Optional stateless convenience endpoints that simplify common cart operations. These are pure functions — (existingCart, operation) → newCart — with no server-side state.
Why use them?
- Accurate pricing using current CatalogSet prices
- Modifier validation (required selections, limits)
- Consistent cart structure ready for order validation
When to implement your own: If you need offline cart support, complex discount/promotion logic, custom persistence, or cart merging across sessions.
Partners can freely choose to use these helpers or implement equivalent logic themselves.
Add item to cart
Stateless cart helper — Adds an item to a cart and returns the updated cart with recalculated totals.
This is a pure function: (existingCart, itemToAdd) → newCart
No server-side state — Partners manage their own cart state. This endpoint simply computes the result of adding an item, validating modifier requirements and calculating prices using the current CatalogSet.
Pass cart: null to create a new cart (provide catalogSetId in this case). For existing carts, pass the full cart object.
Optional — Partners can implement their own cart logic instead of using this helper.
Add item to cart › Request Body
Add item to cart › Responses
Cart operation failed. The errorCode field identifies the specific issue (e.g. MISSING_STORE_ID, CATALOGSET_REQUIRED, INVALID_REQUEST).
statusThe HTTP status code.
titleA short, human-readable summary of the problem type.
typeA URI reference that identifies the problem type.
detailA human-readable explanation specific to this occurrence.
errorCategoryMachine-readable error category (e.g. validation, rate_limit, payment, availability, server_error).
errorCodeMachine-readable error code for domain-specific errors.
Validation error details, when applicable.
instanceA URI reference that identifies the specific occurrence.
requestIdUnique identifier for this request, useful for support.
retryAfterSeconds to wait before retrying. Present when retryable is true and a wait period is known.
retryableWhether the request can be retried with a reasonable expectation of success.
timestampWhen the error occurred.
traceIdW3C trace id (32-hex) for this request. Paste into SigNoz trace search to find the distributed trace and correlated logs. Populated by the global exception filter.
Remove item from cart
Stateless cart helper - Removes an item from a cart and returns the updated cart with recalculated totals.
This is a pure function: (existingCart, lineItemId) -> newCart
No server-side state - Partners manage their own cart state. This endpoint simply computes the result of removing an item.
Optional - Partners can implement their own cart logic instead of using this helper.
Remove item from cart › Request Body
Shopping cart with line items. Carts are client-managed — there is no server-side cart storage.
lineItemIdID of the line item to remove
Remove item from cart › Responses
Updated cart with item removed and recalculated totals
catalogSetIdCatalog set identifier (canonical Guid).
Line items in the cart
storeIdStore identifier (canonical Guid).
Update item quantity
Stateless cart helper — Updates the quantity of an item in the cart and returns the updated cart with recalculated totals.
This is a pure function: (existingCart, lineItemId, newQuantity) → newCart
Setting quantity: 0 removes the item from the cart entirely.
No server-side state — Partners manage their own cart state.
Update item quantity › Request Body
Shopping cart with line items. Carts are client-managed — there is no server-side cart storage.
lineItemIdID of the line item to update
quantityNew quantity (0 removes the item)
Update item quantity › Responses
Updated cart with modified quantity and recalculated totals
catalogSetIdCatalog set identifier (canonical Guid).
Line items in the cart
storeIdStore identifier (canonical Guid).