Ecommerce

Manage products, orders, coupons, collections, and customers. Ecommerce endpoints are scoped to a store (:storeId). For unauthenticated public browsing, see Public Storefront.

Authentication

All store-scoped management endpoints require a valid JWT or API key. The public storefront endpoints require no authentication.

Endpoints

POST/stores/:storeId/productsCreate a product

GET/stores/:storeId/productsList products in a store

GET/products/:idGet a single product

PATCH/products/:idUpdate a product

DELETE/products/:idSoft-delete a product

POST/stores/:storeId/ordersCreate an order

GET/stores/:storeId/ordersList orders for a store

GET/orders/:idGet order details

PATCH/orders/:id/fulfillMark an order as fulfilled

PATCH/orders/:id/cancelCancel an order

POST/stores/:storeId/couponsCreate a discount coupon

GET/stores/:storeId/collectionsList product collections

GET/stores/:storeId/customersList customers for a store

Products

POST/stores/:storeId/productsCreate a product

Request Body

{
"title": "Wireless Headphones Pro",
"description": "Premium noise-canceling wireless headphones",
"type": "physical",
"price": 14999,
"sku": "WHP-001",
"status": "active"
}

Field	Type	Required	Description
`title`	string	Yes	Product name (max 500 chars)
`description`	string	No	Product description
`type`	string	Yes	`physical` or `digital`
`price`	number	Yes	Price in cents (min: 1)
`sku`	string	No	Stock keeping unit
`status`	string	No	`draft` or `active` (default `draft`)

Update a Product

PATCH/products/:idUpdate a product

Request Body

{
"title": "Wireless Headphones Pro (2025)",
"description": "Updated description",
"status": "archived"
}

Field	Type	Required	Description
`title`	string	No	Product name (max 500 chars)
`description`	string	No	Product description
`status`	string	No	`draft`, `active`, or `archived`

Delete a Product

DELETE/products/:idSoft-delete a product

Products are soft-deleted — the record is retained for order history but hidden from listings.

Orders

POST/stores/:storeId/ordersCreate an order

Request Body

{
"customerId": "cust_abc123",
"items": [
  { "variantId": "var_xyz789", "quantity": 2 },
  { "variantId": "var_def456", "quantity": 1 }
],
"currency": "USD"
}

Field	Type	Required	Description
`customerId`	string	Yes	Customer placing the order
`items`	array	Yes	Line items, each `{ variantId, quantity }`
`currency`	string	No	Three-letter ISO currency code

Fulfill or Cancel

PATCH/orders/:id/fulfillMark an order as fulfilled

PATCH/orders/:id/cancelCancel an order

fulfill transitions the order to fulfilled; cancel transitions it to cancelled. Both take no request body.

Coupons

POST/stores/:storeId/couponsCreate a discount coupon

Request Body

{
"code": "SUMMER2025",
"type": "percentage",
"value": 20,
"usageLimit": 100,
"minOrderAmount": 5000
}

Field	Type	Required	Description
`code`	string	Yes	Unique coupon code (max 50 chars)
`type`	string	Yes	`percentage` or `fixed`
`value`	number	Yes	Discount value: percent for `percentage`, cents for `fixed` (min: 1)
`usageLimit`	number	No	Maximum number of redemptions
`minOrderAmount`	number	No	Minimum order amount in cents to apply the coupon

Collections & Customers

GET/stores/:storeId/collectionsList product collections

GET/stores/:storeId/customersList customers for a store

Both return arrays scoped to the given store.

Public Storefront

These endpoints power public product browsing and require no authentication. Stores are addressed by their merchant slug.

GET/public/stores/:slugGet public store and merchant info

GET/public/stores/:slug/productsList active products for a store

GET /public/stores/:slug — Response

{
"merchant": { "id": "merch_xyz789", "name": "Acme Electronics", "slug": "acme-electronics" },
"store": { "id": "store_abc123", "name": "Acme US Store", "currency": "USD" }
}

GET /public/stores/:slug/products returns only products with status: active, each including its variants and the default variant's price and sku.