For the complete documentation index, see llms.txt. This page is also available as Markdown.

Carts

Add an overview of the Carts API here. This block is preserved across regenerations.

Endpoints

POST /api/v1/carts

Create a cart for a session. If an existing cart is already keyed to the session, it is returned instead of creating a duplicate.

post
/carts
Authorizations
X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Body
sessionIdstringRequired

Caller-chosen session identifier to key the cart to

Responses
200

Existing cart for this session returned

application/json

A cart with its line items and computed totals. Totals are recalculated server-side on every item change, including any applicable offer discount.

idstring · uuidOptional
sessionIdstringOptional

Caller-supplied session identifier the cart is keyed to

userIdstring · uuid · nullableOptional
statusstringOptionalExample: active
offerIdstring · uuid · nullableOptional

Offer currently applied to the cart (via promo code or auto-apply), null when none

subtotalCentsintegerOptional

Sum of line totals before discounts

discountCentsintegerOptional

Discount from the applied offer

totalCentsintegerOptional

subtotalCents − discountCents (never negative)

currencystringOptional
createdAtstring · date-timeOptional
updatedAtstring · date-timeOptional
post/carts
POST /api/v1/carts HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 20

{
  "sessionId": "text"
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "sessionId": "text",
  "userId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "active",
  "offerId": "123e4567-e89b-12d3-a456-426614174000",
  "subtotalCents": 1,
  "discountCents": 1,
  "totalCents": 1,
  "currency": "text",
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "cartId": "123e4567-e89b-12d3-a456-426614174000",
      "productId": "123e4567-e89b-12d3-a456-426614174000",
      "offerId": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "quantity": 1,
      "unitPriceCents": 1,
      "totalPriceCents": 1,
      "currency": "text",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for POST /carts go here.

GET /api/v1/carts/{id}

Get a cart with its items and totals

get
/carts/{id}
Authorizations
X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Path parameters
idstringRequired

Cart ID

Responses
200

Cart details

application/json

A cart with its line items and computed totals. Totals are recalculated server-side on every item change, including any applicable offer discount.

idstring · uuidOptional
sessionIdstringOptional

Caller-supplied session identifier the cart is keyed to

userIdstring · uuid · nullableOptional
statusstringOptionalExample: active
offerIdstring · uuid · nullableOptional

Offer currently applied to the cart (via promo code or auto-apply), null when none

subtotalCentsintegerOptional

Sum of line totals before discounts

discountCentsintegerOptional

Discount from the applied offer

totalCentsintegerOptional

subtotalCents − discountCents (never negative)

currencystringOptional
createdAtstring · date-timeOptional
updatedAtstring · date-timeOptional
get/carts/{id}
GET /api/v1/carts/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "sessionId": "text",
  "userId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "active",
  "offerId": "123e4567-e89b-12d3-a456-426614174000",
  "subtotalCents": 1,
  "discountCents": 1,
  "totalCents": 1,
  "currency": "text",
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "cartId": "123e4567-e89b-12d3-a456-426614174000",
      "productId": "123e4567-e89b-12d3-a456-426614174000",
      "offerId": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "quantity": 1,
      "unitPriceCents": 1,
      "totalPriceCents": 1,
      "currency": "text",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for GET /carts/{id} go here.

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

Add an item to a cart. Cart totals are recalculated and any auto-apply offer that improves the discount is applied.

post
/carts/{id}/items
Authorizations
X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Path parameters
idstringRequired

Cart ID

Body
productIdstring · uuidOptional

Catalog product this line maps to

offerIdstring · uuidOptional
namestring · min: 1Required
descriptionstringOptional
quantityinteger · min: 1OptionalDefault: 1
unitPriceCentsintegerRequired
Responses
201

Item added — returns the updated cart with recalculated totals

application/json

A cart with its line items and computed totals. Totals are recalculated server-side on every item change, including any applicable offer discount.

idstring · uuidOptional
sessionIdstringOptional

Caller-supplied session identifier the cart is keyed to

userIdstring · uuid · nullableOptional
statusstringOptionalExample: active
offerIdstring · uuid · nullableOptional

Offer currently applied to the cart (via promo code or auto-apply), null when none

subtotalCentsintegerOptional

Sum of line totals before discounts

discountCentsintegerOptional

Discount from the applied offer

totalCentsintegerOptional

subtotalCents − discountCents (never negative)

currencystringOptional
createdAtstring · date-timeOptional
updatedAtstring · date-timeOptional
post/carts/{id}/items
POST /api/v1/carts/{id}/items HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 168

{
  "productId": "123e4567-e89b-12d3-a456-426614174000",
  "offerId": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "quantity": 1,
  "unitPriceCents": 1
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "sessionId": "text",
  "userId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "active",
  "offerId": "123e4567-e89b-12d3-a456-426614174000",
  "subtotalCents": 1,
  "discountCents": 1,
  "totalCents": 1,
  "currency": "text",
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "cartId": "123e4567-e89b-12d3-a456-426614174000",
      "productId": "123e4567-e89b-12d3-a456-426614174000",
      "offerId": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "quantity": 1,
      "unitPriceCents": 1,
      "totalPriceCents": 1,
      "currency": "text",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for POST /carts/{id}/items go here.

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

Remove an item from a cart. Cart totals and offer discounts are recalculated.

delete
/carts/{id}/items/{itemId}
Authorizations
X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Path parameters
idstringRequired

Cart ID

itemIdstringRequired

Cart item ID

Responses
200

Item removed — returns the updated cart with recalculated totals

application/json

A cart with its line items and computed totals. Totals are recalculated server-side on every item change, including any applicable offer discount.

idstring · uuidOptional
sessionIdstringOptional

Caller-supplied session identifier the cart is keyed to

userIdstring · uuid · nullableOptional
statusstringOptionalExample: active
offerIdstring · uuid · nullableOptional

Offer currently applied to the cart (via promo code or auto-apply), null when none

subtotalCentsintegerOptional

Sum of line totals before discounts

discountCentsintegerOptional

Discount from the applied offer

totalCentsintegerOptional

subtotalCents − discountCents (never negative)

currencystringOptional
createdAtstring · date-timeOptional
updatedAtstring · date-timeOptional
delete/carts/{id}/items/{itemId}
DELETE /api/v1/carts/{id}/items/{itemId} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "sessionId": "text",
  "userId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "active",
  "offerId": "123e4567-e89b-12d3-a456-426614174000",
  "subtotalCents": 1,
  "discountCents": 1,
  "totalCents": 1,
  "currency": "text",
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "cartId": "123e4567-e89b-12d3-a456-426614174000",
      "productId": "123e4567-e89b-12d3-a456-426614174000",
      "offerId": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "quantity": 1,
      "unitPriceCents": 1,
      "totalPriceCents": 1,
      "currency": "text",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for DELETE /carts/{id}/items/{itemId} go here.

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

Remove the applied offer (promo) from a cart and recalculate totals

delete
/carts/{id}/promo
Authorizations
X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Path parameters
idstringRequired

Cart ID

Responses
200

Offer removed — returns the updated cart

application/json

A cart with its line items and computed totals. Totals are recalculated server-side on every item change, including any applicable offer discount.

idstring · uuidOptional
sessionIdstringOptional

Caller-supplied session identifier the cart is keyed to

userIdstring · uuid · nullableOptional
statusstringOptionalExample: active
offerIdstring · uuid · nullableOptional

Offer currently applied to the cart (via promo code or auto-apply), null when none

subtotalCentsintegerOptional

Sum of line totals before discounts

discountCentsintegerOptional

Discount from the applied offer

totalCentsintegerOptional

subtotalCents − discountCents (never negative)

currencystringOptional
createdAtstring · date-timeOptional
updatedAtstring · date-timeOptional
delete/carts/{id}/promo
DELETE /api/v1/carts/{id}/promo HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "sessionId": "text",
  "userId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "active",
  "offerId": "123e4567-e89b-12d3-a456-426614174000",
  "subtotalCents": 1,
  "discountCents": 1,
  "totalCents": 1,
  "currency": "text",
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "cartId": "123e4567-e89b-12d3-a456-426614174000",
      "productId": "123e4567-e89b-12d3-a456-426614174000",
      "offerId": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "quantity": 1,
      "unitPriceCents": 1,
      "totalPriceCents": 1,
      "currency": "text",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for DELETE /carts/{id}/promo go here.

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

Apply an offer (promo) code to a cart. The offer is validated against the cart contents before it is applied.

post
/carts/{id}/promo
Authorizations
X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Path parameters
idstringRequired

Cart ID

Body
codestringRequired

Offer code to apply

Responses
200

Offer applied — returns the updated cart plus an offer summary with the discount amount

application/json

A cart with its line items and computed totals. Totals are recalculated server-side on every item change, including any applicable offer discount.

idstring · uuidOptional
sessionIdstringOptional

Caller-supplied session identifier the cart is keyed to

userIdstring · uuid · nullableOptional
statusstringOptionalExample: active
offerIdstring · uuid · nullableOptional

Offer currently applied to the cart (via promo code or auto-apply), null when none

subtotalCentsintegerOptional

Sum of line totals before discounts

discountCentsintegerOptional

Discount from the applied offer

totalCentsintegerOptional

subtotalCents − discountCents (never negative)

currencystringOptional
createdAtstring · date-timeOptional
updatedAtstring · date-timeOptional
post/carts/{id}/promo
POST /api/v1/carts/{id}/promo HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 15

{
  "code": "text"
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "sessionId": "text",
  "userId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "active",
  "offerId": "123e4567-e89b-12d3-a456-426614174000",
  "subtotalCents": 1,
  "discountCents": 1,
  "totalCents": 1,
  "currency": "text",
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "cartId": "123e4567-e89b-12d3-a456-426614174000",
      "productId": "123e4567-e89b-12d3-a456-426614174000",
      "offerId": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "quantity": 1,
      "unitPriceCents": 1,
      "totalPriceCents": 1,
      "currency": "text",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for POST /carts/{id}/promo go here.

Last updated

Was this helpful?