Storefront API
Base URL: /api/v1. Use these endpoints to list published products, search, collect reviews, manage a cart, and start checkout.
Catalog
Section titled “Catalog”List published products
Section titled “List published products”GET /api/v1/catalog
Query params: page, limit (max 100), locale, currency, categoryId
Response:
{ "products": [...], "total": 42, "page": 1, "limit": 20}Get a product
Section titled “Get a product”GET /api/v1/catalog/:id
Get a single product by id.
Query params: locale, currency
Categories
Section titled “Categories”List categories
Section titled “List categories”GET /api/v1/categories
List all categories.
Query params: locale
Search
Section titled “Search”Search products
Section titled “Search products”GET /api/v1/search
Query params: q, page, limit, locale, currency, categoryId, sortBy, sortDir
Reviews
Section titled “Reviews”List approved reviews
Section titled “List approved reviews”GET /api/v1/products/:productId/reviews
List approved reviews for a product.
Query params: page (default 1), limit (default 10, max 100)
Response:
{ "reviews": [...], "total": 12, "page": 1, "limit": 10, "totalPages": 2}Submit a review
Section titled “Submit a review”POST /api/v1/products/:productId/reviews
Submit a product review (status starts as pending until moderated).
Body: { "customerId": "...", "rating": 5, "title": "Optional", "body": "Great product" }
Response: 201 with { "review": { ... } }
Create a cart
Section titled “Create a cart”POST /api/v1/cart
Body:
{ "currency": "USD", "customerId": "optional" }Response: 201 with { "cart": { ... } }
The returned cart includes a token. Use that token on every later cart request.
Get a cart
Section titled “Get a cart”GET /api/v1/cart/:token
Get a cart by its token.
Delete a cart
Section titled “Delete a cart”DELETE /api/v1/cart/:token
Delete a cart.
Add a line
Section titled “Add a line”POST /api/v1/cart/:token/lines
Body:
{ "variantId": "cld...", "quantity": 2, "currency": "USD" }Update a line
Section titled “Update a line”PATCH /api/v1/cart/:token/lines/:lineId
Update a line’s quantity.
Body: { "quantity": 3 } — set to 0 or negative to remove.
Remove a line
Section titled “Remove a line”DELETE /api/v1/cart/:token/lines/:lineId
Remove a line from the cart.
Checkout
Section titled “Checkout”Create a checkout session
Section titled “Create a checkout session”POST /api/v1/checkout
Create a checkout session from a cart.
Body:
{ "cartToken": "uuid...", "customerId": "optional"}Response: 201 with { "session": { ... } }
Get a checkout session
Section titled “Get a checkout session”GET /api/v1/checkout/:id
Get a checkout session.
Update a checkout session
Section titled “Update a checkout session”POST /api/v1/checkout/:id/update
Update checkout session fields (address, shipping option, payment provider, tenders, etc.). Pass a full payload with shippingAddressJson, shippingOptionJson, and paymentProvider to validate a complete checkout before order placement.