Guide

Cart sessions

Create and own a Throttle cart directly from the browser — no backend required. Cart sessions are the front door for JAMstack / static storefronts that don't run a server with a secret key.

Typed SDK + React hook
Prefer a typed client? CartSessionClient in @usethrottle/cart wraps every endpoint below — create/resume a session, then addItem, selectShipping, applyDiscount, checkout. In React, the useCartSession hook in @usethrottle/checkout-react adds reactive cart state + automatic localStorage persistence. The raw HTTP API is documented here for reference.

How it works

Server-side integrations build carts with a secret sk_ key. A frontend-only storefront can't hold a secret key, so it uses a cart session instead:

  • You create a cart session with your storefront quote token (qt_… — the same token used for shipping/tax quotes, from the dashboard Shipping & Tax page or POST /api/v1/shipping-tax/quote-tokens) from an allowed origin. Quote tokens minted before qt_ start with pk_ and keep working. A pk_ publishable API key is a different credential and is refused with 401 invalid_quote_token.
  • Throttle creates the cart and returns an opaque cart_… session id. That id is a bearer capability scoped to exactly one cart — hold it client-side (e.g. in localStorage) and use it to add, update, and remove items.
  • Because the cart lives in Throttle from the first add-to-cart, you get abandoned-cart recovery and a clean hand-off to checkout for free.
Two gates, no API key
Creation is authorized by your publishable token + the application origin allowlist. Every later call is authorized by possession of the opaque cart_… id + origin. No secret key is ever exposed to the browser, and a session can only ever touch its own cart.

Set your allowed origins first

Cart-session requests are rejected unless the request Origin is on the application's allowlist (the same allowlist used by embedded checkout and quotes). Set it via PUT /api/v1/embed-config. A resolved cart also accepts a request that sends neither Origin nor Referer, as a mobile app does.

Create a cart session

bash
curl -X POST https://api.usethrottle.dev/api/v1/cart-sessions \
  -H "Origin: https://shop.example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "7f9d4c8a-5b2e-4f16-9a73-2d1e5c8b6f40",
    "environmentId":  "a1b2c3d4-...",
    "quoteToken": "qt_...",
    "currency": "USD"
  }'

Returns cartSessionId (the cart_… token), expiresAt, a branding block ( logoUrl, primaryColor, merchantName — each nullable), and a cart snapshot. The same branding block is also returned by GET /api/v1/cart-sessions/{id}, so a storefront rendering its own cart UI can brand it without a separate call.

Build the cart

bash
# Add an item
curl -X POST https://api.usethrottle.dev/api/v1/cart-sessions/cart_<id>/items \
  -H "Origin: https://shop.example.com" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Premium Widget", "unitPrice": 2999, "quantity": 2 }'

# Update an item
curl -X PATCH https://api.usethrottle.dev/api/v1/cart-sessions/cart_<id>/items/<itemId> \
  -H "Origin: https://shop.example.com" -H "Content-Type: application/json" \
  -d '{ "quantity": 3 }'

# Remove an item
curl -X DELETE https://api.usethrottle.dev/api/v1/cart-sessions/cart_<id>/items/<itemId> \
  -H "Origin: https://shop.example.com"

# Read the current cart
curl https://api.usethrottle.dev/api/v1/cart-sessions/cart_<id> \
  -H "Origin: https://shop.example.com"

quantity is an integer between 1 and 10,000 on both add and update. Above that the request is rejected with Quantity cannot exceed 10000. — a cart line is not a bulk order; larger asks belong on the quote surface.

