Cart

Session-bound cart. Add items with a flat payload, apply coupons, and read totals as branded ` Money` strings. The SDK returns `Result<T>` on every method and never throws.

Add an item

The add-to-cart payload is flat. There is no nested configuration wrapper and no productId field; everything sits at the top of the body.

const added = await client.cart.addItem({
  item_id: 'prod_studio-tee-natural',
  quantity: 1,
  variant_id: 'var_studio-tee-natural_size_s',
  add_on_options: ['addopt_gift_wrap'],
  special_instructions: 'Please ship without invoice.',
})

if (!added.ok) {
  console.error(added.error.code, added.error.message)
  return
}

console.log(added.value.cart.id)

Read the cart

import { parsePrice, formatPrice } from '@cimplify/sdk'

const r = await client.cart.get()
if (!r.ok) return

const cart = r.value
console.log(cart.items.length)
console.log(cart.pricing.currency)               // "GHS"
console.log(cart.pricing.subtotal)               // Money (branded string)
console.log(cart.pricing.total_price)            // Money

// Money is a string. Always parse before math, format before display.
const subtotal = parsePrice(cart.pricing.subtotal)
if (subtotal !== 0) {
  console.log(formatPrice(subtotal, cart.pricing.currency)) // "GH₵29.99"
}

Update quantity / remove / clear

// You need the cart-item id from cart.items[i].id (NOT the product id)
await client.cart.updateQuantity('ci_xxx', 3)
await client.cart.removeItem('ci_xxx')
await client.cart.clear()

Coupons

const apply = await client.cart.applyCoupon('WELCOME10')
if (!apply.ok) {
  // Codes you'll see: COUPON_INVALID, COUPON_EXPIRED, COUPON_MIN_NOT_MET
  console.error(apply.error.code)
}

await client.cart.removeCoupon()

// Custom idempotency key (otherwise the SDK auto-generates one)
await client.cart.applyCoupon('WELCOME10', { idempotencyKey: 'apply-welcome10-once' })

Convenience reads

const count = await client.cart.getCount()                      // Result<number>
const total = await client.cart.getTotal()                      // Result<string>
const items = await client.cart.getItems()                      // Result<CartItem[]>
const summary = await client.cart.getSummary()                  // Result<CartSummary>
const empty = await client.cart.isEmpty()                       // Result<boolean>
const has = await client.cart.hasItem('prod_xxx', 'var_yyy')    // Result<boolean>
const found = await client.cart.findItem('prod_xxx', 'var_yyy') // Result<CartItem | undefined>

Reorder from a past order

Walks every line item on the order and adds it to the current cart. Returns added/failed lists; partial success is normal (e.g. a discontinued variant).

const r = await client.cart.reorderFromOrder('ord_xxx')
if (!r.ok) return

console.log(r.value.added)   // [{ item_id }, ...]
console.log(r.value.failed)  // [{ item_id, error: CimplifyError }, ...]

addItem payload

Field	Type	Notes
`item_id`	`string`	Required. Product ID.
`quantity`	`number`	Required.
`variant_id`	`string`	Selected variant.
`add_on_options`	`string[]`	Selected add-on option IDs.
`special_instructions`	`string`	Free-form note.
`bundle_selections`	`BundleSelection[]`	Required when item is a bundle.
`composite_selections`	`CompositeSelection[]`	Required when item is a composite.
`quote_id`	`string`	Pre-computed quote from `catalogue.fetchQuote`. Locks the price.

Method reference

Method	Returns
`get()`	`Result<UICart>`
`getItems()`	`Result<CartItem[]>`
`getCount()`	`Result<number>`
`getTotal()`	`Result<string>`
`getSummary()`	`Result<CartSummary>`
`addItem(input, opts?)`	`Result<CartMutationResult>`
`updateQuantity(cartItemId, qty)`	`Result<CartMutationResult>`
`removeItem(cartItemId)`	`Result<CartMutationResult>`
`clear()`	`Result<CartMutationResult>`
`applyCoupon(code, opts?)`	`Result<CartMutationResult>`
`removeCoupon()`	`Result<CartMutationResult>`
`reorderFromOrder(orderId)`	`Result<ReorderResult>`
`isEmpty()`	`Result<boolean>`
`hasItem(productId, variantId?)`	`Result<boolean>`
`findItem(productId, variantId?)`	`Result<CartItem \| undefined>`

Catalogue Fetch products and price quotes before adding
Checkout Convert the cart into a paid order
Scheduling Pick a slot for service bookings before checkout
Money type parsePrice / formatPrice for cart totals

Cart

On this page