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.
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.
Caller-chosen session identifier to key the cart to
Existing cart for this session returned
A cart with its line items and computed totals. Totals are recalculated server-side on every item change, including any applicable offer discount.
Caller-supplied session identifier the cart is keyed to
activeOffer currently applied to the cart (via promo code or auto-apply), null when none
Sum of line totals before discounts
Discount from the applied offer
subtotalCents − discountCents (never negative)
Cart created
Validation error
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}
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.
Cart ID
Cart details
A cart with its line items and computed totals. Totals are recalculated server-side on every item change, including any applicable offer discount.
Caller-supplied session identifier the cart is keyed to
activeOffer currently applied to the cart (via promo code or auto-apply), null when none
Sum of line totals before discounts
Discount from the applied offer
subtotalCents − discountCents (never negative)
Cart not found
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.
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.
Cart ID
Catalog product this line maps to
1Item added — returns the updated cart with recalculated totals
A cart with its line items and computed totals. Totals are recalculated server-side on every item change, including any applicable offer discount.
Caller-supplied session identifier the cart is keyed to
activeOffer currently applied to the cart (via promo code or auto-apply), null when none
Sum of line totals before discounts
Discount from the applied offer
subtotalCents − discountCents (never negative)
Validation error
Cart not found
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.
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.
Cart ID
Cart item ID
Item removed — returns the updated cart with recalculated totals
A cart with its line items and computed totals. Totals are recalculated server-side on every item change, including any applicable offer discount.
Caller-supplied session identifier the cart is keyed to
activeOffer currently applied to the cart (via promo code or auto-apply), null when none
Sum of line totals before discounts
Discount from the applied offer
subtotalCents − discountCents (never negative)
Cart not found
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
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.
Cart ID
Offer removed — returns the updated cart
A cart with its line items and computed totals. Totals are recalculated server-side on every item change, including any applicable offer discount.
Caller-supplied session identifier the cart is keyed to
activeOffer currently applied to the cart (via promo code or auto-apply), null when none
Sum of line totals before discounts
Discount from the applied offer
subtotalCents − discountCents (never negative)
Cart not found
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.
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.
Cart ID
Offer code to apply
Offer applied — returns the updated cart plus an offer summary with the discount amount
A cart with its line items and computed totals. Totals are recalculated server-side on every item change, including any applicable offer discount.
Caller-supplied session identifier the cart is keyed to
activeOffer currently applied to the cart (via promo code or auto-apply), null when none
Sum of line totals before discounts
Discount from the applied offer
subtotalCents − discountCents (never negative)
Offer is not valid for this cart (offer_invalid) or validation error
Cart not found, or no offer matches the code
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?