The add-item route (and the SDK's addItem) accepts the same recurring block as the Cart API, so a browser cart can hold subscription lines. The limits and codes are identical: see Cart API → Subscription lines.

Cart badge: just the number

A storefront header shows a count next to the cart icon on every page load. Reading it from GET /api/v1/cart-sessions/{id} works, but that response carries the line items, both addresses, the buyer's email and their notes — the whole cart, shipped to every page of the site, to render one integer. /summary is the small read for it:

bash
curl https://api.usethrottle.dev/api/v1/cart-sessions/cart_<id>/summary \
  -H "Origin: https://shop.example.com"

# {
#   "data": {
#     "cartSessionId": "cart_<id>",
#     "status": "active",
#     "unitCount": 4,
#     "total": 12497,
#     "currency": "USD"
#   }
# }

unitCount counts units, not distinct lines: a cart holding 1 stand, 2 notebooks and 1 keyboard reports 4, not 3. The same field is on the cart object every other cart-session endpoint returns, so a page that already has the cart doesn't need this call.

The typical shape on a storefront: restore the session id from localStorage on page load, draw the number, and forget the id once the session is finished.

ts
import { CartSessionClient } from '@usethrottle/cart';

const savedId = localStorage.getItem('throttle_cart_session');
const badge = document.querySelector('#cart-badge');

if (savedId && badge) {
  // forSession() needs no quote token — the opaque cart_ id is the credential.
  const { unitCount, status } = await CartSessionClient.forSession(savedId).summary();

  badge.textContent = String(unitCount);
  badge.hidden = unitCount === 0;

  // Only these two mean the cart is done. Drop the id so the next add-to-cart
  // starts a fresh session. Do NOT test `status !== 'active'`: a cart
  // mid-payment reports 'checkout', and the checkout cancel path reopens it.
  if (status === 'expired' || status === 'converted') {
    localStorage.removeItem('throttle_cart_session');
  }
}

A finished session answers 200 with zeros — unitCount: 0, total: 0, currency: null — and a status of "expired" or "converted". A third value, "checkout", means the cart is mid-payment: keep the id, because the checkout cancel path reopens that cart and the buyer will want it back. This is the one endpoint that does not send cart_session_expired (410): a badge runs on every page, and drawing a zero shouldn't need a try/catch. An id that was never issued is still a cart_session_not_found (404) — that is a bug in the integration, not a finished cart.

A read stays a read
A cart the abandoned-cart sweep has taken reports its real unitCount with status: "active" — the buyer can still come back to it — and the summary never reopens it. Only a write does that, so a link prefetcher or an email scanner hitting a badge cannot resurrect a cart with nobody present.

Buyer details

PATCH /api/v1/cart-sessions/{id} sets buyer-editable fields on the cart: customerEmail and notes, both optional. Send null for either to clear it. The body must carry at least one of the two — an empty object is rejected with Provide at least one of customerEmail or notes.

On a cart backed by an external cart provider, customerEmail is rejected with mode_not_supported (422) rather than accepted and dropped; notes works on both providers.

bash
curl -X PATCH https://api.usethrottle.dev/api/v1/cart-sessions/cart_<id> \
  -H "Origin: https://shop.example.com" -H "Content-Type: application/json" \
  -d '{ "customerEmail": "buyer@example.com", "notes": "Leave at the door" }'
customerEmail is what enables recovery
A guest cart is invisible to abandoned-cart recovery until it has a known email. Setting customerEmail here — even without a full customer record — is what makes the cart eligible for the cart.abandoned sweep and recovery email described in Cart states.

Shipping & discounts

Fetch live rates from POST /api/v1/shipping-tax/quotes (same publishable token), then select a method on the session. Apply a promo code the same way.

bash
# Select a shipping method
curl -X POST https://api.usethrottle.dev/api/v1/cart-sessions/cart_<id>/shipping \
  -H "Origin: https://shop.example.com" -H "Content-Type: application/json" \
  -d '{ "methodId": "fedex_ground", "displayName": "FedEx Ground", "rateAmount": 599 }'

# Apply a discount code
curl -X POST https://api.usethrottle.dev/api/v1/cart-sessions/cart_<id>/discount \
  -H "Origin: https://shop.example.com" -H "Content-Type: application/json" \
  -d '{ "code": "SAVE10" }'
Resolved carts and resolved-lines-only stores price shipping themselves
On a resolved cart, and on every cart session of an environment with resolved lines only on, the browser names a method and Throttle stores its own quote: send just methodId. See Shipping on resolved carts.

The method id dashboard_custom is reserved for a merchant-set charge from the dashboard order builder, and quote_shipping for the shipping an accepted quote fixed. Selecting either on an unlocked cart session answers 400 validation_error; on a locked cart Throttle quotes the method itself, offers neither, and answers 422 shipping_method_unavailable. While a cart's selected method is quote_shipping, selecting another method or DELETE /shipping also answers 400 validation_error: the buyer agreed to that shipping.

Hand off to checkout

When the buyer is ready, convert the cart session into a checkout session and redirect them to the returned checkoutUrl. By default this marks the cart session converted (no further edits). Pass keepOpen: true to leave it active instead, so a buyer who backs out of checkout returns to a live cart rather than an expired one — Throttle's own hosted cart page sets this.

bash
curl -X POST https://api.usethrottle.dev/api/v1/cart-sessions/cart_<id>/checkout-session \
  -H "Origin: https://shop.example.com" -H "Content-Type: application/json" \
  -d '{
    "returnUrl": "https://shop.example.com/thanks",
    "cancelUrl": "https://shop.example.com/cart",
    "keepOpen": true
  }'

