Cart

The cart is server-owned and bound to the caller’s session. Items are added by `item_id` with an optional `variant_id` and add-on selections. The same cart is read on the storefront and on checkout; there is no client-side cart sync.

GET /api/v1/cart

Returns the current cart enriched with line items, pricing breakdown, applied coupon, and totals.

Request

cURL

curl https://storefronts.cimplify.io/api/v1/cart \
  -H "X-API-Key: cpk_test_your_publishable_key"

Response

{
  "success": true,
  "data": {
    "id": "cart_01H…",
    "items": [
      {
        "id": "ci_01H…",
        "item_id": "prod_abc123",
        "name": "Espresso",
        "variant_id": "var_double",
        "variant_name": "Double",
        "quantity": 2,
        "unit_price": "6.00",
        "line_total": "12.00",
        "add_on_options": ["opt_oat"],
        "special_instructions": null
      }
    ],
    "pricing": {
      "subtotal": "12.00",
      "discount_total": "0.00",
      "tax_total": "1.06",
      "total_price": "13.06",
      "currency": "GHS"
    },
    "coupon": null
  }
}

DELETE /api/v1/cart

Removes every line item and clears the applied coupon.

cURL

curl -X DELETE https://storefronts.cimplify.io/api/v1/cart \
  -H "X-API-Key: cpk_test_your_publishable_key"

GET /api/v1/cart/items

Returns just the line items array, the same shape as data.items on GET /cart.

cURL

curl https://storefronts.cimplify.io/api/v1/cart/items \
  -H "X-API-Key: cpk_test_your_publishable_key"

POST /api/v1/cart/items

Add a line item. The body is flat; there is no nested configuration or product wrapper. Use the Idempotency-Key header to dedupe retries.

Body

Field	Type	Description
`item_id`	string	Product ID. Required.
`quantity`	integer	1 to 100. Default 1.
`variant_id`	string	Selected variant.
`add_on_options`	string[]	Add-on option IDs.
`special_instructions`	string	Free-form note shown to the merchant.
`bundle_selections`	object[]	For bundle products: `{ component_id, variant_id?, quantity }`.
`composite_selections`	object[]	For composites: `{ component_id, quantity, variant_id?, add_on_option_id? }`.
`scheduled_start`	datetime	For service products: booking start in ISO 8601.
`scheduled_end`	datetime	Booking end.
`staff_id`	string	Preferred staff for the booking.
`quote_id`	string	Pre-issued quote to lock pricing.
`billing_plan_id`	string	For subscription products.

cURL

curl -X POST https://storefronts.cimplify.io/api/v1/cart/items \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Idempotency-Key: 5b1f9d80-2c70-4f2c-bf61-a0e6fa6b02a1" \
  -H "Content-Type: application/json" \
  -d '{
    "item_id": "prod_abc123",
    "quantity": 2,
    "variant_id": "var_double",
    "add_on_options": ["opt_oat"]
  }'

Errors

Returns 400 VALIDATION_ERROR if item_id is empty, quantity < 1, or quantity > 100. Returns 404 NOT_FOUND when the product or variant doesn’t exist for the active business.

PATCH /api/v1/cart/items/{cart_item_id}

Update the quantity of a line item already in the cart.

cURL

curl -X PATCH https://storefronts.cimplify.io/api/v1/cart/items/ci_01H… \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 3}'

DELETE /api/v1/cart/items/{cart_item_id}

Remove a single line item.

cURL

curl -X DELETE https://storefronts.cimplify.io/api/v1/cart/items/ci_01H… \
  -H "X-API-Key: cpk_test_your_publishable_key"

GET /api/v1/cart/count

Returns the total quantity across line items as an integer.

{ "success": true, "data": 4 }

GET /api/v1/cart/total

Returns the cart total as a Money string.

{ "success": true, "data": "13.06" }

POST /api/v1/cart/coupons

Apply a coupon code to the cart. Replaces any previously applied coupon.

cURL

curl -X POST https://storefronts.cimplify.io/api/v1/cart/coupons \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{"coupon_code": "WELCOME10"}'

DELETE /api/v1/cart/coupons/current

Remove the active coupon. Idempotent.

cURL

curl -X DELETE https://storefronts.cimplify.io/api/v1/cart/coupons/current \
  -H "X-API-Key: cpk_test_your_publishable_key"

Next: Checkout Submit the cart for payment with a flat checkout body.
Catalogue: Products Where item_id values come from.

Cart

On this page