hanzo-commerce

Hanzo Commerce is the core product of Hanzo AI -- a multi-tenant e-commerce platform that powers billing, payments, subscriptions, storefronts, and API usage metering for the entire Hanzo ecosystem and external customers.

Hanzo Commerce - Multi-Tenant E-Commerce and Billing Platform

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-platform.md, hanzo/hanzo-id.md, hanzo/hanzo-kms.md, hanzo/hanzo-console.md

Overview

Hanzo Commerce is the core product of Hanzo AI -- a multi-tenant e-commerce platform that powers billing, payments, subscriptions, storefronts, and API usage metering for the entire Hanzo ecosystem and external customers. It is a standalone Go binary (Cobra CLI + Gin HTTP) with 100+ data models, 4 database backends, 6 payment providers, 25+ third-party integrations, and a complete OpenAPI 3.0 specification.

Live at: https://commerce.hanzo.ai | API: https://api.hanzo.ai/v1 | Version: v1.36.5

Why Hanzo Commerce?

Tech Stack

| Layer | Technology | |-------|-----------| | Language | Go 1.26, single binary | | HTTP | Gin web framework | | CLI | Cobra command framework | | Databases | SQLite + sqlite-vec, PostgreSQL + pgvector, MongoDB, ClickHouse | | KV Cache | Redis/Valkey (hanzoai/kv-go) | | Search | Meilisearch (hanzoai/search-go) | | Vector | Qdrant (hanzoai/vector-go) | | Object Storage | Hanzo S3 (hanzoai/storage-go) | | Pub/Sub | NATS + JetStream (hanzoai/pubsub-go) | | Tasks | Temporal SDK (billing workflows) | | ORM | hanzoai/orm v0.3.1 (generic CRUD, mixin.Model[T]) | | Analytics | ClickHouse (hanzoai/datastore-go) | | Auth | hanzo.id OIDC + legacy access tokens | | Secrets | KMS (Hanzo KMS-compatible REST) | | Crypto | luxfi/crypto, luxfi/geth, btcsuite | | Image | ghcr.io/hanzoai/commerce:latest | | Testing | Ginkgo v2 + Gomega |

Repo

github.com/hanzoai/commerce -- Go module github.com/hanzoai/commerce

When to use

Use this skill when:

Hard requirements

  1. CGO_ENABLED=1 for all builds (SQLite requires it)
  2. KMS credentials for payment provider access in production
  3. IAM (hanzo.id) for JWT-based authentication
  4. PVC is ReadWriteOnce -- deployment MUST use strategy: Recreate, not RollingUpdate
  5. Never store payment credentials in plaintext -- KMS is the single source of truth

Quick reference

| Item | Value | |------|-------| | API | https://api.hanzo.ai/v1 (via gateway) | | Direct | https://commerce.hanzo.ai (port 8001) | | Auth | Bearer token (org API key or IAM JWT) | | Image | ghcr.io/hanzoai/commerce:latest | | K8s | hanzo namespace, commerce deployment, Recreate strategy | | Port | 8001 (container), 8090 (default local) | | Data | PVC commerce-data (10Gi, do-block-storage) | | KMS secret | commerce-kms-auth (client-id, client-secret, project-id) | | Repo | github.com/hanzoai/commerce | | OpenAPI | /openapi.yaml (88KB, 3.0.3) | | CI | Test on PR + Docker build/deploy on push to main |

