> For the complete Lynkow documentation index in agent-friendly format, see [llms.txt](/llms.txt).

# SDK Types: Cart

**Publié le** : 2026-08-20
**Catégorie** : Types

# SDK Types: Cart

## `Cart`

*Interface*

A buyer's cart: its lines plus the server-computed totals.

Totals are ALWAYS computed server-side from the captured line prices and are
returned fresh on every call. Never re-derive them client-side from a stale
copy: read Cart.subtotalCents and Cart.totalCents as given.

There is no item-count field on this shape. Count lines with `items.length`,
and sum units with `items.reduce((n, i) => n + i.quantity, 0)`. The two differ:
one line holding a quantity of 5 is ONE line and FIVE units.

| Property | Type | Optional | Description |
| --- | --- | --- | --- |
| `currency` | `string` | No | ISO 4217 currency code the totals are expressed in (e.g. `'EUR'`), fixed per site. |
| `id` | `string` | No | The cart's opaque wire id (prefixed `'cart_...'`). Stable for the life of the cart<br>through every add, update, and remove.<br><br>A CartService.claim is the one exception: if the buyer already had a cart<br>of their own, the guest lines are folded into THAT cart and the id you held is<br>retired, so the claim resolves a different id. Always re-read `id` from the claim<br>response rather than keying persistent state on a pre-sign-in value. |
| `items` | `CartLineItem[]` | No | The cart lines, one per variant. Empty for a cart whose every line was removed. |
| `removedLines` | `RemovedCartLine[]` | Yes | Lines the server AUTO-REMOVED during the call that returned this cart, because<br>their variant is no longer sellable (product unpublished, variant retired, or<br>variant deleted). Present ONLY when this call pruned something, so it is a<br>per-call report, never a standing list. Use it to tell the buyer an item was<br>dropped and why. Absent (`undefined`) when nothing was removed, which is the<br>steady state once a cart is healed.<br><br>These lines are already gone from Cart.items and from the totals: the<br>cart you receive is the healed one. Do not re-add or re-total from them. |
| `subtotalCents` | `number` | No | Sum of every line subtotal, in minor currency units (cents). Computed server-side on each mutation. |
| `totalCents` | `number` | No | Amount payable in minor currency units (cents). Equal to Cart.subtotalCents today; shipping, discounts, and tax are later additions. |


---

## `CartLineInput`

*Interface*

Which variant to add or update, and how many units.

| Property | Type | Optional | Description |
| --- | --- | --- | --- |
| `quantity` | `number` | No | Number of units. Integer from 1 to 999.<br><br>The meaning differs by method: CartService.addLine ADDS this many to<br>any existing line, while CartService.updateLine SETS the line to<br>exactly this many. |
| `variantId` | `string` | No | The variant's opaque wire id (prefixed `'var_...'`), taken from a product's `variants[].id`. |


---

## `CartLineItem`

*Interface*

A single line in the cart: one product variant and how many of it.

Every descriptive field is a SNAPSHOT taken when the item was added, not a live
read of the catalogue. A later price change or rename by the merchant does not
rewrite an existing line, so what the buyer sees is what they were quoted.

A line is addressed by its CartLineItem.variantId, never by a line id:
there is no separate line identifier on this surface.

| Property | Type | Optional | Description |
| --- | --- | --- | --- |
| `optionValues` | `CartLineOptionValue[]` | No | Ordered option pairs identifying the chosen variant. Empty array for a product with no options. |
| `quantity` | `number` | No | How many units of this variant are in the cart. Integer, 1 or more, capped at 999 per line. |
| `subtotalCents` | `number` | No | This line's total in minor currency units: `unitPriceCents` times `quantity`. Computed server-side. |
| `thumbnail` | `string \| null` | No | Absolute URL of the line's preview image, snapshotted at add time. This is the PRODUCT's primary image, not a variant-specific one, so two lines of the same product share it. `null` when the product has no image. |
| `title` | `string` | No | Product name snapshotted at add time. Always non-empty. |
| `unitPriceCents` | `number` | No | Price of ONE unit in minor currency units (cents), captured when the item was added. |
| `variantId` | `string \| null` | No | The variant's opaque wire id (prefixed `'var_...'`). Pass it to<br>CartService.updateLine or CartService.removeLine to act on this line.<br><br>`null` only in the rare defensive case now. A line whose catalogue variant the<br>merchant permanently deleted is UNSELLABLE, so the server auto-removes it on your<br>next cart call and reports it in Cart.removedLines, rather than leaving it<br>in `items`. You normally see such a line once, in `removedLines`, not here. If a<br>`null` ever does reach `items`, render it read-only: no line route can address it. |
| `variantSku` | `string \| null` | No | Merchant stock-keeping unit snapshotted at add time. `null` when the merchant set none. |
| `variantTitle` | `string \| null` | No | Variant name snapshotted at add time (e.g. `'Medium / Navy'`). `null` for a product with a single unnamed variant. |


