Hanzo
Hanzo Skills Reference

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

ComponentRepoStackPurpose
Commerce APIhanzoai/commerceGo, Gin, SQLiteProducts, orders, subscriptions, billing
Paymentshanzoai/paymentsRust (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

ItemValue
Commerce APIhttps://api.hanzo.ai/v1/commerce
Commerce Repogithub.com/hanzoai/commerce
Payments Repogithub.com/hanzoai/payments
Commerce StackGo, Gin, SQLite
Payments StackRust (Hyperswitch fork)
AuthBearer token (Hanzo API key)

Commerce API (Go/Gin)

Handler Groups (35+)

The Commerce API organizes handlers by resource type:

GroupEndpointsDescription
productsCRUDProduct catalog management
pricesCRUDPricing configurations
customersCRUDCustomer management
ordersCRUD + statusOrder lifecycle
subscriptionsCRUD + cancelRecurring billing
invoicesCRUD + payBilling statements
paymentscreate + capturePayment transactions
usagereport + queryMetered usage tracking
webhooksCRUDEvent notifications
couponsCRUDDiscount codes
tax_ratesCRUDTax configuration
shippingCRUDShipping methods
refundscreate + listRefund processing
disputeslist + respondChargeback handling
payment_methodsCRUDStored payment methods
plansCRUDSubscription 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.db

API 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+)

CategoryProcessors
CardsStripe, Adyen, Braintree, Checkout.com, Worldpay, Cybersource
Digital WalletsApple Pay, Google Pay, PayPal, Venmo
BNPLKlarna, Affirm, Afterpay
BankACH, SEPA, iDEAL, Bancontact
CryptoCoinbase Commerce, BitPay, various on-chain
RegionalBoleto, 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

EventDescription
subscription.createdNew subscription activated
subscription.updatedPlan or quantity changed
subscription.cancelledSubscription cancelled
invoice.createdNew invoice generated
invoice.paidInvoice successfully paid
invoice.payment_failedPayment attempt failed
payment.succeededOne-time payment succeeded
payment.failedPayment attempt failed
usage.thresholdUsage crossed configured threshold
  • hanzo/hanzo-vault.md - PCI card tokenization
  • hanzo/hanzo-web3.md - Crypto payments
  • hanzo/hanzo-cloud.md - Billing dashboard

How is this guide?

Last updated on

On this page