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

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/carts

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Body

application/json

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

201

Cart created

application/json

400

Validation error

application/json

post/carts

HTTPcURLJavaScriptPython

POST /api/v1/carts HTTP/1.1
Host: 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-08-07T01:34:01.717Z"
    }
  ],
  "createdAt": "2026-08-07T01:34:01.717Z",
  "updatedAt": "2026-08-07T01:34:01.717Z"
}

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

GET /api/v1/carts/{id}

Get a cart with its items and totals

get

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/carts/{id}

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

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

404

Cart not found

application/json

get/carts/{id}

HTTPcURLJavaScriptPython

GET /api/v1/carts/{id} HTTP/1.1
Host: 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-08-07T01:34:01.717Z"
    }
  ],
  "createdAt": "2026-08-07T01:34:01.717Z",
  "updatedAt": "2026-08-07T01:34:01.717Z"
}

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

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/carts/{id}/items

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters

idstringRequired

Cart ID

Body

application/json

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

400

Validation error

application/json

404

Cart not found

application/json

post/carts/{id}/items

HTTPcURLJavaScriptPython

POST /api/v1/carts/{id}/items HTTP/1.1
Host: 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-08-07T01:34:01.717Z"
    }
  ],
  "createdAt": "2026-08-07T01:34:01.717Z",
  "updatedAt": "2026-08-07T01:34:01.717Z"
}

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

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/carts/{id}/items/{itemId}

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

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

404

Cart not found

application/json

delete/carts/{id}/items/{itemId}

HTTPcURLJavaScriptPython

DELETE /api/v1/carts/{id}/items/{itemId} HTTP/1.1
Host: 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-08-07T01:34:01.717Z"
    }
  ],
  "createdAt": "2026-08-07T01:34:01.717Z",
  "updatedAt": "2026-08-07T01:34:01.717Z"
}

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

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/carts/{id}/promo

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

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

404

Cart not found

application/json

delete/carts/{id}/promo

HTTPcURLJavaScriptPython

DELETE /api/v1/carts/{id}/promo HTTP/1.1
Host: 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-08-07T01:34:01.717Z"
    }
  ],
  "createdAt": "2026-08-07T01:34:01.717Z",
  "updatedAt": "2026-08-07T01:34:01.717Z"
}

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

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/carts/{id}/promo

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters

idstringRequired

Cart ID

Body

application/json

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

400

Offer is not valid for this cart (offer_invalid) or validation error

application/json

404

Cart not found, or no offer matches the code

application/json

post/carts/{id}/promo

HTTPcURLJavaScriptPython

POST /api/v1/carts/{id}/promo HTTP/1.1
Host: 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-08-07T01:34:01.717Z"
    }
  ],
  "createdAt": "2026-08-07T01:34:01.717Z",
  "updatedAt": "2026-08-07T01:34:01.717Z"
}

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