Commerce Engine Developer Portal

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

Cart Structure (Cart Object)

Cart Items (CartItem Object)

Cart API Endpoints

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)

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.

GET /carts/{id}

DELETE /carts/{id}

GET /carts/users/{user_id}

DELETE /carts/users/{user_id}

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.
Add/Update/Remove Item Request Body
```
{
    "product_id": "PROD_ID_B",
    "variant_id": null, 
    "quantity": 2 // Set to 0 to remove
}
```

POST /carts/{id}/address

POST /carts/{id}/coupon

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

DELETE /carts/{id}/coupon

Redeem/Remove Loyalty Points & Credit Balance

Wishlist Endpoints

Common Use Cases & Flows

Adding the First Item to the Cart

Adding Subsequent Items / Updating Quantity / Removing

Retrieving Cart on Page Load / After Login

Getting Started

Storefront APIs

Configure your store

Cart

Core Concepts

Cart API Endpoints

Common Use Cases & Flows

Getting Started

Storefront APIs

Configure your store

​Core Concepts

​Cart API Endpoints

​Common Use Cases & Flows

Core Concepts

Cart API Endpoints

Common Use Cases & Flows