The body also takes an optional clientContext: the buyer's GA4 client and session ids, UTMs, click ids and consent, so the server-sent purchase joins their visit. @usethrottle/cart attaches Throttle.analyticsContext() for you when the loader is on the page. See Google Analytics 4 and GTM.

returnUrl and cancelUrl must be http or https URLs: any other scheme, such as javascript: or data:, answers 400 invalid_url with details.field, and no checkout session is created. Hosted checkout only ever redirects to an http(s) URL; anything else sends the buyer to Throttle's /complete page.

If the cart holds a subscription plan line, the hand-off carries the plan's recurring intent over from the cart, so the subscription is created when the buyer pays. If the intent cannot be recovered the hand-off is refused before any charge: 422 subscription_terms_undeterminable, or 422 recurring_customer_required when there is no buyer email to inherit or send. Shipping is kept for carts that also hold physical goods. See Starting checkout from an existing cart .

Skip the UI: Throttle's hosted cart page

Don't want to build cart UI at all? Send the buyer to Throttle's own hosted cart page instead — it renders the same session, branded with the branding block above, and hands off to hosted checkout itself.

ts
import { CartSessionClient } from '@usethrottle/cart';

const cart = new CartSessionClient({ applicationId, environmentId, quoteToken });

const session = await cart.create({
  currency: 'USD',
  metadata: {
    returnUrl: 'https://shop.example.com/thanks',
    cancelUrl: 'https://shop.example.com/cart',
    storefrontUrl: 'https://shop.example.com',
  },
});

await cart.addItem({ name: 'Premium Widget', unitPrice: 2999, quantity: 2 });

location.href = cart.hostedCartUrl();

returnUrl, cancelUrl, and storefrontUrl are all optional. Each is read back off the session's metadata by the hosted page itself. At create time only the scheme is checked: a value with any scheme other than http or https (such as javascript:) answers 400 invalid_url naming metadata.<field>:

  • Omit storefrontUrl and the hosted page simply doesn't render a "Continue shopping" button — checkout still works.
  • Omit returnUrl and a completed order lands the buyer on Throttle's own /complete page instead of yours.
  • Omit cancelUrl and backing out of checkout returns the buyer to this same hosted cart page (it stays live — the hand-off is sent with keepOpen: true).

One hook for the whole flow: useThrottleCheckout

useThrottleCheckout (in @usethrottle/checkout-react) wraps all of the above: it binds totals and selectedMethod straight to the cart (no shadow copy to drift), locks shipping in one call via selectMethod, exposes a status state machine, and auto-recovers from a stale cart — if the cart was converted by a completed order or abandoned, it rebuilds a fresh session from the last-known line items and retries ( status === 'recovering'). createSession returns the checkoutSessionId for <PaymentEmbed>.

tsx
import { useThrottleCheckout, PaymentEmbed } from '@usethrottle/checkout-react';

