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.
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 orPOST /api/v1/shipping-tax/quote-tokens) from an allowed origin. Quote tokens minted beforeqt_start withpk_and keep working. Apk_publishable API key is a different credential and is refused with401 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. inlocalStorage) 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.
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
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
# 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:
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.
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.
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.
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
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.
# 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" }' 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.
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.
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
storefrontUrland the hosted page simply doesn't render a "Continue shopping" button — checkout still works. -
Omit
returnUrland a completed order lands the buyer on Throttle's own/completepage instead of yours. -
Omit
cancelUrland backing out of checkout returns the buyer to this same hosted cart page (it stays live — the hand-off is sent withkeepOpen: 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>.
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>;
} 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.
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 } } -
currencyis required withlineResolverand must be the environment's currency or one of its extra cart currencies (422 currency_not_enabledotherwise). An app that is not installed and active in this application and environment answers422 line_resolver_not_available. -
The session's
metadatamay not carry the cart-level keys that change the tax quote:taxTrigger,shippingTaxCode,transport,deliveryTerms,isGoodsSecondHandandexchangeRate. Sending one answers400 price_lockedwithdetails.fieldsnaming them (for examplemetadata.taxTrigger), and nothing is created. Set them from your server with the secret-key cart routes instead. Other metadata is stored as before. -
metadata.createdViais set by Throttle and cannot be sent: it answers400 validation_errorwithdetails.field: "metadata.createdVia". -
locale(optional, BCP 47 such asen-GB, up to 35 characters) is passed to the app. -
The cart gains
lineResolver: { extensionId }(extensionIdis null if the installation is gone) and each line gainsresolution: null on a line the app does not own, otherwise{ status, code, maxQuantity, minQuantity }withstatusresolved,refusedorstale. Carts created withoutlineResolverhave 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) andmetadata. Adding a SKU the cart already holds adds to that line. Any other field is a400 validation_error. -
unitPrice,name,imageUrl,taxAmountanddiscountAmountare set by the app. On an add they answer400 price_lockedwithdetails.fieldsnaming them. On aPATCHof a line the app owns,unitPrice,taxAmountanddiscountAmountanswer400 price_locked;nameandimageUrlcannot be sent on any linePATCH(400 validation_error). -
A
quantitychange 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_unavailableor422 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 })). ArateAmountorcurrencythat differs from Throttle's quote answers400 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 answers503 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.
| Warning | Meaning |
|---|---|
lines_removed | Lines 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_dropped | The 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_stale | The target's owned lines could not all be re-priced just now; refresh the cart. |
| Status and code | When |
|---|---|
400 invalid_request | fromSessionId is the target itself. |
400 validation_error | An extra key in the body. |
403 cart_owner_mismatch | The source belongs to another customer. Ownership is never reassigned. |
404 cart_session_not_found | Either session is unknown, or belongs to another workspace, application or environment. |
409 cart_not_open | Either cart is converted, in checkout, expired or merged. |
410 cart_session_expired | The source session has ended. |
422 cart_resolver_mismatch | The source holds owned lines the target's resolver does not price. |
429 rate_limit_exceeded | Too many requests. |
503 line_resolver_unavailable | The 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.
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;
} | Class | Status and code | Fields |
|---|---|---|
PriceLockedError | 400 price_locked | fields |
QuantityUnavailableError | 409 quantity_unavailable | reason, maxQuantity (or null) |
LineNotPurchasableError | 422 line_not_purchasable | reason on an add; lines at checkout |
LineResolverUnavailableError | 503 line_resolver_unavailable | reason (or null). Nothing changed; retry. |
LineResolverNotAvailableError | 422 line_resolver_not_available | reason |
CurrencyNotEnabledError | 422 currency_not_enabled | details.currency, details.enabledCurrencies |
ResolvedLinesRequiredError | 422 resolved_lines_required | The store only accepts resolved lines. |
LineLimitReachedError | 422 line_limit_reached | details.maxLines |
CartPricesChangedError | 409 cart_prices_changed | cart, shipping (or null) |
ShippingMethodUnavailableError | 422 shipping_method_unavailable | — |
ShippingQuoteUnavailableError | 503 shipping_quote_unavailable | Nothing changed; retry. |
AmountTooLargeError | 422 amount_too_large | Lower the quantity. |
CartChangedError | 409 cart_changed | The 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 withoutlineResolver, a well-formed resolved add is422 resolved_lines_required: create the session withlineResolver. - Creating a session. The cart-level tax override keys in
metadataare400 price_locked, with or withoutlineResolver. - Existing lines. Quantity changes and removals of lines that were already
in a cart keep working. Their
unitPrice,taxAmount,discountAmountand locked metadata keys are400 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
currencyis in the store's main currency; acurrencythat is not enabled answers422 currency_not_enabled. The old unresolved-cart422 currency_mismatchis 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_unsupportedwith 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, acurrencyother than the cart's answers422 shipping_currency_unsupportedon every cart; without one, the rate is stored in the cart's currency. The same holds forcurrencyandselectedShipping.currencyonPOST /api/v1/shipping-tax/external-snapshots, and a refused snapshot saves nothing.
-
a discount code with no amount in the cart's currency answers
- 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 answers409 cart_prices_changedwithshipping; if the entry is removed, it clears the method as unavailable (method_unavailable). A selection in a currency other than the cart's still answers422 shipping_currency_unsupportedwithdetails.shippingand 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 always400 validation_errorwithdetails[].pathnaming the field or the entry, such ascartCurrencies.1. - Who can change it. The same callers as resolved lines only: a dashboard user with
application:settingsor the merchant's ownsk_key. An installed app's API key, an extension session and an OAuth token get403 permission_denied. Each change writes acart_pricing.updatedaudit entry withcartCurrencies: { from, to }. -
GET /api/v1/embed-configreturnscartCurrencies, 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_amountdiscount on them is removed at their next recalculation. Saving a list that holds the new environment currency answers400 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}— setcustomerEmail/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.
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.