---

## `CartLineOptionValue`

*Interface*

One resolved option pair on a cart line, snapshotted when the item was added
(e.g. `{ option: 'Size', value: 'M' }`). Render these to tell two lines of the
same product apart. Empty for a product with no options.

| Property | Type | Optional | Description |
| --- | --- | --- | --- |
| `option` | `string` | No | Option name as the merchant labelled it (e.g. `'Size'`, `'Colour'`). |
| `value` | `string` | No | The chosen value for that option (e.g. `'M'`, `'Navy'`). |


---

## `CartWithToken`

*Interface*

A Cart that may additionally carry the guest cart token.

`cartToken` is present on exactly ONE response in a cart's life: the
CartService.addLine call that first creates a cart for a buyer who is
not signed in. It is absent from every later response and from every response
to a signed-in buyer.

The SDK captures it automatically, so a single-page session needs nothing
extra. Persist it yourself only to survive a page reload: read it here (or
from CartService.getCartToken) and hand it back with
CartService.setCartToken on the next client.

Extends: `Cart`

| Property | Type | Optional | Description |
| --- | --- | --- | --- |
| `cartToken` | `string` | Yes | The guest cart token, returned once when a guest cart is first created and<br>never recoverable afterwards. `undefined` on every other response.<br><br>Treat it as a secret: whoever holds it can read and change that cart. Store<br>it per browser, never in a shared or server-side cache keyed by anything<br>other than the individual visitor. |
| `currency` | `string` | No | ISO 4217 currency code the totals are expressed in (e.g. `'EUR'`), fixed per site. |
| `id` | `string` | No | The cart's opaque wire id (prefixed `'cart_...'`). Stable for the life of the cart<br>through every add, update, and remove.<br><br>A CartService.claim is the one exception: if the buyer already had a cart<br>of their own, the guest lines are folded into THAT cart and the id you held is<br>retired, so the claim resolves a different id. Always re-read `id` from the claim<br>response rather than keying persistent state on a pre-sign-in value. |
| `items` | `CartLineItem[]` | No | The cart lines, one per variant. Empty for a cart whose every line was removed. |
| `removedLines` | `RemovedCartLine[]` | Yes | Lines the server AUTO-REMOVED during the call that returned this cart, because<br>their variant is no longer sellable (product unpublished, variant retired, or<br>variant deleted). Present ONLY when this call pruned something, so it is a<br>per-call report, never a standing list. Use it to tell the buyer an item was<br>dropped and why. Absent (`undefined`) when nothing was removed, which is the<br>steady state once a cart is healed.<br><br>These lines are already gone from Cart.items and from the totals: the<br>cart you receive is the healed one. Do not re-add or re-total from them. |
| `subtotalCents` | `number` | No | Sum of every line subtotal, in minor currency units (cents). Computed server-side on each mutation. |
| `totalCents` | `number` | No | Amount payable in minor currency units (cents). Equal to Cart.subtotalCents today; shipping, discounts, and tax are later additions. |


---

## `RemovedCartLine`

*Interface*

One entry in Cart.removedLines: a line the server AUTO-REMOVED from the
cart during the call that returned this cart, because its variant is no longer
sellable (the merchant unpublished the product, retired the variant, or deleted it).

It carries only what a storefront needs to tell the buyer "this item is no longer
available and was removed". It is a report of what THIS call pruned, not a standing
list: a later call that removes nothing omits `removedLines` entirely.

| Property | Type | Optional | Description |
| --- | --- | --- | --- |
| `reason` | `"unavailable"` | No | Machine-readable removal reason. Currently always `'unavailable'`; treat any other value as unavailable too. |
| `title` | `string` | No | Product name snapshotted when the item was added, for the "removed" message. Always non-empty. |
| `variantId` | `string \| null` | No | The removed variant's wire id (prefixed `'var_...'`), or `null` when its catalogue<br>variant had been hard deleted. Present so you can match the removal against a line<br>you were rendering; there is nothing to act on, the line is already gone. |
| `variantTitle` | `string \| null` | No | Variant name snapshotted when the item was added (e.g. `'Medium / Navy'`), or `null` when unset. |