function Checkout() {
  const {
    addItem, selectMethod,   // one-call select — returns the recomputed cart
    totals, selectedMethod,  // bound to the cart; never a stale copy
    status,                  // 'idle' | 'loading' | 'recovering' | 'ready' | 'error'
    createSession,           // → { checkoutSessionId } for <PaymentEmbed>
  } = useThrottleCheckout({ applicationId, environmentId, quoteToken });

  const start = async () => {
    const { checkoutSessionId } = await createSession({
  returnUrl: 'https://shop.example.com/thanks',
  cancelUrl: 'https://shop.example.com/cart',
    });
    setSessionId(checkoutSessionId);
  };

  return sessionId
    ? <PaymentEmbed sessionId={sessionId} parentOrigin={location.origin} />
    : <button onClick={start} disabled={status === 'loading'}>Pay {totals?.total}</button>;
}
Address collection lives in the embed
The hook does not write addresses to the cart — the hosted/full checkout embed collects shipping & billing. The hook focuses on cart state, shipping selection, totals, recovery, and the session handoff.

Resolved carts: lines priced by an installed app

A resolved cart takes no prices from the browser. Create the session with lineResolver: { extensionId } naming an installed app with a line resolver (for example Product Catalog), then add lines by the app's referenceId. Throttle asks the app for the name, price, stock and limits on every add, quantity change, sign-in merge, refresh and checkout. A session created without lineResolver behaves exactly as described above, unless the environment turns on resolved lines only.

bash
curl -X POST https://api.usethrottle.dev/api/v1/cart-sessions \
  -H "Origin: https://shop.example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "7f9d4c8a-5b2e-4f16-9a73-2d1e5c8b6f40",
    "environmentId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "quoteToken": "qt_...",
    "currency": "USD",
    "lineResolver": { "extensionId": "0b6a3c1e-8d2f-4a5b-9c7d-1e2f3a4b5c6d" },
    "locale": "en-US"
  }'

# Add a line by the app's id for the item. The app sets name, price and image.
curl -X POST https://api.usethrottle.dev/api/v1/cart-sessions/cart_<id>/items \
  -H "Origin: https://shop.example.com" -H "Content-Type: application/json" \
  -d '{ "referenceId": "TSHIRT-BLUE-M", "quantity": 2 }'

# Re-check every line the app owns (send {} as the body)
curl -X POST https://api.usethrottle.dev/api/v1/cart-sessions/cart_<id>/refresh \
  -H "Origin: https://shop.example.com" -H "Content-Type: application/json" \
  -d '{}'
# → { "data": { "cartSessionId": "cart_<id>", "cart": { … }, "changed": false } }
  • currency is required with lineResolver and must be the environment's currency or one of its extra cart currencies ( 422 currency_not_enabled otherwise). An app that is not installed and active in this application and environment answers 422 line_resolver_not_available.
  • The session's metadata may not carry the cart-level keys that change the tax quote: taxTrigger, shippingTaxCode, transport, deliveryTerms, isGoodsSecondHand and exchangeRate. Sending one answers 400 price_locked with details.fields naming them (for example metadata.taxTrigger), and nothing is created. Set them from your server with the secret-key cart routes instead. Other metadata is stored as before.
  • metadata.createdVia is set by Throttle and cannot be sent: it answers 400 validation_error with details.field: "metadata.createdVia".
  • locale (optional, BCP 47 such as en-GB, up to 35 characters) is passed to the app.
  • The cart gains lineResolver: { extensionId } (extensionId is null if the installation is gone) and each line gains resolution: null on a line the app does not own, otherwise { status, code, maxQuantity, minQuantity } with status resolved, refused or stale. Carts created without lineResolver have neither key.

Mobile apps: no Origin needed

A request with neither Origin nor Referer, as a mobile app sends, is accepted for a resolved cart: on its create (with lineResolver) and on every later call of its session. A request that does carry an origin must still be on the allowlist. Unresolved carts keep the origin gate exactly as before.

Adding and changing lines

  • An add on a resolved cart takes only referenceId, quantity (1 to 10,000, default 1) and metadata. Adding a SKU the cart already holds adds to that line. Any other field is a 400 validation_error.
  • unitPrice, name, imageUrl, taxAmount and discountAmount are set by the app. On an add they answer 400 price_locked with details.fields naming them. On a PATCH of a line the app owns, unitPrice, taxAmount and discountAmount answer 400 price_locked; name and imageUrl cannot be sent on any line PATCH (400 validation_error).
  • A quantity change on an owned line is re-checked with the app; a refusal keeps the old quantity. Removing a line works as always.
  • A line can be refused (409 quantity_unavailable or 422 line_not_purchasable), and the app may not answer ( 503 line_resolver_unavailable: nothing changed, retry). A cart holds at most 50 lines priced by one app ( 422 line_limit_reached).

