hanzo-commerce-api

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).

Hanzo Commerce - E-Commerce & Payments Platform

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-vault.md, hanzo/hanzo-web3.md, hanzo/hanzo-cloud.md

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?

When to use

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

| 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

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: billing, payments, subscriptions, commerce, go, hyperswitch Prerequisites: Go or API concepts, payment processing basics