Money

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.

  • PATCH an application or store currency to change the main currency. After the store's first production sale it answers 409 currency_locked and the response shows currencyLocked: true. A code that cannot be a main currency is 422 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_error with the reason in details[], and an application main currency answers 422 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.
Production
Until multi-currency opens in production, a production environment accepts USD only. Adding a code to a production 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 cartCurrencies with PUT /api/v1/embed-config is refused with 422 currency_not_payable when no connected service accepts it (details is an array of { currency, payableCurrencies }, several codes joined in one message). When coverage cannot be read the answer is 503 currency_coverage_unavailable and 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_payable with details as { 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 keeps 402 connect_processor.
  • Freshness. Payment paths use a coverage read cached for 60 seconds. The coverage route and the enable gate always read fresh.
currency_not_payable
# 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.

Request
curl https://api.usethrottle.dev/api/v1/connectors/currency-coverage \
  -H "X-API-Key: sk_test_xxx"
Response
{
  "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"
  }
}
Production
The production rule is unchanged: non-USD stays closed in production until the production gate opens. Coverage is read the same way in every environment.

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 currency means the store's main currency.
  • A given currency is matched case-insensitively and stored upper case (eur becomes EUR). It must be enabled, else 422 currency_not_enabled with details.enabledCurrencies.
  • An unknown code (XXX, ABC) is 422 currency_not_supported.
Create a cart
# 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" }'
currency_not_enabled
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"] }
  }
}
Behaviour change
An integration that omitted 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.

SurfaceFieldNo entry for the order currency
Discountsamounts422 discount_currency_unsupported. See Discounts.
Shipping methodscurrencyAmountsThe method is not offered. Selecting it is 422 shipping_method_unavailable.
Carrier markupmarkup.amountsA flat markup with no entry for the cart currency drops that carrier rate, the main currency included.
Net 30 capsmaxOrderTotalsOnce 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 conditionsamountsThe rule does not match an order in that currency.

Shipping

Shipping amounts
# 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 currencyAmounts entry takes baseRate (required), handlingFee (default 0), and the optional subtotalMin and subtotalMax thresholds, all in that currency's minor units. The main-currency entry is required; a bare number is refused with 400.
  • The shipping configuration's currency must equal the main currency; anything else is 422 currency_mismatch.
  • A calculation with a cartId must send currency, else 400 calculation_currency_required.
  • Selecting a shipping method, or saving an external snapshot, in a currency other than the cart's is 422 shipping_currency_unsupported on 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 connection
# 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

Routing amount condition
# 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/orders follows the create rule above. A payment ( POST /orders/{id}/payments and /payments/record) is always in the order's currency: omit currency, or send the same one, or get 422 currency_mismatch. So is a subscription created with orderId (POST /api/v1/subscriptions).
  • POST /api/v1/me/payment-methods/embed-token takes an optional currency for the verification hold. Omitted, the hold is in the main currency, or the first enabled currency a connector can take. A currency refusal comes before 402 connect_processor.
  • POST /api/v1/checkout-sessions/embed-token no longer requires currency; amount is 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).

CurrencyMinor unit digits1 major unit
USD, EUR, GBP2100
JPY, KRW01
KWD, BHD31000

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.

Install
npm install @usethrottle/money
ExportDoes
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.
Examples
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.

en-US formatting on every surface
Amounts always use , 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 }.

SurfaceStyle
Buyer pages, emails, PDFs, dialogs, toasts, refusals, detail pagesformatMoney(amount, currency)
Dashboard lists and tablesThe amount as above, with the currency code muted beside it.
Amount inputsThe 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 feedstoDecimalString(amount, currency)
Typed text from a buyer or merchantparseMoney(text, currency)
Old helpers
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.

RouteLegacy money (main currency only)New fields
GET /api/v1/analytics/orders-timeseriestotalGrossCents, series[].grossCents, comparison.totalGrossCentscurrency (now the main currency); byCurrency of { currency, amount, display, paidOrders }; series[].byCurrency (zero-filled); comparison.byCurrency
GET /api/v1/analytics/business-summaryorders.current/previous gross, average order, refunds and net; orders.deltaPct; subscriptions.mrr current, period start and delta; receivables.outstandingCents; quotes.<status>.totalCentscurrency; 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-digestdisputes.totalCents, overdueInvoices.totalCentscurrency; disputes.byCurrency and overdueInvoices.byCurrency with count
GET /api/v1/analytics/customerstopCustomers[].revenueCents, totals.revenueCentscurrency; topCustomers[].byCurrency with orderCount; totals.byCurrency with orderCount and customerCount
GET /api/v1/analytics/productsrows[].revenueCents, totals.revenueCentscurrency; rows[].byCurrency with units and orderCount; totals.byCurrency with units
GET /api/v1/analytics/revenue-breakdownrows[].grossCents, totals.grossCentscurrency; rows[].byCurrency and totals.byCurrency with orderCount
GET /api/v1/analytics/discountsrows[].discountedRevenueCents, rows[].discountGivenCents and the totalscurrency; rows[].byCurrency and totals.byCurrency of { currency, amount (discounted revenue), display, redemptions, discountGiven }
GET /api/v1/analytics/subscriptionsseries[].mrrDeltaCents, totals.netMrrDeltaCentscurrency; series[].byCurrency (zero-filled); totals.byCurrency
GET /api/v1/invoices/agingbuckets[].total_amount, total_outstanding_amount (keeps its snake-case keys)currency; buckets[].byCurrency and byCurrency with count
GET /api/v1/abandoned-carts/summaryabandonedValuecurrency; 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.

orders-timeseries (excerpt)
{
  "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 }
  ]
}
Counts stay all-currency
Order, customer and cart counts such as 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.

Related guides