Locked metadata keys. The reserved keys lineResolver and requiresShipping are Throttle's: a browser can never set them on any line of a resolved cart. On a line the app owns, the keys that change a shipping or tax quote or a discount are locked too: itemCode, sku, productType, subscriptionLineItem, shippingProfileIds, taxCategory, taxIncluded, isPreferredProgram, weight, weightUnit, hsCode, productCategory, category, countryOfManufacture, netWeight, grossWeight, shippingWeight, netVolume, productId, variantId and referenceId, plus the snake_case spellings item_code, product_type, requires_shipping, shipping_profile_ids, tax_category, tax_included, is_preferred_program, hs_code, product_category, country_of_manufacture, net_weight, gross_weight, shipping_weight, net_volume, product_id, variant_id and reference_id. Sending one answers 400 price_locked even when the value is unchanged, so don't echo a line's metadata back. On a line the app owns (and on every line when resolved lines only is on), other metadata edits are merged into the stored metadata, not replaced, so a key cannot be removed.

Refresh

POST /api/v1/cart-sessions/{id}/refresh (body {}) asks the app to re-check every line it owns and answers { cartSessionId, cart, changed }. changed is true when a price, name or refusal changed. On an unresolved cart it answers 200 with the cart unchanged and calls nothing. If the app does not answer it is a 503 line_resolver_unavailable and nothing changes. It is rate limited per cart session (30 calls a minute; 429 rate_limit_exceeded).

Shipping on resolved carts

  • Throttle quotes shipping itself; the browser cannot set an amount. Send only methodId (cart.selectShippingMethod({ methodId })). A rateAmount or currency that differs from Throttle's quote answers 400 price_locked; other sent fields (displayName, carrier, serviceCode, estimatedDeliveryDays) are replaced by the quote's.
  • A cart session cannot set an address, so before checkout Throttle usually cannot quote a method: 422 shipping_method_unavailable. Let the buyer choose shipping on the hosted checkout page, where they enter the address. A failed tax quote answers 503 shipping_quote_unavailable.
  • There is no flat-rate fallback: with no method selected, shipping reads as not calculated yet (0).

Checkout hand-off

The hand-off re-checks every owned line with the app and re-quotes the selected shipping method. If anything changed, the new values are applied and the hand-off answers 409 cart_prices_changed with details.cart (the updated cart) and, when shipping moved, details.shipping: { methodId, previousAmount, amount, reason? } (amount is null with reason method_unavailable, quote_unavailable or shipping_currency_unsupported; see extra cart currencies). Show the cart and let the buyer check out again. A line the app still refuses answers 422 line_not_purchasable with details.lines. Pay on the returned checkoutUrl: its checkout session only completes for what the hosted page last priced. See the completion guard for the surfaces that always answer 409.

Signing in

Claiming a resolved cart after sign-in merges the customer's newest same-currency cart into it and re-prices the owned lines for that customer. The claim moves the lines: the merged cart is left empty and abandoned, and a cart in another currency is left untouched. A storefront on another device finds the customer's cart with GET /v1/storefront/me/cart and writes to it with the session that answer carries. The claim answers 200 with linesStale and, when the merge could not land, mergeSkipped: { reason }; sign-in never fails because of a merge. See Sign-in merges.

Switching currency: absorb a cart

A cart never changes currency. To let a buyer switch, hold one cart per currency and move the lines across with POST /api/v1/cart-sessions/{id}/absorb. The id in the path is the target cart; the body names the source: { "fromSessionId": "..." } (no other keys). Both sessions are authorised by their ids, like every cart-session route, and the route sits behind the same origin check as the other cart-session writes. It never creates a cart: the target must already exist, so the production currency gate is untouched.

