API reference
The SDK wraps every endpoint. You can also call the API directly.
Authentication
curl https://api.commerceforai.com/v1/orders \
-H "Authorization: Bearer $COMMERCEFORAI_API_KEY"Conventions
- Idempotency. Send
Idempotency-Keyon POSTs. A repeat with the same key replays the first response. Reusing a key with a different body returnsidempotency_error. - Pagination.
?limit=(max 100) and?starting_after=<id>. Lists return{ object: "list", data, has_more }. - Errors.
{ error: { type, message, param? } }with typesinvalid_request,authentication_error,not_found,conflict,out_of_stock,stripe_error,idempotency_error,rate_limited. - Request ids. Every response has an
x-request-idheader. Include it when you contact support.
Store
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/store | Store settings, connected providers, feed URLs |
| PATCH | /v1/store | Name, tax, default success/cancel URLs |
| PUT | /v1/store/shipping | Connect EasyPost or Shippo |
| PUT / DELETE | /v1/store/fulfillment | Connect / disconnect Printful or Printify |
| PUT / DELETE | /v1/store/emails | Customer emails via Resend |
| PUT | /v1/store/storefront | Product URL template, feeds, agent access |
Catalog
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/products | Create a product with variants |
| GET | /v1/products | List; filter with active and metadata[key]=value |
| GET / PATCH / DELETE | /v1/products/:id | Get, update, archive |
| POST | /v1/products/:id/variants | Add a variant |
| PATCH | /v1/variants/:id | Price, SKU, weight, print-on-demand mapping |
| GET | /v1/inventory | Tracked stock, lowest first |
| POST | /v1/variants/:id/inventory | Adjust (+/−) or set stock |
Checkout & orders
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/checkouts | Reserve stock and create a Stripe Checkout |
| GET | /v1/checkouts/:id | Checkout status and resulting order |
| GET | /v1/orders | List; filter by status |
| GET / PATCH | /v1/orders/:id | By id or number; notes and metadata |
| POST | /v1/orders/:id/fulfill | Mark shipped with tracking |
| POST | /v1/orders/:id/refund | Refund through Stripe, optional restock |
| POST | /v1/orders/:id/submit-fulfillment | Send to print-on-demand now |
Shipping & returns
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/orders/:id/shipping-rates | Live rates, cheapest first |
| POST / GET | /v1/orders/:id/labels | Buy a label / list labels |
| POST | /v1/orders/:id/returns | Open a return |
| GET | /v1/returns | List returns |
| POST | /v1/returns/:id/approve | reject | receive | Return lifecycle |
Events
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/events | Ordered event log (cursor: after) |
| POST / GET / DELETE | /v1/webhook-endpoints | Manage webhook endpoints |
| GET | /v1/emails | Customer email log |