Multi-currency
A store has one main currency and may enable more. Every record is created in one currency, and every amount that depends on a currency (a discount, a shipping rate, a Net 30 cap, a routing threshold) is stored per currency. Throttle never converts an amount for you.
Enabled currencies
The main currency belongs to the application and is shared by its sandbox and
production environments. The extra currencies are cartCurrencies, set per environment in the dashboard (a searchable
multi-select under Cart pricing → Extra cart currencies) or with PUT /api/v1/embed-config. An application reports both as enabledCurrencies, with the main currency first.
-
PATCHan application or storecurrencyto change the main currency. After the store's first production sale it answers409 currency_lockedand the response showscurrencyLocked: true. A code that cannot be a main currency is422 currency_not_supported. -
A currency can be enabled when it is an ISO 4217 currency with 0, 2 or 3 decimal places, is not a
fund or test code, and its decimal places are confirmed by payment processors. Four-decimal
currencies and codes whose processor handling is unconfirmed (HUF, TWD, ISK, UGX, COP and IDR among
them) are refused: the embed-config PUT answers
400 validation_errorwith the reason indetails[], and an application main currency answers422 currency_not_supported. - Disabling a currency stops new carts, quotes and subscriptions in it. Existing records keep working in their own currency: sent quotes, renewals, invoices and refunds.
cartCurrencies, or creating a record in a non-USD
currency there, answers 422 currency_not_available_in_production. An
unchanged or shorter cartCurrencies list is still accepted, and sandbox
is not restricted.
Payment coverage
A currency is payable when at least one active payment service on your connection accepts it. A service with an empty accepted-currency list inherits the list of its definition. Invoice Terms (Net 30) never makes a currency payable.
- The enable rule. Adding a code to
cartCurrencieswithPUT /api/v1/embed-configis refused with422 currency_not_payablewhen no connected service accepts it (detailsis an array of{ currency, payableCurrencies }, several codes joined in one message). When coverage cannot be read the answer is503 currency_coverage_unavailableand nothing changes. - Not payable. A currency that is already enabled stays enabled when it stops being
covered, and the dashboard shows it as "Not payable" (in Cart pricing and in the New order
picker). In the Cart pricing multi-select, a currency that is not payable ("no payment provider
accepts it") can't be added, and removing a currency asks for confirmation. Carts, quotes and orders can still be built in it. Only starting a payment is refused:
422 currency_not_payablewithdetailsas{ currency, payableCurrencies }. This applies to cart finalize and checkout, cart-session checkout, order authorize, order and payment-link payments, quote accept and quote-link checkout, and the embed tokens and card sessions. If the coverage lookup fails on a payment path, the payment proceeds; only the enable gate fails closed. - No connection. With no payment connection, the coverage route answers 200 with
connection: "missing", and the embed token keeps402 connect_processor. - Freshness. Payment paths use a coverage read cached for 60 seconds. The coverage route and the enable gate always read fresh.
# Starting a payment in a currency no connected service accepts
HTTP/1.1 422
{
"error": {
"code": "currency_not_payable",
"message": "AUD can't be paid right now: no connected payment service accepts it.",
"details": { "currency": "AUD", "payableCurrencies": ["CHF", "USD"] }
}
}
# Enabling such a currency (PUT /api/v1/embed-config): details is an array,
# and several refused codes share one message.
HTTP/1.1 422
{
"error": {
"code": "currency_not_payable",
"message": "No connected payment service accepts CHF. Add or edit a connector first.",
"details": [{ "currency": "CHF", "payableCurrencies": ["USD"] }]
}
}
# Payment coverage could not be read while enabling a currency
HTTP/1.1 503
{
"error": {
"code": "currency_coverage_unavailable",
"message": "Couldn't check payment coverage. Try again."
}
} Reading coverage
GET /api/v1/connectors/currency-coverage needs connectors:read for an API key, or the application:settings permission in the dashboard. It returns one row per
enabled currency plus every currency an active service accepts: the main currency first, then the other
enabled codes ascending, then the covered-but-not-enabled ones. usage
(open carts and active subscriptions) appears only on enabled currencies, and only when the key holds both carts:read and subscriptions:read. valuation is ecb, fallback or none: how Throttle values a
payment in that currency for its own billing. unknownServices lists services
Throttle could not match to a definition. The MCP tool get_currency_coverage
returns the same data.
curl https://api.usethrottle.dev/api/v1/connectors/currency-coverage \
-H "X-API-Key: sk_test_xxx" {
"data": {
"mainCurrency": "USD",
"connection": "active",
"currencies": [
{
"currency": "USD", "main": true, "enabled": true, "payable": true,
"services": [
{ "id": "stripe-usd", "displayName": "Stripe", "method": "card", "active": true, "inherited": true }
],
"valuation": "ecb",
"usage": { "openCarts": 4, "activeSubscriptions": 2 }
},
{
"currency": "AUD", "main": false, "enabled": true, "payable": false,
"services": [],
"valuation": "ecb",
"usage": { "openCarts": 1, "activeSubscriptions": 0 }
},
{
"currency": "CHF", "main": false, "enabled": false, "payable": true,
"services": [
{ "id": "adyen-eu", "displayName": "Adyen", "method": "card", "active": true, "inherited": false }
],
"valuation": "ecb"
}
],
"services": [
{ "id": "stripe-usd", "displayName": "Stripe", "method": "card", "active": true, "inherited": true },
{ "id": "adyen-eu", "displayName": "Adyen", "method": "card", "active": true, "inherited": false }
],
"unknownServices": [],
"readAt": "2026-11-08T12:00:00.000Z"
}
}
Both embed-token responses (POST /api/v1/checkout-sessions/embed-token and GET /api/v1/checkout-sessions/{id}/embed-token) carry originCountry, a nullable string: the buyer address country, else the store
origin country, else US.
One rule for every create path
Carts, cart sessions, quotes, orders, subscriptions, the checkout embed token, the add-card embed token and imports all follow the same rule:
- A missing
currencymeans the store's main currency. -
A given currency is matched case-insensitively and stored upper case (
eurbecomesEUR). It must be enabled, else422 currency_not_enabledwithdetails.enabledCurrencies. - An unknown code (
XXX,ABC) is422 currency_not_supported.
# No currency: the store's main currency (here EUR).
curl -X POST https://api.usethrottle.dev/api/v1/carts \
-H "X-API-Key: sk_test_xxx" -H "Content-Type: application/json" \
-d '{ "applicationId": "e7efb0a6-892e-46b2-97ab-296bb04c5b29" }'
# A currency the store has not enabled.
curl -X POST https://api.usethrottle.dev/api/v1/carts \
-H "X-API-Key: sk_test_xxx" -H "Content-Type: application/json" \
-d '{ "applicationId": "e7efb0a6-892e-46b2-97ab-296bb04c5b29", "currency": "CHF" }' HTTP/1.1 422
{
"error": {
"code": "currency_not_enabled",
"message": "CHF is not enabled for this store. Enabled: EUR, USD.",
"details": { "currency": "CHF", "enabledCurrencies": ["EUR", "USD"] }
}
} currency used to get USD on orders, payments,
subscriptions and quotes. It now gets the store's main currency. A USD-main store sees no
difference. The old 422 currency_mismatch on an unresolved cart is
replaced by the codes above.
Amounts are per currency
Throttle does not convert prices, so a currency with no entry is not offered. The
legacy single-value field (value, a method's rate, a flat markup's amount, maxOrderTotal) mirrors the main-currency entry.
| Surface | Field | No entry for the order currency |
|---|---|---|
| Discounts | amounts | 422 discount_currency_unsupported. See Discounts. |
| Shipping methods | currencyAmounts | The method is not offered. Selecting it is 422 shipping_method_unavailable. |
| Carrier markup | markup.amounts | A flat markup with no entry for the cart currency drops that carrier rate, the main currency included. |
| Net 30 caps | maxOrderTotals | Once any cap is set, a currency with no entry is not offered for Net 30. With no caps at all, Net 30 is uncapped in every currency. |
| Routing amount conditions | amounts | The rule does not match an order in that currency. |
Shipping
# A shipping method with an entry per currency (minor units).
{
"currencyAmounts": {
"USD": { "baseRate": 500, "handlingFee": 0 },
"EUR": { "baseRate": 450, "handlingFee": 0, "subtotalMin": 4500 }
}
}
# A carrier markup with one amount per currency.
{ "markup": { "type": "flat", "amounts": { "USD": 200, "EUR": 180 } } } -
Each
currencyAmountsentry takesbaseRate(required),handlingFee(default 0), and the optionalsubtotalMinandsubtotalMaxthresholds, all in that currency's minor units. The main-currency entry is required; a bare number is refused with400. -
The shipping configuration's
currencymust equal the main currency; anything else is422 currency_mismatch. -
A calculation with a
cartIdmust sendcurrency, else400 calculation_currency_required. -
Selecting a shipping method, or saving an external snapshot, in a currency other than the cart's is
422 shipping_currency_unsupportedon every cart. - A legacy write of a single rate sets the main-currency entry and keeps the other entries; when a write sends both the single value and the map, they must agree on the main currency.
Net 30 and payment methods
# Net 30 credit cap per currency. maxOrderTotal mirrors the main entry.
{
"invoicePrefix": "NET",
"defaultNetDays": 30,
"enabled": true,
"maxOrderTotals": { "USD": 500000, "EUR": 450000 }
} GET /api/v1/payment-methods takes an optional currency query: Net 30 is offered or hidden using the cap for that currency,
or the main currency when absent. Sending both maxOrderTotal and maxOrderTotals that disagree is 400.
Routing
# A routing amount condition with one bound per currency, in MAJOR units:
# above 100.00 USD or 90.00 EUR.
{
"type": "amount",
"op": "gt",
"amounts": {
"USD": { "min": 100 },
"EUR": { "min": 90 }
}
}
Routing thresholds are in major units (100 is 100.00), unlike
every other amount in the API. op is gt (uses min), lt (uses max)
or between (both).
An amount condition needs a main-currency entry when the rule's currency condition admits the main currency (422 routing_amount_main_currency_required).
When amounts and the mirrored currency/ min/max are both sent, amounts wins.
The other 422 codes are routing_too_many_rules and routing_amount_currency_excluded. Rule messages start with "Rule N:" ("Decline rule N:" in
the decline flows).
Orders, payments and saved cards
-
POST /api/v1/ordersfollows the create rule above. A payment (POST /orders/{id}/paymentsand/payments/record) is always in the order's currency: omitcurrency, or send the same one, or get422 currency_mismatch. So is a subscription created withorderId(POST /api/v1/subscriptions). -
POST /api/v1/me/payment-methods/embed-tokentakes an optionalcurrencyfor the verification hold. Omitted, the hold is in the main currency, or the first enabled currency a connector can take. A currency refusal comes before402 connect_processor. -
POST /api/v1/checkout-sessions/embed-tokenno longer requirescurrency;amountis still required.
Quotes
Changing a draft quote's currency flags every typed amount for review, and POST /api/v1/quotes/{id}/issue answers 422 quote_amounts_need_review until each is confirmed. See Quotes.
Minor units
Every amount in the API is an integer in the currency's minor unit. The number of decimals comes from
ISO 4217, not from an assumption of 100. Routing thresholds are the one exception: their min/max are in major units (see Routing).
| Currency | Minor unit digits | 1 major unit |
|---|---|---|
| USD, EUR, GBP | 2 | 100 |
| JPY, KRW | 0 | 1 |
| KWD, BHD | 3 | 1000 |
Any currency that can be enabled works in its own minor units: 1999 is
¥1,999 in JPY and 1.999 in KWD. Checkout, tax, shipping and routing amounts use that exponent, and
imports refuse a cell with more decimals than the currency has (JPY 1999.00)
or an ambiguous one (KWD 1,999). The codes that stay refused are listed
under "Enable-able currencies" in the README of @usethrottle/money.
The money package
@usethrottle/money formats, parses and looks up minor units for every currency.
It has no dependencies and never calls Intl, so the same input prints the same
bytes in Node, browsers and Workers.
npm install @usethrottle/money | Export | Does |
|---|---|
formatMoney(minor, code, { display? }) | Formats minor units. display is symbol (default) or symbol-code. |
currencySymbol(code) | The symbol, such as € or CA$. |
toDecimalString(minor, code) | A plain decimal string: 19.99, 1999 for JPY, 1.999 for KWD. |
moneyValue(amount, currency) | An object with amount, currency and display. |
parseMoney(text, code) | Typed text to minor units, or null. |
toMinor(decimal, code) | A decimal string or number to minor units, or null. |
minorUnitsOf(code) | The ISO 4217 digit count. Throws for an unknown code. |
isKnownCurrency(code) | True when the code is in the ISO 4217 table. |
isEnableableCurrency(code) | True when a store may enable the currency. |
import { formatMoney, parseMoney, toDecimalString } from '@usethrottle/money';
// U+00A0 is a no-break space.
formatMoney(4763, 'EUR'); // '€47.63'
formatMoney(-4763, 'EUR'); // '-€47.63'
formatMoney(500, 'CAD'); // 'CA$5.00'
formatMoney(500, 'CHF'); // 'CHF<U+00A0>5.00'
formatMoney(1999, 'KWD'); // 'KWD<U+00A0>1.999'
formatMoney(4763, 'EUR', { display: 'symbol-code' }); // '€47.63<U+00A0>EUR'
formatMoney(500, 'CHF', { display: 'symbol-code' }); // 'CHF<U+00A0>5.00' (code not repeated)
formatMoney(1234, 'XYZ'); // '12.34<U+00A0>XYZ' (unknown code)
parseMoney('€44.00', 'EUR'); // 4400
parseMoney('$5', 'EUR'); // null (foreign symbol)
toDecimalString(1999, 'JPY'); // '1999'
The symbol comes first. A symbol that ends in a currency sign ($, €, ₹) is glued to the digits; any other symbol is
followed by a no-break space. symbol-code adds the code after the amount unless the
symbol already is the code. An unknown code prints two decimals and the code; a non-number prints an em dash.
, for grouping and . for decimals.
Buyer-locale formatting is not offered.
Showing money
Show every amount with the currency of the record it belongs to, through formatMoney(amount, record.currency) from @usethrottle/money. Never divide by 100, never write toFixed(2) and never default the currency to USD: JPY has no decimals, KWD has three, and a missing currency means a
missing field on your side, not dollars. Every response and webhook payload that carries an amount carries its currency beside it, and refusals that quote an amount add it as a money value, { amount, currency, display }.
| Surface | Style |
|---|---|
| Buyer pages, emails, PDFs, dialogs, toasts, refusals, detail pages | formatMoney(amount, currency) |
| Dashboard lists and tables | The amount as above, with the currency code muted beside it. |
| Amount inputs | The currency symbol as the leading label, the currency's own decimals, and a "Check this price" hint when the currency changes under a typed value. |
| Analytics and feeds | toDecimalString(amount, currency) |
| Typed text from a buyer or merchant | parseMoney(text, currency) |
formatMoney(minor, currency, locale?) in @usethrottle/quotes and in @usethrottle/auth/components is deprecated: it now ignores the locale and
prints what the money package prints. The other SDK entry points re-export the two-argument formatMoney.
Reports
Reports never add currencies together. Every analytics and summary route returns money per currency in a byCurrency array, and a top-level currency
naming the application's main currency. The legacy single-value money fields keep their names and now
hold the main-currency amount only, so a store with one currency sees the same numbers as
before.
| Route | Legacy money (main currency only) | New fields |
|---|---|---|
GET /api/v1/analytics/orders-timeseries | totalGrossCents, series[].grossCents, comparison.totalGrossCents | currency (now the main currency); byCurrency of { currency, amount, display, paidOrders }; series[].byCurrency (zero-filled); comparison.byCurrency |
GET /api/v1/analytics/business-summary | orders.current/previous gross, average order, refunds and net; orders.deltaPct; subscriptions.mrr current, period start and delta; receivables.outstandingCents; quotes.<status>.totalCents | currency; orders.current/previous.byCurrency of { currency, amount, display, orderCount, avgOrder, refunds?, net? }; orders.deltaByCurrency; subscriptions.mrr.byCurrency with periodStart and deltaPct; receivables.byCurrency and quotes.<status>.byCurrency with count |
GET /api/v1/analytics/attention-digest | disputes.totalCents, overdueInvoices.totalCents | currency; disputes.byCurrency and overdueInvoices.byCurrency with count |
GET /api/v1/analytics/customers | topCustomers[].revenueCents, totals.revenueCents | currency; topCustomers[].byCurrency with orderCount; totals.byCurrency with orderCount and customerCount |
GET /api/v1/analytics/products | rows[].revenueCents, totals.revenueCents | currency; rows[].byCurrency with units and orderCount; totals.byCurrency with units |
GET /api/v1/analytics/revenue-breakdown | rows[].grossCents, totals.grossCents | currency; rows[].byCurrency and totals.byCurrency with orderCount |
GET /api/v1/analytics/discounts | rows[].discountedRevenueCents, rows[].discountGivenCents and the totals | currency; rows[].byCurrency and totals.byCurrency of { currency, amount (discounted revenue), display, redemptions, discountGiven } |
GET /api/v1/analytics/subscriptions | series[].mrrDeltaCents, totals.netMrrDeltaCents | currency; series[].byCurrency (zero-filled); totals.byCurrency |
GET /api/v1/invoices/aging | buckets[].total_amount, total_outstanding_amount (keeps its snake-case keys) | currency; buckets[].byCurrency and byCurrency with count |
GET /api/v1/abandoned-carts/summary | abandonedValue | currency; byCurrency with count |
Order and presence
The main currency comes first, then the other codes in ascending order. In a response array the main entry is
always present, with amount 0 when it has no rows, so the legacy field always equals the first entry. Other
currencies appear only when they have at least one row in that scope. Series points carry an entry for every
currency of the range, zero-filled. Ranked lists (top customers, products, discounts) rank by the main-currency
amount, then by count, and each row carries its own byCurrency. A
percentage change is per currency: deltaPct compares the main currency and deltaByCurrency lists every currency.
Example
A store whose main currency is USD, with one EUR order in the window. Every entry is { currency, amount, display } plus the counts of that object; the
legacy field is the USD entry.
{
"currency": "USD",
"totalGrossCents": 19150,
"totalOrders": 3,
"byCurrency": [
{ "currency": "USD", "amount": 19150, "display": "$191.50", "paidOrders": 2 },
{ "currency": "EUR", "amount": 4000, "display": "€40.00", "paidOrders": 1 }
]
} totalOrders or abandonedCount still count every currency, because a count is not money. Use
the counts inside byCurrency for a per-currency figure. A customer who paid in
two currencies counts once in each entry, so the per-currency customerCount values do not add up to the all-currency one. With dimension=currency on the revenue breakdown, each row carries a single entry
in its own currency and a non-main row has legacy grossCents 0.
The daily operations email and the MCP tools follow the same rule. The email lists one revenue row per currency
for production environments only. MCP money values are { amount, currency, display }, and MCP drops the main-only scalars (deltas,
a fixed discount's value, minimum order, a payment's USD value, a fixed quote deposit): read the
amounts from byCurrency and amounts.
What stays in USD
Throttle's own billing values every captured payment in USD from the ECB reference rate dated before the capture. That valuation is internal: it never changes what your buyer is charged or what your API returns.