The lines move, are re-priced by the app that owns them in the target's currency, and the source is closed as abandoned with reason merged. It answers 200 { data: { cart }, meta: { warnings } }. A merged cart is not abandoned value: it is left out of abandoned-cart totals and no recovery email is sent for it. Writing to a merged cart answers 409 cart_not_open.

WarningMeaning
lines_removedLines that could not move, as lines: [{ referenceId, code }]. The code is the resolver's, or unowned_line_currency for a line you priced yourself in another currency.
discount_droppedThe code does not apply in the target currency. Carries discountCode and a message such as "This code can't be used for orders in GBP".
lines_staleThe target's owned lines could not all be re-priced just now; refresh the cart.
Status and codeWhen
400 invalid_requestfromSessionId is the target itself.
400 validation_errorAn extra key in the body.
403 cart_owner_mismatchThe source belongs to another customer. Ownership is never reassigned.
404 cart_session_not_foundEither session is unknown, or belongs to another workspace, application or environment.
409 cart_not_openEither cart is converted, in checkout, expired or merged.
410 cart_session_expiredThe source session has ended.
422 cart_resolver_mismatchThe source holds owned lines the target's resolver does not price.
429 rate_limit_exceededToo many requests.
503 line_resolver_unavailableThe resolver did not answer. Nothing changed; retry.

A signed-in buyer finds the cart for another currency with GET /v1/storefront/me/cart?currency=; a guest keeps the cart session id per currency. The cart.abandoned event for the closed source is internal (reason merged_on_currency_switch) and is not sent to webhook endpoints. A source the idle sweep already abandoned emits nothing.

In @usethrottle/cart

CartSessionClient adds lineResolver and locale on create(), addResolvedItem(), refresh() (it sends {}; a cart session only) and selectShippingMethod(). Every error below is a typed class that extends ThrottleApiError, so existing instanceof ThrottleApiError and e.code checks keep working.

ts
import {
  CartSessionClient,
  QuantityUnavailableError,
  LineNotPurchasableError,
  LineResolverUnavailableError,
  CartPricesChangedError,
} from '@usethrottle/cart';

const cart = new CartSessionClient({ applicationId, environmentId, quoteToken });

await cart.create({
  currency: 'USD', // required with lineResolver; the environment's currency or an extra cart currency
  lineResolver: { extensionId: '0b6a3c1e-8d2f-4a5b-9c7d-1e2f3a4b5c6d' },
  locale: 'en-US', // optional, passed to the app
});

try {
  await cart.addResolvedItem({ referenceId: 'TSHIRT-BLUE-M', quantity: 2 });
} catch (e) {
  if (e instanceof QuantityUnavailableError) showMessage(`Only ${e.maxQuantity ?? 0} available`);
  else if (e instanceof LineNotPurchasableError) showMessage('No longer available');
  else if (e instanceof LineResolverUnavailableError) showMessage('Try again in a moment');
  else throw e;
}

// When the buyer comes back to the cart:
const { changed } = await cart.refresh();

try {
  const { checkoutUrl } = await cart.checkout({ returnUrl, cancelUrl });
  location.href = checkoutUrl;
} catch (e) {
  if (e instanceof CartPricesChangedError) {
    if (e.cart) render(e.cart); // the new prices are already applied; show them
  } else throw e;
}
ClassStatus and codeFields
PriceLockedError400 price_lockedfields
QuantityUnavailableError409 quantity_unavailablereason, maxQuantity (or null)
LineNotPurchasableError422 line_not_purchasablereason on an add; lines at checkout
LineResolverUnavailableError503 line_resolver_unavailablereason (or null). Nothing changed; retry.
LineResolverNotAvailableError422 line_resolver_not_availablereason
CurrencyNotEnabledError422 currency_not_enableddetails.currency, details.enabledCurrencies
ResolvedLinesRequiredError422 resolved_lines_requiredThe store only accepts resolved lines.
LineLimitReachedError422 line_limit_reacheddetails.maxLines
CartPricesChangedError409 cart_prices_changedcart, shipping (or null)
ShippingMethodUnavailableError422 shipping_method_unavailable—
ShippingQuoteUnavailableError503 shipping_quote_unavailableNothing changed; retry.
AmountTooLargeError422 amount_too_largeLower the quantity.
CartChangedError409 cart_changedThe cart changed during the add; retry.

