Commerce
Quick Start
Get up and running with Hanzo Commerce in minutes
This guide walks you through setting up Hanzo Commerce and making your first API calls.
Prerequisites
- Go 1.21 or later
- Docker and Docker Compose
- A Hanzo API key (get one at hanzo.ai)
Installation
Option 1: Docker (Recommended)
# Clone the repository
git clone https://github.com/hanzoai/commerce.git
cd commerce
# Start with Docker Compose
docker compose up -dThe API will be available at http://localhost:8000.
Option 2: Local Development
# Clone the repository
git clone https://github.com/hanzoai/commerce.git
cd commerce
# Install dependencies
go mod download
# Run the development server
make devConfiguration
Create a .env file in the project root:
# API Configuration
HANZO_ENV=development
HANZO_API_PORT=8000
# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/commerce
# Authentication (Hanzo ID)
HANZO_CLIENT_ID=your_client_id
HANZO_CLIENT_SECRET=your_client_secret
# Payments (Stripe)
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
# Analytics (Optional)
CLICKHOUSE_URL=http://localhost:8123Your First API Call
Authenticate
Get an access token using your API credentials:
curl -X POST https://api.hanzo.ai/auth/token \
-H "Content-Type: application/json" \
-d '{
"client_id": "your_client_id",
"client_secret": "your_client_secret",
"grant_type": "client_credentials"
}'Response:
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 3600
}Create a Product
curl -X POST https://api.hanzo.ai/product \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Premium Widget",
"slug": "premium-widget",
"price": 2999,
"currency": "USD",
"description": "A high-quality widget for all your needs"
}'Create an Order
curl -X POST https://api.hanzo.ai/order \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"productId": "prod_abc123",
"quantity": 2
}
],
"shippingAddress": {
"line1": "123 Main St",
"city": "San Francisco",
"state": "CA",
"postalCode": "94102",
"country": "US"
}
}'Process Payment
curl -X POST https://api.hanzo.ai/checkout/authorize \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"orderId": "order_xyz789",
"paymentMethod": "stripe",
"token": "tok_visa"
}'Using the SDK
JavaScript/TypeScript
npm install @hanzo/commerceimport { Commerce } from '@hanzo/commerce'
const commerce = new Commerce({
apiKey: 'your_api_key',
environment: 'production'
})
// Create a product
const product = await commerce.products.create({
name: 'Premium Widget',
price: 2999,
currency: 'USD'
})
// Create an order
const order = await commerce.orders.create({
items: [{ productId: product.id, quantity: 2 }],
shippingAddress: {
line1: '123 Main St',
city: 'San Francisco',
state: 'CA',
postalCode: '94102',
country: 'US'
}
})
// Process payment
await commerce.checkout.authorize({
orderId: order.id,
paymentMethod: 'stripe',
token: 'tok_visa'
})Go
package main
import (
"context"
"github.com/hanzoai/commerce/sdk"
)
func main() {
client := sdk.NewClient("your_api_key")
ctx := context.Background()
// Create a product
product, err := client.Products.Create(ctx, &sdk.ProductInput{
Name: "Premium Widget",
Price: 2999,
Currency: "USD",
})
if err != nil {
panic(err)
}
// Create an order
order, err := client.Orders.Create(ctx, &sdk.OrderInput{
Items: []sdk.OrderItem{
{ProductID: product.ID, Quantity: 2},
},
})
if err != nil {
panic(err)
}
}Next Steps
How is this guide?
Last updated on