Class: CartClient
Constructors
Constructor
new CartClient(
client):CartClient
Parameters
client
Returns
CartClient
Methods
addItems()
addItems(
cartId,lines):Promise<CartMutationOutcome>
Add line items to an existing cart.
Parameters
cartId
string
lines
Returns
Promise<CartMutationOutcome>
applyGiftCard()
applyGiftCard(
input):Promise<CartMutationOutcome>
Apply gift card to cart (stackable with discount codes, FIFO consumption). Balance NOT debited yet — actual deduction at cartComplete.
Parameters
input
Returns
Promise<CartMutationOutcome>
clearPaymentSelection()
clearPaymentSelection(
input):Promise<CartMutationOutcome>
Clear all payment selection state on the cart — atomically NULLs the method
type, provider code, instrument code and legacy method ID. Idempotent —
repeated calls produce the same final state. Use it for "back to payment
method selection" accordion UI flows. The cart MUST be ACTIVE (CONVERTED
carts throw with ALREADY_COMPLETED).
Parameters
input
CartClearPaymentSelectionInput
Returns
Promise<CartMutationOutcome>
complete()
complete(
input):Promise<CartCompleteOutcome>
Complete cart → create Order. Returns { order, warnings }.
Idempotent on idempotencyKey (auto-generated from cartId + minute timestamp
if omitted).
order is populated on success — assertNoUserErrors throws first if the
mutation reported userErrors. The cart is NOT returned: after completion it
is CONVERTED/locked, so drop your local cart and work with the Order. The
Order carries canCreatePayment + paymentMethodType so the storefront can
decide the payment flow. paymentUrl is intentionally NOT in the response
— the payment session is created by a separate paymentCreate mutation
after checking order.canCreatePayment.
Parameters
input
Returns
Promise<CartCompleteOutcome>
create()
create(
input?):Promise<CartSecretRevealOutcome>
Create a new cart, optionally with initial lines. The result carries the
one-time secret (the cart access capability) — persist it into the
composite cart-id cookie. The SDK cart manager does this for you.
Parameters
input?
Returns
Promise<CartSecretRevealOutcome>
createPayment()
createPayment(
input):Promise<PaymentSessionFragment>
Initiate a payment session for an order created by complete(). Call this
when order.canCreatePayment is true — orders with an offline payment
method (cash on delivery, manual bank transfer) skip this step.
input.returnUrl / input.cancelUrl are optional; when supplied they must
point to a verified domain of the shop (the server rejects others). The
returned PaymentSession is flow-aware — branch on session.flow:
ONLINE_REDIRECT → redirect to session.redirectUrl, ONLINE_EMBEDDED →
render a widget with session.clientSecret, INSTANT_DIRECT → already
settled, read session.status.
Idempotent — calling it again for the same order returns the existing
still-valid session instead of creating a duplicate (safe to retry).
Throws a StorefrontError (carrying userErrors) when the order can't be
paid — inspect .userErrors[0].code (PaymentErrorCode).
Parameters
input
Returns
Promise<PaymentSessionFragment>
downgradeOnLogout()
downgradeOnLogout(
cartId):Promise<CartMutationOutcome>
Downgrade a cart to guest on logout — clears the customer association,
contact details, addresses and saved-payment selection while keeping line
items, coupons, shipping method, currency and notes. The access secret is
NOT rotated, so the stored cookie stays valid. Capability-gated by the
x-cart-secret header (a missing / wrong secret throws CART_NOT_FOUND).
Parameters
cartId
string
Returns
Promise<CartMutationOutcome>
get()
get(
cartId):Promise<CartFragment|null>
Fetch existing cart by ID. Returns null if cart doesn't exist or has expired.
Parameters
cartId
string
Returns
Promise<CartFragment | null>
getAvailablePaymentMethods()
getAvailablePaymentMethods():
Promise<AvailablePaymentMethodsFragment>
Shop-level list of active payment methods. Returns the raw payload from the backend:
methods[]— sorted by the merchant's display position.defaultMethod— the merchant-flagged pre-selection (may be null when none is configured). Prefer this over scanningmethods.find(isDefault)— the merchant may override the default independently of per-method flags.
Returns
Promise<AvailablePaymentMethodsFragment>
getAvailableShippingMethods()
getAvailableShippingMethods(
cartId,address):Promise<AvailableShippingMethodsPayload|null>
Cart-aware list of shipping methods available for the given destination.
Resolves with null when the cart does not exist or has expired —
symmetric with CartClient.get(cartId). Otherwise resolves with
AvailableShippingMethodsPayload:
methods[]— methods available for this cart at the destination, each carryingdeliveryType(HOME/PICKUP_POINT/LOCKER).freeShippingProgress— best free-shipping progress across all returned methods (use for a single banner above the picker).userErrors[]— populated by the backend for business conditions (e.g.DIGITAL_ONLY_NO_SHIPPINGfor a cart with no shippable lines,NO_SHIPPING_METHODSfor an unsupported address). Branch onuserErrors[0].code; themessageis localized per the request'sAccept-Languageheader.
Parameters
cartId
string
address
Returns
Promise<AvailableShippingMethodsPayload | null>
getOrderByToken()
getOrderByToken(
token,email?):Promise<OrderFragment|null>
Fetch a guest order by its opaque access token (returned in
complete().order.accessToken). Use on the post-checkout confirmation
page when the buyer is not signed in.
Optional email is matched case-insensitively against the order's buyer
email as defense in depth — on mismatch the call returns null with the
same shape as an invalid token (attackers cannot distinguish the two).
Backend rate-limits this query (5 requests / minute per IP + shop) and responses are uncached.
Parameters
token
string
email?
string
Returns
Promise<OrderFragment | null>
merge()
merge(
guestCartId):Promise<CartMutationOutcome>
Merge the customer's prior cart into the guest cart on login. The guest
cart survives (same id + secret → the stored cookie stays valid),
quantities sum per variant, guest checkout fields win. Requires an
authenticated request — throws (StorefrontError) on
CART_MERGE_REQUIRES_AUTH (anonymous) or CART_CURRENCY_MISMATCH
(different currencies). Inspect err.userErrors[0].code.
Parameters
guestCartId
string
Returns
Promise<CartMutationOutcome>
recoveryRedeem()
recoveryRedeem(
token):Promise<CartSecretRevealOutcome>
Redeem a signed cart-recovery link. On success the cart secret is rotated
and the result carries the NEW one-time secret — persist it into the
composite cart-id cookie (the old secret stops working). Invalid /
expired links throw a StorefrontError carrying userErrors without
leaking cart content.
Parameters
token
string
Returns
Promise<CartSecretRevealOutcome>
removeGiftCard()
removeGiftCard(
input):Promise<CartMutationOutcome>
Remove applied gift card from cart. Re-calculates FIFO amounts for the remaining cards.
Parameters
input
Returns
Promise<CartMutationOutcome>
removeItems()
removeItems(
cartId,lineIds):Promise<CartMutationOutcome>
Remove line items by their line IDs.
Parameters
cartId
string
lineIds
string[]
Returns
Promise<CartMutationOutcome>
selectPaymentMethod()
selectPaymentMethod(
input):Promise<CartMutationOutcome>
Select payment method on the cart. Validates existence + active status; no pre-authorization.
Parameters
input
Returns
Promise<CartMutationOutcome>
selectShippingMethod()
selectShippingMethod(
input):Promise<CartMutationOutcome>
Select shipping method on the cart (typed shippingMethodId — an ID,
not a plain string).
Parameters
input
Returns
Promise<CartMutationOutcome>
setBillingAddress()
setBillingAddress(
input):Promise<CartMutationOutcome>
Set billing address on the cart (independent of the shipping address — pass it even when "billing same as shipping").
Parameters
input
Returns
Promise<CartMutationOutcome>
setShippingAddress()
setShippingAddress(
input):Promise<CartMutationOutcome>
Set shipping address on the cart. Full replace (not patch). Triggers cart re-pricing (tax recalculation per address country/region).
Parameters
input
Returns
Promise<CartMutationOutcome>
updateAttributes()
updateAttributes(
cartId,attributes):Promise<CartMutationOutcome>
Replace the cart's custom { key, value } attribute pairs — free-form
metadata visible to the merchant (delivery instructions, gift-wrap flags,
B2B PO numbers). Semantics is REPLACE-ALL (not merge): pass the full set
each call, an empty array clears all attributes. Backend rejects oversized
sets with CART_ATTRIBUTES_LIMIT_EXCEEDED (max 250 pairs, 255-char keys).
Parameters
cartId
string
attributes
Returns
Promise<CartMutationOutcome>
updateBuyerIdentity()
updateBuyerIdentity(
cartId,buyerIdentity):Promise<CartMutationOutcome>
Update buyer identity (email, phone, country, customer link, languageCode).
Parameters
cartId
string
buyerIdentity
Returns
Promise<CartMutationOutcome>
updateDiscountCodes()
updateDiscountCodes(
cartId,discountCodes):Promise<CartMutationOutcome>
Update discount codes (replaces all existing codes). Pass empty array to clear discounts.
Parameters
cartId
string
discountCodes
string[]
Returns
Promise<CartMutationOutcome>
updateGiftCardRecipient()
updateGiftCardRecipient(
input):Promise<CartMutationOutcome>
Update gift card recipient info on a line item (personalised delivery — recipientEmail, recipientName, message). Required before cartComplete for every gift card line item.
Parameters
input
CartUpdateGiftCardRecipientInput
Returns
Promise<CartMutationOutcome>
updateItems()
updateItems(
cartId,lines):Promise<CartMutationOutcome>
Update line items (quantity, attributes).
Parameters
cartId
string
lines
Returns
Promise<CartMutationOutcome>
updateNote()
updateNote(
cartId,note):Promise<CartMutationOutcome>
Update cart note / gift message.
Parameters
cartId
string
note
string
Returns
Promise<CartMutationOutcome>
validateDiscountCode()
validateDiscountCode(
cartId,discountCode):Promise<Pick<DiscountValidationResult,"isValid"> &object>
Validate a discount code as a preview — a read-only Query, NOT a mutation:
validation must not mutate cart state. Returns { isValid, discount?, error? }
— storefront UI uses it for inline feedback while the customer types a code.
Caching: the storefront should use fetchPolicy: 'network-only' or a
cache key that includes cart.subtotal (discount eligibility may depend
on a minimum order amount).
Parameters
cartId
string
discountCode
string
Returns
Promise<Pick<DiscountValidationResult, "isValid"> & object>