Only allow prices from installed apps

An opt-in setting per application and environment, off by default. When it is on, no cart session in that environment takes a browser price, resolved or not: shoppers' browsers can't set or change prices, and every cart line must be priced by an installed app such as Product Catalog. It is for stores whose products all come from an app with a line resolver. Turn it on in the dashboard under App settings → General → Cart pricing (the toggle is labelled Only allow prices from installed apps, with the hint "recommended with Product Catalog"), or with PUT /api/v1/embed-config and { "resolvedLinesOnly": true }.

  • Adds. A price field or a locked metadata key is 400 price_locked. On a session created without lineResolver, a well-formed resolved add is 422 resolved_lines_required: create the session with lineResolver.
  • Creating a session. The cart-level tax override keys in metadata are 400 price_locked, with or without lineResolver.
  • Existing lines. Quantity changes and removals of lines that were already in a cart keep working. Their unitPrice, taxAmount, discountAmount and locked metadata keys are 400 price_locked, and metadata edits merge.
  • Shipping. Locked as on a resolved cart: Throttle quotes the method, there is no flat-rate fallback, and the hand-off re-quotes it (a change is 409 cart_prices_changed) and carries the same completion guard.
  • The secret-key cart routes (/api/v1/carts) are not affected.

Who can change it. A dashboard user with the application:settings permission (owner, workspace admin, app admin), or the merchant's own secret sk_ key with embed_config:write. Nothing else can change it: an installed app's API key (even one holding embed_config:write, and whatever the installation's status), an extension session and an OAuth token all get 403 permission_denied, and so does any key Throttle cannot confirm is not an installed app's; a value that is not true or false is 400 validation_error. Each change writes an audit entry, cart_pricing.updated, with the old and new value. GET /api/v1/embed-config (and throttle embed show) returns resolvedLinesOnly and lineResolverInstallations, the number of active installations in this environment whose pinned version has a line resolver. With none, every browser add-to-cart would be refused.

Extra cart currencies

A cart is in the store's main currency unless it asks for another. A merchant can list up to 10 extra currencies per application and environment; a cart may then be created in any of them, and, on a resolved cart, the app's line resolver is asked for prices in that currency. Set them in the dashboard under App settings → General → Cart pricing → Extra cart currencies, a searchable multi-select of the currencies that can be enabled. Each option shows Payable or Not payable ("no payment provider accepts it"), and a not-payable currency can't be added. Chips are removable, and removing one asks for confirmation. Or set them with PUT /api/v1/embed-config and { "cartCurrencies": ["EUR", "GBP"] }. [] clears the list.

  • Every cart path. Extra currencies are allowed on every cart, resolved or not, secret-key or publishable-key. A cart without currency is in the store's main currency; a currency that is not enabled answers 422 currency_not_enabled. The old unresolved-cart 422 currency_mismatch is gone. The rules are on the Multi-currency page.
  • Amounts are per currency, and a missing amount is refused. Throttle never converts an amount, so a currency with no entry is not offered:
    • a discount code with no amount in the cart's currency answers 422 discount_currency_unsupported with the message "This code can't be used for orders in EUR.", and nothing is applied. A code whose EUR entry is later removed is dropped from the cart at its next recalculation. Percentage codes with no minimum work in every currency;
    • a shipping method with no amount in the cart's currency is not offered, and selecting it answers 422 shipping_method_unavailable;
    • on POST /api/v1/carts/{id}/shipping, a currency other than the cart's answers 422 shipping_currency_unsupported on every cart; without one, the rate is stored in the cart's currency. The same holds for currency and selectedShipping.currency on POST /api/v1/shipping-tax/external-snapshots, and a refused snapshot saves nothing.
  • Shipping on an extra-currency cart. Each shipping method carries an amount per currency (currencyAmounts). A cart in EUR is offered the methods that have a EUR amount, priced from it. If a selected method's EUR amount is raised or lowered, the hand-off (POST /api/v1/cart-sessions/{id}/checkout-session) stores the fresh amount and answers 409 cart_prices_changed with shipping; if the entry is removed, it clears the method as unavailable (method_unavailable). A selection in a currency other than the cart's still answers 422 shipping_currency_unsupported with details.shipping and keeps the selection. Choose another method and check out again.
  • Validation. Each entry is upper-cased and must be a three-letter code (^[A-Z]{3}$); entries must be unique, at most 10, and none may be the environment's own currency. Each must also be an enable-able currency: an ISO 4217 currency with 0, 2 or 3 decimals, not a fund or test code, whose processor decimal places are confirmed. Amounts are in the currency's own minor units (JPY has none, KWD has three). A four-decimal currency, a code without a minor unit or for testing (XAU, XDR, XTS, XXX), a fund code, a code with unconfirmed processor decimals (HUF, IDR, COP, ISK) and any unknown code are refused, for example "HUF isn't supported yet: payment processors handle its decimal places differently." The refusal is always 400 validation_error with details[].path naming the field or the entry, such as cartCurrencies.1.
  • Who can change it. The same callers as resolved lines only: a dashboard user with application:settings or the merchant's own sk_ key. An installed app's API key, an extension session and an OAuth token get 403 permission_denied. Each change writes a cart_pricing.updated audit entry with cartCurrencies: { from, to }.
  • GET /api/v1/embed-config returns cartCurrencies, an array that is empty when none are set.
  • Lines the app doesn't price. Unless resolved lines only is on, a resolved cart can also hold lines priced by the browser. Throttle takes that price as the cart's currency and cannot tell if it was meant in another one. For a storefront selling in several currencies, turn on resolved lines only.
  • Changing the list later. The list is checked when a cart is created, so removing a currency does not affect its open carts: they keep adding lines and checking out in it while the app still prices it. If the environment's own currency changes, carts in the old one are treated as extra-currency carts: a fixed_amount discount on them is removed at their next recalculation. Saving a list that holds the new environment currency answers 400 validation_error; remove it from the list.
  • Analytics. Revenue and product analytics add order amounts across currencies without converting them.

Endpoints

  • POST /api/v1/cart-sessions — create a cart + session.
  • GET /api/v1/cart-sessions/{id} — read the session + cart.
  • GET /api/v1/cart-sessions/{id}/summary — unit count + total, nothing else.
  • PATCH /api/v1/cart-sessions/{id} — set customerEmail / notes.
  • POST /api/v1/cart-sessions/{id}/items — add an item.
  • PATCH /api/v1/cart-sessions/{id}/items/{itemId} — update an item.
  • DELETE /api/v1/cart-sessions/{id}/items/{itemId} — remove an item.
  • POST /api/v1/cart-sessions/{id}/shipping — select a shipping method.
  • DELETE /api/v1/cart-sessions/{id}/shipping — clear the selected method.
  • POST /api/v1/cart-sessions/{id}/discount — apply a discount code.
  • DELETE /api/v1/cart-sessions/{id}/discount — remove the discount.
  • POST /api/v1/cart-sessions/{id}/refresh — re-check a resolved cart's lines with the app.
  • POST /api/v1/cart-sessions/{id}/checkout-session — hand off to checkout.
Errors
invalid_quote_token (401) — bad token, app/environment, or origin. origin_not_allowed (403) — origin not on the allowlist. cart_session_expired (410) — session is no longer active; details.reason is "expired" (past expiresAt) or "converted" (already handed off to checkout), and details.storefrontUrl echoes back whatever the session's metadata held, for a "back to the store" link. A cart the abandoned-cart sweep has taken is not a 410: the session still reads, reporting "abandoned", and the first write reopens it — so both a recovery link and a buyer returning from checkout land on a working cart. Reads leave it alone, so a link scanner cannot resurrect a cart on the buyer's behalf. item_not_found (404) — the item isn't in this session's cart. mode_not_supported (422) — PATCH of a field this cart's provider cannot store. rate_limit_exceeded (429) — too many POST /cart-sessions creates from one client; back off and retry. Resolved carts and the resolved-lines-only setting add their own codes (such as price_locked, line_resolver_unavailable and cart_prices_changed): see the line resolver error reference.