---
title: "ZeroCommerce API"
description: "Ecommerce API with product templates, semantic search, and Stripe payments"
canonical: "https://docs.ainative.studio/docs/business-ops/zerocommerce"
last-updated: "2026-09-23T01:51:08.820Z"
---

# ZeroCommerce API

Source: https://docs.ainative.studio/docs/business-ops/zerocommerce

> Ecommerce API with product templates, semantic search, and Stripe payments

## ZeroCommerce API

**Base URL:** `https://zerocommerce.ainative.studio`  
**API Prefix:** `/api/v1`  
**Auth:** JWT Bearer (cookie-based)  
**Source:** [github.com/AINative-Studio/ZeroCommerce](https://github.com/AINative-Studio/ZeroCommerce)

:::note Custom Domain Pending
`zerocommerce.ainative.studio` is not yet provisioned. Use `zerocommerce.ainative.studio` 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.

:::tip Health Check
```bash
curl https://zerocommerce.ainative.studio/health
## {"status":"healthy","db":"ok","zerodb":"ok","vector_search":"ok","redis":"ok"}
```
:::

## Authentication

### Step 1: Get CSRF Token (browser clients)

```http
GET /api/v1/auth/csrf
```

Returns `{"csrf_token": "..."}`. Include as `X-CSRF-Token` header on all mutating requests from browsers.

### Step 2: Register

```http
POST /api/v1/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securepassword",
  "name": "Jane Dev"
}
```

### Step 3: Login

```http
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:**

```http
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:**

```json
{
  "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.