# Commerce — Umney Connect API

> For AI agents. Cloudflare-style token: service **Commerce**, permission `commerce:read`.
> **Live** public read-only REST under `/api/v1/commerce/*`. Writes stay on JWT Growth.
> Prefer customer-facing names. Do not expose internal billing catalog IDs.

## Quick facts

| Item | Value |
|---|---|
| Service | Commerce |
| Status | Public Commerce API **live** (read-only) |
| Permission | `commerce:read` |
| Key | `umk_live_commerce_<8>_<secret>` |
| HTML | https://umneyconnect.com/developers/commerce |
| Markdown | https://umneyconnect.com/developers/commerce.md |
| OpenAPI | https://umneyconnect.com/developers/openapi-commerce.json |
| UI | Dashboard → Email Suites / Commerce tabs |
| JWT live | GET\|POST /api/growth/commerce/products\|orders\|loyalty; GET …/statistics |
| Production API | https://umneyconnect.com/api |

## Create access

1. Enable **Commerce** in Billing.
2. Create API token with `commerce:read`.
3. Store secret server-side only.

## Public API (token — live, read-only)

| Method | Path | Permission | Status |
|---|---|---|---|
| GET | `/v1/commerce/products` | commerce:read | **Live** (`?sku=&limit=`) |
| GET | `/v1/commerce/products/{id}` | commerce:read | **Live** |
| GET | `/v1/commerce/orders` | commerce:read | **Live** (`?status=&customerRef=&limit=`) |
| GET | `/v1/commerce/orders/{id}` | commerce:read | **Live** |
| GET | `/v1/commerce/loyalty` | commerce:read | **Live** (`?customerRef=&limit=`) |
| GET | `/v1/commerce/loyalty/{id}` | commerce:read | **Live** |
| GET | `/v1/commerce/statistics` | commerce:read | **Live** |

No public write scopes — do not invent POST/PATCH. Use JWT Growth to create/update catalog data.

## Concepts

| Resource | Description |
|---|---|
| Product | Catalog item (`name`, `sku`, `priceCents`, `currency`, `metadata`) |
| Order | Order snapshot for support context (`status`, `amountCents`, `customerRef`) |
| Loyalty | Points/tier by `customerRef` |
| Statistics | `ordersTotal`, `ordersPaid`, `paidRevenueCents`, `loyaltyAccounts` |

## Agent checklist

1. /llms.txt → this file
2. Enable product → create `commerce:read` token
3. Read products/orders/loyalty for support context
4. Do not invent catalog sync crawlers or public write endpoints