ZeroCommerce API
Base URL: https://zerocommerce-production.up.railway.app
API Prefix: /api/v1
Auth: JWT Bearer (cookie-based)
Source: github.com/AINative-Studio/ZeroCommerce
Custom Domain Pending
zerocommerce.ainative.studio is not yet provisioned. Use zerocommerce-production.up.railway.app until the custom domain is live.
ZeroCommerce is a headless ecommerce API with a product templating engine, semantic product search via ZeroDB, Redis rate limiting, and Stripe payments.
Health Check
curl https://zerocommerce-production.up.railway.app/health
# {"status":"healthy","db":"ok","zerodb":"ok","vector_search":"ok","redis":"ok"}
Authentication
Step 1: Get CSRF Token (browser clients)
GET /api/v1/auth/csrf
Returns {"csrf_token": "..."}. Include as X-CSRF-Token header on all mutating requests from browsers.
Step 2: Register
POST /api/v1/auth/register
Content-Type: application/json
{
"email": "user@example.com",
"password": "securepassword",
"name": "Jane Dev"
}
Step 3: Login
POST /api/v1/auth/login
Content-Type: application/json
{"email": "user@example.com", "password": "securepassword"}
Returns JWT in httpOnly cookie. Pass Authorization: Bearer <token> on API clients.
Other Auth Endpoints
| Method | Path | Description |
|---|---|---|
POST | /api/v1/auth/refresh | Refresh expired JWT |
GET | /api/v1/auth/me | Current user profile |
POST | /api/v1/auth/verify-email | Verify email address |
POST | /api/v1/auth/resend-verification | Resend verification email |
POST | /api/v1/auth/password-reset | Request password reset |
Products
All list endpoints require a trailing slash (e.g. /api/v1/products/).
| Method | Path | Description |
|---|---|---|
GET | /api/v1/products/ | List products |
POST | /api/v1/products/ | Create product (admin) |
GET | /api/v1/products/{product_id} | Get product with template config |
PUT | /api/v1/products/{product_id} | Update product (admin) |
DELETE | /api/v1/products/{product_id} | Delete product (admin) |
POST | /api/v1/products/search/semantic | Semantic search by description |
POST | /api/v1/products/search/compare | Compare similar products |
Semantic Search Example:
POST /api/v1/products/search/semantic
Authorization: Bearer <token>
Content-Type: application/json
{"query": "custom engraved jewelry", "limit": 10}
Templates & Option Sets
Product templates define customization UI. Option sets are the building blocks (e.g. color, size, engraving text).
Templates
| Method | Path | Description |
|---|---|---|
GET | /api/v1/templates/ | List templates |
POST | /api/v1/templates/ | Create template (admin) |
GET | /api/v1/templates/{template_id} | Get template |
PUT | /api/v1/templates/{template_id} | Update template (admin) |
DELETE | /api/v1/templates/{template_id} | Delete template (admin) |
Option Sets
| Method | Path | Description |
|---|---|---|
GET | /api/v1/option-sets/ | List option sets |
POST | /api/v1/option-sets/ | Create option set (admin) |
POST | /api/v1/option-sets/with-options/ | Create option set with options in one call |
GET | /api/v1/option-sets/with-options/ | List option sets with options |
GET | /api/v1/option-sets/{option_set_id} | Get option set |
PUT | /api/v1/option-sets/{option_set_id} | Update option set (admin) |
DELETE | /api/v1/option-sets/{option_set_id} | Delete option set (admin) |
GET | /api/v1/option-sets/{option_set_id}/options/ | List options in set |
POST | /api/v1/option-sets/{option_set_id}/options/ | Add option to set |
GET | /api/v1/option-sets/options/{option_id} | Get individual option |
PUT | /api/v1/option-sets/options/{option_id} | Update option |
DELETE | /api/v1/option-sets/options/{option_id} | Delete option |
Cart
| Method | Path | Description |
|---|---|---|
GET | /api/v1/cart | Get current user cart |
DELETE | /api/v1/cart | Clear cart |
GET | /api/v1/cart/{cart_id} | Get specific cart |
GET | /api/v1/cart/{cart_id}/items | List cart items |
POST | /api/v1/cart/items | Add item (with customization data) |
PUT | /api/v1/cart/items/{item_id} | Update item quantity |
DELETE | /api/v1/cart/items/{item_id} | Remove item |
POST | /api/v1/cart/checkout | Create order from cart |
Add Item with Customization:
{
"product_id": "uuid",
"quantity": 1,
"customization": {
"color": "midnight-blue",
"engraving": "WAGMI",
"size": "L"
}
}
Orders
| Method | Path | Description |
|---|---|---|
GET | /api/v1/me/orders | My order history |
GET | /api/v1/me/orders/{order_id} | My order details |
GET | /api/v1/orders/{order_id} | Get order (admin or owner) |
Order statuses: pending → confirmed → processing → shipped → delivered / cancelled
Payments (Stripe)
| Method | Path | Description |
|---|---|---|
POST | /api/v1/payments/checkout | Create Stripe checkout session |
GET | /api/v1/payments/checkout | Get checkout session |
GET | /api/v1/payments/history | Payment history |
GET | /api/v1/payments/subscription | Get subscription |
POST | /api/v1/payments/subscription | Create subscription |
POST | /api/v1/payments/subscription/cancel | Cancel subscription |
GET | /api/v1/payments/portal | Get Stripe billing portal |
POST | /api/v1/payments/portal-session | Create billing portal session |
POST | /api/v1/webhooks/stripe | Stripe webhook handler |
POST | /api/v1/webhooks/paypal | PayPal webhook handler |
Webhooks
Subscribe to ecommerce events (order placed, payment received, etc).
| Method | Path | Description |
|---|---|---|
POST | /api/v1/webhooks/subscribe | Create webhook subscription |
GET | /api/v1/webhooks/subscriptions | List subscriptions |
DELETE | /api/v1/webhooks/subscriptions/{subscription_id} | Delete subscription |
GET | /api/v1/webhooklogs | Webhook delivery log |
GET | /api/v1/webhooklogs/dashboard | Webhook delivery dashboard |
GET | /api/v1/admin/webhooks/failed | Failed deliveries (admin) |
POST | /api/v1/admin/webhooks/failed/{failure_id}/replay | Replay failed delivery (admin) |
Customization Sessions
Track product customization state across sessions.
| Method | Path | Description |
|---|---|---|
POST | /api/v1/customization-sessions | Create session |
GET | /api/v1/customization-sessions/{product_id} | Get session for product |
PUT | /api/v1/customization-sessions/{product_id} | Replace session |
PATCH | /api/v1/customization-sessions/{product_id} | Partial update session |
POST | /api/v1/sessions | Create generic session |
GET | /api/v1/sessions/{session_key} | Get session by key |
File Uploads
| Method | Path | Description |
|---|---|---|
POST | /api/v1/files/upload | Upload file |
POST | /api/v1/files/products/{product_id}/images | Upload product image |
GET | /api/v1/files/ | List files |
GET | /api/v1/files/{file_id} | Get file metadata |
GET | /api/v1/files/{file_id}/download | Download file |
POST | /api/v1/files/{file_id}/presigned-url | Generate presigned URL |
DELETE | /api/v1/files/{file_id} | Delete file |
Reports
| Method | Path | Description |
|---|---|---|
GET | /api/v1/reports/sales | Sales analytics report |
Admin
| Method | Path | Description |
|---|---|---|
GET/POST | /api/v1/admin/api-keys | Manage API keys |
DELETE | /api/v1/admin/api-keys/{prefix} | Revoke API key |
GET | /api/v1/admin/signing-keys | List JWT signing keys |
POST | /api/v1/admin/signing-keys/rotate | Rotate signing key |
POST | /api/v1/admin/signing-keys/retire | Retire a signing key |
GET | /api/v1/admin/jwt-keys/status | JWT keyring status |
GET | /api/v1/admin/audit | Admin audit log |
POST | /api/v1/admin/users/{user_id}/erase | GDPR erasure (admin) |
User / GDPR
| Method | Path | Description |
|---|---|---|
GET | /api/v1/users/me/export | Export all user data |
DELETE | /api/v1/users/me | Delete account (right to erasure) |
GET | /api/v1/users/me/onboarding | Onboarding status |
Rate Limits
| Tier | Requests/min |
|---|---|
| Anonymous | 30–120 (varies by endpoint) |
| Authenticated | 60–240 |
| Admin | 120–240 |
Returns X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After headers on 429.