Hanzo Commerce - E-Commerce & Payments Platform
Hanzo Commerce is a Go/Gin e-commerce API with SQLite storage, providing products, orders, subscriptions, invoices, usage metering, and multi-currency support (fiat + crypto).
Overview
Hanzo Commerce is a Go/Gin e-commerce API with SQLite storage, providing products, orders, subscriptions, invoices, usage metering, and multi-currency support (fiat + crypto). Powers billing for Hanzo Cloud, Console, and third-party integrations.
NOTE: The repo is hanzoai/commerce (not commerce-api). Built with Go + Gin + SQLite with 35+ API handler directories. For payment processing, Hanzo also has hanzoai/payments — a Rust Hyperswitch fork supporting 50+ payment processors.
Components
| Component | Repo | Stack | Purpose |
|---|---|---|---|
| Commerce API | hanzoai/commerce | Go, Gin, SQLite | Products, orders, subscriptions, billing |
| Payments | hanzoai/payments | Rust (Hyperswitch fork) | 50+ payment processors, routing |
Why Hanzo Commerce?
- Go/Gin backend: Fast, lightweight, easy to deploy
- SQLite storage: Zero-config embedded database
- 35+ endpoint groups: Full e-commerce API surface
- Multi-currency: USD, EUR, USDC, ETH, LUX, BTC
- Usage-based: Metered billing for API calls, compute, storage
- 50+ processors: Via Payments service (Stripe, Adyen, PayPal, crypto, etc.)
- PCI compliant: Card handling via Hanzo Vault
When to use
- Creating products, plans, or pricing tiers
- Processing payments or managing subscriptions
- Usage-based billing for API or compute services
- Multi-currency payments (fiat + crypto)
- Subscription lifecycle management
- Invoice generation and tracking
Quick reference
| Item | Value |
|---|---|
| Commerce API | https://api.hanzo.ai/v1/commerce |
| Commerce Repo | github.com/hanzoai/commerce |
| Payments Repo | github.com/hanzoai/payments |
| Commerce Stack | Go, Gin, SQLite |
| Payments Stack | Rust (Hyperswitch fork) |
| Auth | Bearer token (Hanzo API key) |
Commerce API (Go/Gin)
Handler Groups (35+)
The Commerce API organizes handlers by resource type:
| Group | Endpoints | Description |
|---|---|---|
| products | CRUD | Product catalog management |
| prices | CRUD | Pricing configurations |
| customers | CRUD | Customer management |
| orders | CRUD + status | Order lifecycle |
| subscriptions | CRUD + cancel | Recurring billing |
| invoices | CRUD + pay | Billing statements |
| payments | create + capture | Payment transactions |
| usage | report + query | Metered usage tracking |
| webhooks | CRUD | Event notifications |
| coupons | CRUD | Discount codes |
| tax_rates | CRUD | Tax configuration |
| shipping | CRUD | Shipping methods |
| refunds | create + list | Refund processing |
| disputes | list + respond | Chargeback handling |
| payment_methods | CRUD | Stored payment methods |
| plans | CRUD | Subscription plan templates |
Running Locally
git clone https://github.com/hanzoai/commerce.git
cd commerce
go build ./...
go test ./...
# Start server
go run main.go --port 4242 --db commerce.dbAPI Examples
# Create product
curl -X POST http://localhost:4242/v1/products \
-H "Authorization: Bearer $HANZO_API_KEY" \
-d '{
"name": "AI API Access",
"type": "service",
"description": "Access to Hanzo AI APIs"
}'
# Create price
curl -X POST http://localhost:4242/v1/prices \
-H "Authorization: Bearer $HANZO_API_KEY" \
-d '{
"product_id": "prod_123",
"amount": 2999,
"currency": "usd",
"interval": "month",
"type": "recurring"
}'
# Create subscription
curl -X POST http://localhost:4242/v1/subscriptions \
-H "Authorization: Bearer $HANZO_API_KEY" \
-d '{
"customer_id": "cus_123",
"price_id": "price_456",
"payment_method": "tok_card_789"
}'
# Report usage
curl -X POST http://localhost:4242/v1/usage \
-H "Authorization: Bearer $HANZO_API_KEY" \
-d '{
"subscription_id": "sub_123",
"metric": "api_calls",
"quantity": 1000
}'Payments Service (Rust/Hyperswitch)
The hanzoai/payments repo is a Rust fork of Hyperswitch providing payment processor routing:
Supported Processors (50+)
| Category | Processors |
|---|---|
| Cards | Stripe, Adyen, Braintree, Checkout.com, Worldpay, Cybersource |
| Digital Wallets | Apple Pay, Google Pay, PayPal, Venmo |
| BNPL | Klarna, Affirm, Afterpay |
| Bank | ACH, SEPA, iDEAL, Bancontact |
| Crypto | Coinbase Commerce, BitPay, various on-chain |
| Regional | Boleto, PIX, UPI, GrabPay, GCash |
Smart Routing
# Payment routing configuration
routing:
rules:
- condition: amount > 10000
processor: stripe # High-value → primary processor
fallback: adyen
- condition: currency == "BTC"
processor: coinbase # Crypto → crypto processor
- default:
processor: stripe
fallback: [adyen, checkout]SDK Usage
Python
from hanzoai import Hanzo
client = Hanzo()
# Create a product
product = client.commerce.products.create(
name="AI API Access",
type="service",
)
# Create subscription
sub = client.commerce.subscriptions.create(
customer_id="cus_123",
price_id="price_456",
)
# Report usage
client.commerce.usage.report(
subscription_id=sub.id,
metric="api_calls",
quantity=1000,
)TypeScript
import Hanzo from "hanzoai"
const client = new Hanzo()
const product = await client.commerce.products.create({
name: "AI API Access",
type: "service",
})
const sub = await client.commerce.subscriptions.create({
customerId: "cus_123",
priceId: "price_456",
})Webhooks
| Event | Description |
|---|---|
subscription.created | New subscription activated |
subscription.updated | Plan or quantity changed |
subscription.cancelled | Subscription cancelled |
invoice.created | New invoice generated |
invoice.paid | Invoice successfully paid |
invoice.payment_failed | Payment attempt failed |
payment.succeeded | One-time payment succeeded |
payment.failed | Payment attempt failed |
usage.threshold | Usage crossed configured threshold |
Related Skills
hanzo/hanzo-vault.md- PCI card tokenizationhanzo/hanzo-web3.md- Crypto paymentshanzo/hanzo-cloud.md- Billing dashboard
How is this guide?
Last updated on
Hanzo Commerce - Multi-Tenant E-Commerce and Billing Platform
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...
Hanzo Billing - Subscription and Payment Management Portal
Hanzo Billing is a multi-org billing portal for managing subscriptions, payments, credits, invoices, and usage across the Hanzo ecosystem. Static-exported Next.js 16 app with `@hanzo/ui` components...