Cart

The Cart is a persistent shopping session. Cart state is stored in the database, so customers can abandon and return without losing their selections. A cart's expires_at is set 7 days after creation and is not extended on subsequent updates.

Cart Sessions

Carts are tied to one of:

• An authenticated customer — retrieved automatically when the customer logs in (the Customer-Token is read by the middleware to find the customer's cart)
• A guest session — a unique identifier your app generates and stores locally (e.g., in AsyncStorage). Pass it as the URL path parameter when retrieving the cart

GET /storefront/v1/carts/{uniqueIdentifier}
Authorization: Bearer store_your_store_key

Cart Item Structure

Each item in the cart records:

The cart object itself exposes accessors for total_items, total_unique_items, subtotal, and is_multi_cart (true when items span more than one store).

Adding Items

POST /storefront/v1/carts/{cartId}/{productId}
Authorization: Bearer store_your_store_key

{
  "quantity": 2,
  "variants": [{ "id": "variant_option_id", "additional_cost": 200 }],
  "addons": [{ "id": "addon_id", "price": 100 }],
  "store_location": "store_location_public_id"
}

store_location is optional — if omitted, the cart picks the store's first location. Variants and addons are stored as full objects (their additional_cost and price are read by the cart subtotal calculator).

Updating Items

PUT /storefront/v1/carts/{cartId}/{lineItemId}
Authorization: Bearer store_your_store_key

Pass updated quantity, variants, or addons.

Removing Items

DELETE /storefront/v1/carts/{cartId}/{lineItemId}
Authorization: Bearer store_your_store_key

Cart Calculations

Cart totals are recalculated after every modification:

Item Subtotal = (Base Price
                 + Sum of selected variant additional costs
                 + Sum of addon prices (sale_price when is_on_sale, otherwise price))
                × Quantity

Cart Subtotal = Sum of all item subtotals

Cart Events

Cart mutations are logged on the cart's events array — cart.item_added, cart.item_updated, cart.item_removed, cart.emptied. This is useful for audit trails and for analyzing cart abandonment patterns.

Multi-Store Cart Behavior

A cart can hold items from a single store or from multiple stores within a Network — the behavior is controlled by the network's Enable multi-cart checkout setting (options.multi_cart_enabled).

Single-store carts (default)

When multi-cart is disabled (or the customer is shopping a standalone store), the cart's items are tied to a single store at a time. Your frontend should prompt the customer to clear the cart if they try to add an item from a different store.

Multi-store carts (network-level)

When Enable multi-cart checkout is toggled on for a Network:

• Customers can add items from any store in the network to a single cart
• The cart's is_multi_cart accessor returns true when items span more than one store
• Storefront groups cart items by store internally
• One checkout session is created for the combined total
• On successful capture, Storefront produces one Fleet-Ops order per store, each with its own pickup location, store-specific dispatch, and proof-of-delivery
• The customer pays once but receives multiple deliveries

Toggle this from Storefront → Networks → [Network] → General Settings → Enable multi-cart checkout.

Promotions and Promo Codes

Carts are priced against the store's (or network's) promotions: automatic promotions apply to every eligible cart, and code-based promotions apply once the customer enters a promo code.

Applied codes are listed in the cart's promo_codes (the older discount_code field holds the same codes comma separated) and are used automatically at checkout. The cart's subtotal is always the undiscounted total — the discount is applied when the checkout is created.