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.