---
title: "Cart"
description: "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."
source: content/docs/sdk/cart.mdx
---

      

      

## 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.

      
        

```ts
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

      
        

```ts
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

      
        

```ts
// 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

      
        

```ts
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

      
        

```ts
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).

      
        

```ts
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>` |

      

      

## Related

      
        
- [**Catalogue**](/docs/sdk/catalogue)
  Fetch products and price quotes before adding

        
- [**Checkout**](/docs/sdk/checkout)
  Convert the cart into a paid order

        
- [**Scheduling**](/docs/sdk/scheduling)
  Pick a slot for service bookings before checkout

        
- [**Money type**](/docs/concepts/money)
  parsePrice / formatPrice for cart totals