Files
skills/public/hanzo-commerce-api.md

6.4 KiB

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?

  • 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.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
  • hanzo/hanzo-vault.md - PCI card tokenization
  • hanzo/hanzo-web3.md - Crypto payments
  • hanzo/hanzo-cloud.md - Billing dashboard

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