Skip to main content
Key Features Covered:
  • Explicit Cart Creation: Carts must be created before items can be added.
  • Persistent Carts: Carts are tied to the user.
  • Item Management: Add, update quantity, or remove products and variants to an existing cart.
  • Pricing Calculation: Automatically calculates subtotals, taxes, shipping, and grand totals.
  • Discount Application: Apply coupon codes, automatic promotions, loyalty points, and store credit.
  • Address Management: Set billing and shipping addresses for checkout calculation.
  • Fulfillment Options: Fetch fulfillment options and update fulfillment preferences per shipment.
  • User Association: Carts link to anonymous or logged-in users; retrievable via user_id for both.

​
Core Concepts

  • Creation: A cart must always be explicitly created using POST /carts before any items can be added. This endpoint requires at least one item to be included in the request body for successful cart creation. There is no concept of creating an empty cart via the API initially.
  • Association: Every cart is linked to a user automatically upon creation.
  • Retrieval: You can retrieve a specific cart using its id (GET /carts/{id}) or retrieve the active cart associated with a user (both anonymous and logged-in) via their user_id (GET /carts/users/{user_id}). This allows fetching the correct cart even if the client loses the cart_id but still has the user’s token/ID.
  • Persistence: Carts persist across sessions as long as the user context (user_id) remains the same.
  • Expiration: Carts have an expires_at timestamp. Inactive carts may be cleaned up after this time. Active interaction typically extends the expiry.
  • Transition to Order: The final state of the cart (identified by its id) is used as the basis for creating an order via the POST /orders endpoint.
-When an anonymous user creates a cart and then goes on to login, if the user happens to be a returning user, the currently active cart is merged into the logged in user’s ID. This ensures seamless checkout experience. -Note that if the logged in user already had a different cart associated from a previous session, that cart will be marked as inactive when they login with an active cart. This is to prevent cart/item conflicts or items suddenly appearing/disappearing from the user’s cart.
  • id: The unique identifier for this cart.
  • active: Boolean indicating if the cart is still active.
  • cart_items: An array of CartItem objects detailing each product/variant in the cart.
  • cart_items_count: Total number of unique line items.
  • Pricing Summary:
    • subtotal: Sum of item selling prices (before tax and discounts).
    • items_tax_amount: Total tax calculated on items.
    • subtotal_including_tax: Subtotal + Item Tax.
    • shipping_amount: Calculated shipping cost (before tax).
    • shipping_tax_amount: Tax on shipping.
    • shipping_amount_including_tax: Shipping + Shipping Tax.
    • total_tax: items_tax_amount + shipping_tax_amount + handling_charge_tax_amount.
    • grand_total: The final amount after all deductions, including taxes but before loyalty points are redeemed.
  • Discounts & Redemptions:
    • is_promotion_applied, promotion_discount_amount: For automatic promotions.
    • is_coupon_applied, coupon_code, coupon_discount_amount: For user-applied coupons.
    • loyalty_points_redeemed: Points applied as discount.
    • loyalty_points_earned: Points the user will earn if this cart becomes an order.
    • credit_balance_used: Store credit/wallet balance applied.
    • to_be_paid: The amount to display at checkout. This is what the customer actually pays (grand_total - loyalty_points_redeemed_value - credit_balance_used). Always display to_be_paid rather than grand_total as the final price — it accounts for loyalty points and credit balance deductions.
  • Addresses:
    • billing_address: CustomerAddress object.
    • shipping_address: CustomerAddress object.
    • customer_email, customer_phone, customer_note: User details associated with the cart.
    • currency: Currency details (code, symbol, name).
    • metadata: Custom key-value pairs.
    • expires_at: Timestamp when the cart might expire if inactive.
  • product_id, variant_id, sku: Identifiers for the item.
  • product_name, variant_name, product_image_url: Display details.
  • quantity: The number of this item in the cart.
  • stock_available, on_offer, on_promotion, on_subscription: Status flags.
  • listing_price, selling_price: Per-unit prices.
  • promotion_discount_amount, coupon_discount_amount: Discounts applied to this line item.
  • tax_type, tax_rate, tax_amount: Tax details for this line item.
  • shipping_additional_cost: Any per-item shipping surcharge.
  • associated_options: Details of selected variant options (e.g., Color: Red, Size: Large).
  • subscriptions: Details if this item is being added as part of a subscription plan.
  • is_free_item, free_quantity: Indicates if quantity is part of a “free goods” promotion.

