Carts

Carts power on-page checkout flows. Unlike orders (which are atomic), carts let a session accumulate items and have promotions applied before being converted to an order.

Auth note: cart endpoints sit behind the same API-key authentication as the rest of /api/v1. The sessionId you pass in is your storefront's own session identifier and scopes the cart for reuse — it does not authenticate the request. Send your tenant API key with every cart call.

• POST /api/v1/carts — get or create

• GET /api/v1/carts/{id}

• POST /api/v1/carts/{id}/items

• DELETE /api/v1/carts/{id}/items/{itemId}

• POST /api/v1/carts/{id}/promo

• DELETE /api/v1/carts/{id}/promo

---

POST /api/v1/carts

Get or create a cart for a session. If a cart already exists for the sessionId, it is returned with its items.

Body

Field	Type	Required
sessionId	string (≥1)	yes

Response 200 or 201

{
  "id": "cart_01H...",
  "tenantId": "ten_01H...",
  "sessionId": "sess_01H...",
  "status": "active",
  "subtotalCents": 0,
  "discountCents": 0,
  "totalCents": 0,
  "currency": "USD",
  "items": []
}

cURL

curl -X POST https://api.example.com/api/v1/carts \
  -H "Authorization: Bearer $PEAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sessionId": "sess_01H..." }'

---

GET /api/v1/carts/{id}

Retrieve a cart with its items.

Errors

Status	When
404	Cart not found

cURL

curl -H "Authorization: Bearer $PEAK_API_KEY" \
  https://api.example.com/api/v1/carts/cart_01H...

---

POST /api/v1/carts/{id}/items

Add a line item. Recomputes subtotal, automatically re-evaluates auto- apply offers, and updates the discount/total.

Body

Field	Type	Required	Description
productId	UUID	no	Recommended; ties to the catalog
offerId	UUID	no	Pre-applied offer ID
name	string	yes	Display name
description	string	no
quantity	integer ≥ 1	no	Defaults to 1
unitPriceCents	integer ≥ 0	yes

Response 201

{
  "id": "cart_01H...",
  "subtotalCents": 9800,
  "discountCents": 980,
  "totalCents": 8820,
  "currency": "USD",
  "items": [
    {
      "id": "ci_01H...",
      "cartId": "cart_01H...",
      "productId": "prod_01H...",
      "name": "Pro Plan",
      "quantity": 2,
      "unitPriceCents": 4900,
      "totalPriceCents": 9800,
      "currency": "USD"
    }
  ]
}

cURL

curl -X POST https://api.example.com/api/v1/carts/cart_01H.../items \
  -H "Authorization: Bearer $PEAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "prod_uuid",
    "name": "Pro Plan",
    "quantity": 2,
    "unitPriceCents": 4900
  }'

---

DELETE /api/v1/carts/{id}/items/{itemId}

Remove a line item; re-evaluates discounts and totals.

Response 200

Same shape as adding an item.

cURL

curl -X DELETE https://api.example.com/api/v1/carts/cart_01H.../items/ci_01H... \
  -H "Authorization: Bearer $PEAK_API_KEY"

---

POST /api/v1/carts/{id}/promo

Apply a promo code. Looks up the offer by code, validates against the current cart contents, and (if valid) attaches it.

Body

Field	Type	Required
code	string (≥1)	yes

Response 200

{
  "id": "cart_01H...",
  "subtotalCents": 9800,
  "discountCents": 980,
  "totalCents": 8820,
  "items": [ /* ... */ ],
  "offer": {
    "code": "WELCOME10",
    "name": "Welcome 10% off",
    "discountType": "percentage",
    "discountValue": "10",
    "discountAmountCents": 980
  }
}

Errors

Status	When
400	Offer invalid for this cart (expired, min-amount not met, etc.)
404	Code not found

cURL

curl -X POST https://api.example.com/api/v1/carts/cart_01H.../promo \
  -H "Authorization: Bearer $PEAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "WELCOME10" }'

---

DELETE /api/v1/carts/{id}/promo

Remove the applied promo and recompute totals.

Response 200

Same shape as adding an item; offer field is absent.

cURL

curl -X DELETE https://api.example.com/api/v1/carts/cart_01H.../promo \
  -H "Authorization: Bearer $PEAK_API_KEY"

---

Related

• Orders — convert a cart to an order

• Pricing previews