Architecture

 +-----------------------+
 | API Gateway |
 | (api.hanzo.ai) |
 +----------+------------+
 |
 +----------v------------+
 | Commerce App |
 | (Cobra + Gin) |
 +------------------------+
 | HTTP Routes (/api/v1) |
 | Middleware Chain |
 | Hook System |
 +----+------+------+----+
 | | |
 +----------+ +---+---+ +----------+
 | | | |
 +--------v---+ +-----v--+ +-v--------+ +--v--------+
 | SQLite/PG | | Redis | | NATS | | ClickHouse|
 | (per-org) | | (cache)| | (events) | | (analytics|
 +------------+ +--------+ +----------+ +-----------+
 |
 +--------v-----------+
 | KMS | Meilisearch|
 | (creds)| (search) |
 +--------+------------+

Multi-Tenancy Model

Hook System

Extensible lifecycle hooks (Hanzo Base-compatible pattern):

Directory Structure

commerce/
 commerce.go Main App framework (Config, Bootstrap, Routes, Serve, Shutdown)
 cmd/commerce/ CLI entry point (main.go)

 api/ HTTP Handlers (30+ resource groups)
 accesstoken/ API token management
 account/ User account (login, register, profile)
 affiliate/ Affiliate program
 auth/ OAuth2 token endpoint
 billing/ Balance, usage, deposits, credits
 cart/ Shopping cart
 cdn/ CDN/asset serving
 checkout/ Checkout sessions (Stripe Checkout)
 contributor/ Contributor management
 counter/ Atomic counters
 coupon/ Coupon codes
 customergroup/ Customer segmentation
 dashv2/ Dashboard v2 API
 data/ Generic data API
 deploy/ Deploy management
 form/ Form submissions
 fulfillment/ Order fulfillment
 inventory/ Inventory tracking
 library/ Content library
 namespace/ Namespace management (admin-only)
 notification/ Notifications
 order/ Order CRUD
 organization/ Org management
 pricing/ Price lists and rules
 promotion/ Promotions
 referrer/ Referral tracking
 region/ Geographic regions
 review/ Product reviews
 search/ Search proxy
 store/ Storefront
 subscription/ Subscriptions
 tax/ Tax calculation
 transaction/ Transaction records
 user/ User management
 xd/ Cross-domain helpers

 models/ Data Models (100+ entities)
 product/ Product, variant, collection
 order/ Order, lineitem, fulfillmentmodel
 cart/ Shopping cart
 subscription/ Subscription, subscriptionitem, subscriptionschedule
 plan/ Subscription plans
 payment/ Payments, paymentintent, paymentmethod
 invoice/ Invoices
 billing*/ billingevent, billinginvoice
 credit/ Credits, creditgrant
 coupon/ Coupons, discount, promotion, promotionrule, redemption
 user/ User accounts
 organization/ Multi-tenant orgs
 token/ API tokens, oauthtoken, publishableapikey
 wallet/ Crypto wallets
 cryptobalance/ Crypto balances
 cryptopaymentintent/ Crypto payment intents
 networktoken/ Network tokens
 tokensale/ Token sales
 affiliate/ Affiliates
 referral/ Referral programs
 inventory/ Inventory, inventorylevel, stocklocation
 shippingoption/ Shipping options, profiles, rates
 fulfillment*/ Fulfillment providers, sets
 region/ Regions, geozones, servicezones
 taxrate/ Tax rates, rules, providers, regions
 price/ Price, pricelist, priceset, pricepreference, pricerule, pricingrule
 meter/ Usage metering
 usagewatermark/ Usage watermarks
 spendalert/ Spend alerts
 balancetransaction/ Balance transactions
 dispute/ Payment disputes
 refund/ Refunds
 fee/ Fees
 payout/ Payouts
 transfer/ Transfers
 review/ Product reviews
 form/ Form submissions
 webhook/ Webhooks, webhookendpoint
 notification/ Notifications
 types/ Shared types (currency, etc.)
 mixin/ Generic Model[T] mixin with CRUD
 migrations/ Schema migrations
 fixtures/ Test fixtures

 billing/ Billing Engine
 credit/ Credit system
 engine/ Billing calculation engine
 ledger/ Double-entry ledger
 tier/ Tiered pricing
 workflows/ Temporal billing workflows

 payment/ Payment Processing
 processor/ Payment processor interface
 providers/ Provider implementations
 adyen/ Adyen
 braintree/ Braintree
 lemonsqueezy/ Lemon Squeezy
 paypal/ PayPal
 recurly/ Recurly
 router/ Payment routing logic

 thirdparty/ Third-Party Integrations (25+)
 authorizenet/ Authorize.net
 bitcoin/ Bitcoin payments
 ethereum/ Ethereum payments
 square/ Square payments
 paypal/ PayPal (legacy)
 kms/ KMS client (secret management)
 cardconnect/ CardConnect
 cloudflare/ Cloudflare CDN
 facebook/ Facebook integration
 indiegogo/ Indiegogo crowdfunding
 mailchimp/ Mailchimp email
 mandrill/ Mandrill transactional email
 mercury/ Mercury banking
 mpc/ Multi-party computation
 netlify/ Netlify deployment
 reamaze/ Reamaze support
 recaptcha/ reCAPTCHA
 sendgrid/ SendGrid email
 shipstation/ ShipStation fulfillment
 shipwire/ Shipwire fulfillment
 smtprelay/ SMTP relay
 wire/ Wire transfers
 woopra/ Woopra analytics
 bigquery/ BigQuery analytics
 paymentmethods/ Payment method registry

 db/ Database Backends
 sqlite.go SQLite + sqlite-vec (embedded, per-org)
 postgres.go PostgreSQL + pgvector (production)
 mongo.go MongoDB (alternative)
 datastore.go ClickHouse via hanzoai/datastore-go (analytics)
 db.go Manager, interface, pool
 query.go Query builder (PascalCase -> camelCase auto-conversion)
 model.go Generic model interface
 serialize.go JSON serialization

 datastore/ Cloud Datastore abstraction layer
 datastore.go Core datastore interface
 get.go, put.go CRUD operations
 delete.go Delete operations
 key.go, key/ Key generation
 query.go, query/ Query builder
 parallel/ Parallel query execution

 infra/ Infrastructure Clients
 infra.go Manager (connect, health, close)
 kv.go Redis/Valkey client
 search.go Meilisearch client
 vector.go Qdrant vector client
 storage.go Hanzo S3 storage client
 pubsub.go NATS/JetStream client
 tasks.go Temporal task client
 locking.go Distributed locking

 hooks/ Hook System
 hooks.go Registry, Hook[T] generic
 tagged.go TaggedHook[T]
 event.go Event types

 events/ Event System
 publisher.go NATS/JetStream publisher
 client.go HTTP analytics client
 bootstrap.go Stream bootstrap
 schema.go Event schema

 auth/ Authentication
 auth.go Auth helpers
 iam.go IAM (hanzo.id) OIDC/JWKS validation
 password/ Password hashing

 middleware/ HTTP Middleware
 accesstoken.go API token auth
 iammiddleware/ IAM JWT validation
 oauthmiddleware/ OAuth middleware
 organization.go Org resolution
 cache.go Cache headers
 cors.go CORS
 error.go Error handler
 logger.go Request logging

 ai/ AI Features
 recommendations.go Vector-based product recommendations

 email/ Email System
 email.go Email sending
 emails.go Template rendering
 subscribe.go Mailing list
 tasks/ Async email tasks

 cron/ Background Jobs
 payout/ Payout processing
 tasks/ Scheduled tasks

 k8s/ Kubernetes Manifests
 deployment.yaml Deployment (Recreate strategy, 1 replica)
 service.yaml ClusterIP service (port 8001)
 api-ingress.yaml Ingress for commerce.hanzo.ai
 configmap.yaml Environment config
 pvc.yaml PersistentVolumeClaim (10Gi)
 kms-auth-secret.yaml KMS auth credentials
 frontend-admin.yaml Admin UI deployment
 frontend-site.yaml Marketing site deployment
 frontend-store.yaml Storefront deployment

 config/ Environment configs (dev, staging, production, sandbox)
 templates/ Email and page templates
 test/ Ginkgo test suites
 test-integration/ Integration tests
 demo/ Demo data
 deploy/ Deployment scripts
 docs/ Documentation
 scripts/ Utility scripts
 openapi.yaml OpenAPI 3.0.3 specification (88KB)
 bench_test.go Benchmarks

Running

# Development (SQLite, local)
go run cmd/commerce/main.go serve --dev

# Production (PostgreSQL)
SQL_URL=postgresql://user:pass@host:5432/commerce \
 KMS_ENABLED=true KMS_URL=http://kms:8080 \
 ./commerce serve 0.0.0.0:8001

# Seed an organization with plans and API tokens
./commerce seed bootnode

# Docker
docker build --platform linux/amd64 -t ghcr.io/hanzoai/commerce:latest .

Environment Variables

| Variable | Default | Purpose | |----------|---------|---------| | COMMERCE_DIR | ./commerce_data | Data directory for SQLite DBs | | COMMERCE_SECRET | change-me-in-production | Encryption secret | | COMMERCE_HTTP | 127.0.0.1:8090 | Listen address | | COMMERCE_DEV | false | Development mode | | SQL_URL | - | PostgreSQL DSN (production) | | KV_URL | - | Redis/Valkey URL | | SEARCH_URL | - | Meilisearch URL | | VECTOR_URL | - | Qdrant URL | | S3_URL | - | Hanzo S3 URL | | PUBSUB_URL | - | NATS URL | | TASKS_URL | - | Temporal URL | | DATASTORE_URL | - | ClickHouse DSN | | DOC_URL | - | MongoDB URL | | KMS_ENABLED | false | Enable KMS secret management | | KMS_URL | - | KMS base URL | | KMS_CLIENT_ID | - | KMS Universal Auth client ID | | KMS_CLIENT_SECRET | - | KMS Universal Auth client secret | | KMS_PROJECT_ID | - | KMS project ID | | KMS_ENVIRONMENT | prod | KMS environment | | IAM_ENABLED | true | Enable IAM JWT validation | | IAM_ISSUER | https://hanzo.id | IAM issuer URL | | IAM_CLIENT_ID | - | IAM client ID | | IAM_CLIENT_SECRET | - | IAM client secret | | ANALYTICS_ENDPOINT | - | Analytics collector HTTP URL | | INSIGHTS_ENABLED | false | Hanzo Insights product analytics | | ANALYTICS_ENABLED | false | Umami-like web analytics |

API Endpoints

Core Commerce

| Endpoint | Method | Purpose | |----------|--------|---------| | /api/v1/store | GET/POST | Storefront listing/create | | /api/v1/product | CRUD | Products | | /api/v1/variant | CRUD | Product variants | | /api/v1/collection | CRUD | Product collections | | /api/v1/cart | CRUD | Shopping carts | | /api/v1/order | CRUD | Orders | | /api/v1/checkout | POST | Payment processing | | /api/v1/checkout/sessions | POST | Stripe Checkout sessions | | /api/v1/subscription | CRUD | Subscriptions | | /api/v1/coupon | CRUD | Coupon codes | | /api/v1/promotion | CRUD | Promotions | | /api/v1/inventory | CRUD | Inventory tracking | | /api/v1/fulfillment | CRUD | Order fulfillment | | /api/v1/review | CRUD | Product reviews |

Billing

| Endpoint | Method | Purpose | |----------|--------|---------| | /api/v1/billing/balance | GET | Balance by user + currency (cents) | | /api/v1/billing/balance/all | GET | All currency balances | | /api/v1/billing/usage | POST | Record API usage (withdraw) | | /api/v1/billing/deposit | POST | Create deposit transaction | | /api/v1/billing/credit | POST | Grant starter credit ($5, 30-day expiry) | | /api/v1/billing/zap | POST | Clear balance |

Analytics

| Endpoint | Method | Purpose | |----------|--------|---------| | /api/v1/analytics/event | POST | Single event | | /api/v1/analytics/events | POST | Batch events | | /api/v1/analytics/identify | POST | User identification | | /api/v1/analytics/pixel.gif | GET | Pixel tracking | | /api/v1/analytics/ai/message | POST | AI message event | | /api/v1/analytics/ai/completion | POST | AI completion event |

Auth & Admin

| Endpoint | Method | Purpose | |----------|--------|---------| | /auth | POST | OAuth2 password grant | | /api/v1/account | GET/POST | User account | | /api/v1/user | CRUD | User management (admin) | | /api/v1/organization | CRUD | Organization management | | /api/v1/namespace | CRUD | Namespace management (admin-only, authed) | | /api/v1/accesstoken | CRUD | API token management | | /health | GET | Health check |

KMS Secret Management

All payment credentials are stored in KMS. No fallback to org-stored fields.

Secret path convention:

/tenants/{orgName}/stripe/STRIPE_LIVE_ACCESS_TOKEN
/tenants/{orgName}/stripe/STRIPE_TEST_ACCESS_TOKEN
/tenants/{orgName}/stripe/STRIPE_PUBLISHABLE_KEY
/tenants/{orgName}/square/SQUARE_PRODUCTION_ACCESS_TOKEN
/tenants/{orgName}/square/SQUARE_PRODUCTION_LOCATION_ID
/tenants/{orgName}/square/SQUARE_PRODUCTION_APPLICATION_ID
/tenants/{orgName}/authorizenet/AUTHORIZENET_LIVE_LOGIN_ID
/tenants/{orgName}/paypal/PAYPAL_LIVE_EMAIL

Hydration: kms.Hydrate(ctx, org) populates all 25 provider credential fields. Called once after org resolution. Cache: 5min TTL, extends to 30min on KMS failure.

K8s: Single "secret zero" (commerce-kms-auth) holds KMS Universal Auth credentials.

Checkout Sessions

POST /api/v1/checkout/sessions -- public endpoint (no token auth).

Request:

{
 "company": "acme",
 "providerHint": "stripe",
 "currency": "usd",
 "org": "acme",
 "customer": { "email": "[email protected]" },
 "items": [{ "productId": "prod_xyz", "quantity": 1 }],
 "successUrl": "https://acme.com/success",
 "cancelUrl": "https://acme.com/cancel"
}

Response: { "checkoutUrl": "https://checkout.stripe.com/...", "sessionId": "cs_..." }

Org resolved from X-Hanzo-Org header or request body. Per-request Stripe client (multi-tenant safe).

Cross-Compilation

# Build for linux/amd64 from macOS (zig cross-compile for CGO)
go mod vendor
CC="zig cc -target x86_64-linux-musl" CXX="zig c++ -target x86_64-linux-musl" \
 CGO_ENABLED=1 GOOS=linux GOARCH=amd64 \
 go build -mod=vendor -ldflags="-s -w -extldflags '-static'" \
 -o commerce ./cmd/commerce/main.go

# Push to GHCR
docker build --platform linux/amd64 -t ghcr.io/hanzoai/commerce:latest .
docker push ghcr.io/hanzoai/commerce:latest

CI/CD

Gotchas

| Issue | Detail | |-------|--------| | SQLite requires CGO | Always CGO_ENABLED=1, needs gcc/musl-dev | | PVC ReadWriteOnce | Deployment MUST use Recreate strategy | | Filter field names | PascalCase (Go struct) auto-converts to camelCase JSON in queries | | Boolean omitempty | false with omitempty may be NULL in JSON -- COALESCE handles it | | Healthcheck | Use curl -f, not wget --spider (Gin only handles GET) | | Colima cross-compile | QEMU crashes HTTP/2 on ARM Mac -- use zig cc instead | | Platform org bypass | "platform" org returns empty namespace (admin bypass, intentional) | | Global entities | Organization, User, Token use DefaultNamespace = true by design |

Related Skills

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: e-commerce, billing, payments, subscriptions, multi-tenant, API Prerequisites: Go, REST APIs, Kubernetes basics