​
Cart API Endpoints

Explicitly creates a new cart. This endpoint requires at least one item in the items array to successfully create the cart. It cannot be used to create an empty cart. This is typically the first cart-related call when a user adds their initial item.
  • Authentication: Bearer Token (Anonymous or Logged-in)
  • Request Body (Required): (See UpdateCartItem schema)
    Create Cart Request Body
    {
  "items": [
    {
      "product_id": "PROD_ID_1",
      "variant_id": "VARIANT_ID_A", // or null if no variants
      "quantity": 1
    }
    // Potentially more items
  ]
}
  • Response: 200 OK with the newly created Cart object, including its unique id. Store this id for subsequent cart operations.
Fetches the details of a specific cart using its ID.
  • Authentication: Bearer Token (Must match the user associated with the cart ID)
  • Path Parameter: id (Cart ID obtained from POST /carts or a previous cart state)
  • Response: 200 OK with the Cart object, or 404 Not Found.
Removes all items from the specified cart, effectively emptying it but leaving the cart shell intact until expiration/cleanup.
  • Authentication: Bearer Token (Must match the user associated with the cart ID)
  • Path Parameter: id (Cart ID)
  • Response: 200 OK with success message, or 404 Not Found.
Fetches the active cart associated with a specific user ID. This works for both anonymous and logged-in users. Use the user_id from the user object obtained via /auth/anonymous or login flows.
  • Authentication: Bearer Token (Token must correspond to the user session associated with {user_id})
  • Path Parameter: user_id
  • Response: 200 OK with the Cart object, or 404 Not Found if no active cart exists for the user.
Removes all items from the active cart associated with the specified user ID (anonymous or logged-in).
  • Authentication: Bearer Token (Token must correspond to the user session associated with {user_id})
  • Path Parameter: user_id
  • Response: 200 OK with success message, or 404 Not Found.
Updates the contents of an existing cart. This endpoint cannot create a cart; use POST /carts for initial creation.
  • Authentication: Bearer Token (Must match the user associated with the cart ID)
  • Path Parameter: id (Required Cart ID obtained from POST /carts or GET requests)
  • Request Body: UpdateCartItem schema:
    • product_id: Required ID of the product.
    • variant_id: Required ID of the variant (use null if the product has no variants).
    • quantity: The desired total quantity for this item in the cart.
      • quantity > 0: Adds or updates the item to this quantity.
      • quantity = 0: Removes the item from the cart.
  • Response: 200 OK with the updated Cart object reflecting the changes and recalculated totals. Returns 400 Bad Request if quantity exceeds stock or validation fails, or 404 Not Found if the Cart ID is invalid.
    Add/Update/Remove Item Request Body
    {
    "product_id": "PROD_ID_B",
    "variant_id": null,
    "quantity": 2 // Set to 0 to remove
}
Sets or updates the billing and shipping addresses for the cart. Crucial for calculating shipping costs and taxes.
  • Authentication: Bearer Token
  • Path Parameter: id (Cart ID)
  • Request Body: oneOf saved address IDs (logged-in users) or full CustomerAddress objects (guests or new address). (Schema details unchanged)
  • Response: 200 OK with the updated Cart object.
Applies a coupon code to the cart.
  • Authentication: Bearer Token
  • Path Parameter: id (Cart ID)
  • Request Body:
    Apply Coupon Request Body
    { "coupon_code": "YOUR_COUPON_CODE" }
  • Response: 200 OK with the updated Cart object, or 400 Bad Request.
Important NoteIf a coupon has rules like “valid for first-time customers only,” attempting to apply it while the user is anonymous may result in a 400 Bad Request error, potentially with a message indicating login is required. Consider prompting users to log in before applying coupons with such restrictions.
Removes any currently applied coupon from the cart.
  • Authentication: Bearer Token
  • Path Parameter: id (Cart ID)
  • Response: 200 OK with the updated Cart object.
(Endpoints POST /carts/{id}/loyalty-points, DELETE /carts/{id}/loyalty-points, POST /carts/{id}/credit-balance, DELETE /carts/{id}/credit-balance remain functionally the same, requiring a logged-in user’s token.)
(Endpoints GET /wishlist/{user_id}, POST /wishlist/{user_id}, DELETE /wishlist/{user_id} remain functionally the same, requiring a logged-in user’s token.)

​
Common Use Cases & Flows