Overview

A cart belongs to one shopper’s browser. It is anonymous: no customer is attached until checkout.

The cart token

Creating a cart returns a token once. Store it for the shopper, for example in an httpOnly cookie set by your server, and send it in the cart-token header on every later cart request.

A cart that has not changed for 30 days is removed, and its token stops working. A request with an unknown token returns 404; create a new cart when that happens.

Typical flow

1. Create the cart when the shopper adds their first item, sending the item in the same request.
2. Add, change and remove lines as the shopper shops. Every response returns the whole cart with fresh prices and totals.
3. Apply a promotion code if the shopper has one.
4. Check out with the shopper’s details. See Checkout.

curl -X POST "https://api.papertracc.com/v1/store/cart" \
  -H "Authorization: Bearer $API_KEY" \
  -H "identity: $WORKSPACE_IDENTITY" \
  -H "channel: $CHANNEL_HANDLE" \
  -H "Content-Type: application/json" \
  -d '{"country": "NG", "items": [{"variant_id": "4b67e11f-b111-4d80-85ae-ed0be1af492b", "quantity": 2}]}'

Country and currency

A cart’s country is set when it is created and cannot be changed. Its currency follows that country’s prices. To let a shopper switch country, create a new cart.

Totals

subtotal, discount_total, tax_total and total are recalculated on every request, so they always reflect current prices and promotions. Promotions that depend on who the shopper is, such as a limit of one use per customer, are only checked at checkout, when the shopper is known.

Stock

Whether a shortfall blocks a line depends on the workspace’s stock settings. When stock is enforced, adding more than is available fails with 422 and a message naming the item.

Backordered, pre-ordered and made-to-order items can still be added beyond stock. Each line’s sell_mode, lead_time_days and release_date say how it will ship, so show that next to the line. A merchant can cap how many backorders or pre-orders they take; past the cap, adding fails with 422. A cart can mix these items with in-stock ones, and the order ships when every item is ready.

Made-to-order products with questions

When a product’s request_form is in BUY_NOW mode, send the shopper’s answers and the needed_by date with the item. Priced options are added to the line’s unit price and shown as add_on, and the line’s answers list what the shopper chose. Products sold through order requests cannot be added to a cart; send them with Create Request. See Requests.

Limits

A cart holds up to 100 different items. A shopper can create 30 carts in 15 minutes.