Files
skills/public/hanzo-commerce.md

19 KiB

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?

  • Full e-commerce platform: Products, variants, collections, carts, orders, checkout, fulfillment, shipping, tax, inventory, returns, disputes
  • Multi-tenant: Namespace-isolated per organization with per-org databases
  • 4 database backends: SQLite (embedded, dev), PostgreSQL (production), MongoDB/FerretDB, ClickHouse (analytics)
  • 6 payment providers: Stripe, Square, PayPal, Authorize.net, Braintree, Adyen + crypto (Bitcoin, Ethereum)
  • Usage-based billing: Ledger, credit grants, metering, tiered pricing, Temporal workflows
  • AI-powered: Product recommendations via vector search (sqlite-vec / pgvector / Qdrant)
  • Event-driven: NATS/JetStream pub/sub + ClickHouse analytics pipeline
  • KMS-first secrets: All payment credentials via KMS (kms.hanzo.ai), zero plaintext
  • IAM integrated: Dual auth -- legacy access tokens + hanzo.id OIDC JWT
  • OpenAPI spec: 88KB spec at /openapi.yaml covering all endpoints

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:

  • Working with the commerce Go codebase or API
  • Configuring payment providers (Stripe, Square, PayPal, etc.)
  • Setting up billing, subscriptions, or usage metering
  • Understanding the multi-tenant data model
  • Deploying commerce to K8s
  • Integrating commerce with other Hanzo services (IAM, KMS, Console)
  • Working with the checkout flow or Stripe Connect

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

  • Namespace-based: Organization.Name IS the namespace
  • Per-org SQLite databases: {COMMERCE_DIR}/orgs/{orgName}/data.db
  • Per-org PostgreSQL: tenant_id column isolation
  • middleware.Namespace() sets context namespace for all downstream queries
  • "platform" org returns empty namespace (admin bypass, documented)
  • Dual auth: legacy access tokens (org-bound) + IAM JWT (OIDC/JWKS via hanzo.id)

Hook System

Extensible lifecycle hooks (Hanzo Base-compatible pattern):

  • OnBootstrap -- app initialization
  • OnServe -- before HTTP server starts
  • OnRouteSetup -- add custom routes
  • OnTerminate -- graceful shutdown
  • Hook[T], TaggedHook[T], Resolver -- typed hook registry

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

  • Test: On PR and push to main -- go vet, unit tests (billing, models, payment), Ginkgo suites
  • Deploy: On push to main or tag -- reusable hanzoai/.github Docker build workflow, deploys to hanzo namespace

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
  • hanzo/hanzo-id.md -- IAM and OIDC authentication (hanzo.id)
  • hanzo/hanzo-kms.md -- Secret management (kms.hanzo.ai)
  • hanzo/hanzo-console.md -- Admin console
  • hanzo/hanzo-platform.md -- PaaS deployment platform
  • hanzo/hanzo-cloud.md -- Cloud dashboard

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