Cart

Key Features Covered:

• Explicit Cart Creation: Carts must be created before items can be added.
• Persistent Carts: Carts are tied to the user’s token/account.
• 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.
• User Association: Carts link to anonymous or logged-in users; retrievable via user_id for both.

​

Core Concepts

​

Cart Lifecycle & Persistence

• 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 a truly empty cart via the API initially.
• Association: Every cart is linked to a user via their access_token.
• 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.

​

Cart Structure (Cart Object)

• 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.
  • grand_total: The final amount before user-specific deductions (subtotal_including_tax + shipping_amount_including_tax - discounts).
• 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 final amount the customer needs to pay (grand_total - loyalty_points_redeemed_value - credit_balance_used).
• 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.

​

Cart Items (CartItem Object)

• 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

​

Create Cart

POST /carts

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)

  {
    "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.

​

Retrieve Cart by ID

GET /carts/{id}

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.

​

Delete Cart (Empty Cart) by ID

DELETE /carts/{id}

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.

​

Retrieve Cart by User ID

GET /carts/users/{user_id}

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.

​

Delete Cart (Empty Cart) by User ID

DELETE /carts/users/{user_id}

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.

​

Add/Update/Remove Cart Item

POST /carts/{id}/items

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.

​

Update Cart Address

POST /carts/{id}/address

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.

​

Apply Coupon

POST /carts/{id}/coupon

Applies a coupon code to the cart.

• Authentication: Bearer Token
• Path Parameter: id (Cart ID)
• Request Body: { "coupon_code": "YOUR_COUPON_CODE" }
• Response: 200 OK with the updated Cart object, or 400 Bad Request.
• Important Note: If 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.

​

Remove Coupon

DELETE /carts/{id}/coupon

Removes any currently applied coupon from the cart.

• Authentication: Bearer Token
• Path Parameter: id (Cart ID)
• Response: 200 OK with the updated Cart object.

​

Redeem/Remove Loyalty Points & Credit Balance

(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.)

​

Wishlist Endpoints

(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

​

Adding the First Item to the Cart

​

Adding Subsequent Items / Updating Quantity / Removing

​

Retrieving Cart on Page Load / After Login