> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api-docs.papertracc.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api-docs.papertracc.com/_mcp/server.

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

> **Warning**
>
> The token is the only thing protecting the cart. Do not put it in a URL or a log.

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.

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