Currencies

Returns the store's complete currency set, including the base currency and any added currencies. Each currency includes its conversion rate, rate_source, rounding mode, the rounding modes it can use, enabled state, and timestamps. The base currency keeps its original prices and cannot be rounded, so its rounding_modes is always empty. conversion_rate is the rate prices use right now: in manual mode it is the merchant's stored rate (rate_source: "manual"); in automatic-rate mode it is the live market cross-rate from the current exchange-rate snapshot (rate_source: "automatic"), and when no current snapshot exists it is the stored placeholder with rate_source: "automatic_unavailable"—prices in that currency cannot be charged until rates refresh. Exchange rates always use . as the decimal separator. Use All exchange rates for the live market table. Live rate refreshes do not fire currencies/update; re-read currencies when you need the current automatic rate. The response also shows whether multi-currency is enabled and available on the store's plan, whether rates are automatic, every rounding mode the platform supports, and the store's currency limits. The top-level rounding_modes includes nearest_99, nearest_95 and nearest_50, which zero-decimal currencies such as JPY reject; offer each currency its own rounding_modes instead. Use max_conversion_decimals and max_conversion_rate to validate manual rates. bulk_max caps currency batches, including the bulk data-removal endpoint.

Returns only the enabled currencies with their ids, display fields, conversion rate and rate_source, rounding configuration, timestamps, and the store's multi-currency enabled state. conversion_rate is the rate prices use right now: in manual mode it is the merchant's stored rate (rate_source: "manual"); in automatic-rate mode it is the live market cross-rate from the current exchange-rate snapshot (rate_source: "automatic"), and when no current snapshot exists it is the stored placeholder with rate_source: "automatic_unavailable"—prices in that currency cannot be charged until rates refresh. Exchange rates always use . as the decimal separator. Use All exchange rates for the live market table. Live rate refreshes do not fire currencies/update; re-read currencies when you need the current automatic rate. Market assignment still determines which currencies a shopper may use. Use the resolved active market—not this store-wide list alone—to build a shopper-facing currency selector.

Returns the store's base currency. Every price the API returns is in this currency unless a market currency applies. The base is set when the store is created and never changes.

Returns current market rates for supported currencies relative to the store's base currency. Each entry carries base_currency and the rate in both directions as decimal strings: rate is how much base one unit of the currency buys, while rate_inverse is how many units one base unit buys. Both are rounded to six significant digits (at most ten decimal places), so they may not multiply to exactly one. updated_at is an RFC 3339 UTC timestamp for the complete rate snapshot. The request fails when the latest snapshot is unavailable or stale. The store's base currency is not included in rates.

Returns the market rate for a single ISO currency code relative to the store's base, in both directions. updated_at is the complete snapshot's RFC 3339 UTC timestamp. The request fails when the latest snapshot is unavailable or stale. Useful when suggesting a rate while a merchant sets a manual one.

Returns the currency if it belongs to the token's store, with its conversion rate and rate_source, rounding mode, the rounding modes it can use (empty for the base currency), and enabled state. In automatic-rate mode conversion_rate is the live market rate.

Adds a non-base currency. conversion_rate is a positive decimal string expressing how many units of the added currency equal one unit of the store's base currency—for example, "0.0105" means 1 INR = 0.0105 USD. Send it as a JSON string to avoid binary floating-point conversion. Manual rate values allow up to max_conversion_decimals decimal places (currently ten) after insignificant trailing zeros are removed, and a maximum value of max_conversion_rate (currently 999999); read both from List currencies instead of hardcoding those limits. Equivalent formatting such as trailing zeros is not preserved. The call fails when multi-currency is off or unavailable on the plan, automatic rates are on, the store has reached its currency limit, or the code is unknown or already configured. is_base is not accepted.

Updates a non-base currency. Supply at least one field; omitted fields keep their current values, and a request with none is rejected with CURRENCY_BULK_FIELDS_REQUIRED. The base currency is immutable and requests against it are rejected. In automatic-rate mode the rate and enabled state are market-managed: changing either is rejected, while a rounding-only change is accepted and values equal to the current ones are not changes. The rounding mode must be one of the currency's own rounding_modes; a zero-decimal currency rejects nearest_99, nearest_95 and nearest_50 with CURRENCY_ROUNDING_MODE_UNAVAILABLE. Disabling a currency is rejected while a market still uses it. It is also rejected with CURRENCY_DISABLE_GIFT_CARD_BALANCES while active or scheduled, unexpired Gift Cards still hold a balance in it; details carries code, active_gift_cards and outstanding_balance. A request that changes nothing returns the currency without code or message and records no audit entry or webhook.

Deletes the currency in manual-rate mode. Removal is blocked while any live mutable reference remains, and while an active Gift Card still holds a balance in this currency. The error (CURRENCY_IN_USE, or CURRENCY_GIFT_CARDS_IN_USE when Gift Card balances are the only blocker) returns six summary groups (gift_cards among them), the exact count for each of the 17 reference types, and active_gift_cards. Use Remove Currency Data to clear the mutable references first; it never touches Gift Card balances, which must be spent, cancelled or expire. Historical carts, orders, payments, spent or closed gift cards, ledgers, invoices, and settlements are retained and do not block removal.

Send a non-empty list of unique currency UUIDs in ids, capped by bulk_max from List currencies. Every ID must belong to this store. The base currency and automatic exchange-rate mode are rejected. The entire selection is checked together: a market must retain at least one currency after removal. First call without confirmation. CONFIRMATION_REQUIRED returns details.preview with total and per-currency removed/counts, warnings, and a five-minute single-use confirmation token. Repeat the same IDs with confirmed: true and confirmation_token. The token is bound to the store, actor, sorted selection and all previewed counts. Changed counts, selection, expiry or replay require a fresh preview. All 17 reference types are cleared for the whole batch at once: either every currency in the batch is cleaned up or nothing changes. No currency configuration records or historical carts, orders, payments or financial records are deleted. An all-empty unconfirmed batch returns zero counts without mutation events. Successful cleanup records per-currency and batch audit entries, queues one currencies/update with changed currency IDs/codes and one currencies/data_removed per currency whose data changed. Storefront product filters are refreshed once for the whole batch. Any failure rolls back the entire batch.

This is a two-step destructive operation. Call it first without confirmation; if references exist, the API returns CONFIRMATION_REQUIRED with exact warnings and a short-lived, single-use token bound to those counts. Repeat with confirmed: true and that token. If the counts changed, review a fresh preview. The confirmed request checks again that every market keeps another currency, then clears all 17 reference types at once: either everything is cleared or nothing changes. The response reports the counts actually removed, and currencies/update and currencies/data_removed are sent only when the cleanup is saved. Counts cover directly addressed reference rows; dependent feed jobs, diagnostics, and artifacts cascade with their feed unit and are not added to the total. It does not delete the currency. Historical commerce and financial records are never changed.

Applies the selected rounding rule to converted prices in this currency; storefront prices, the checkout preview and the created order all use it. It is accepted in automatic-rate mode: rates are automatic, rounding is not. The mode must be one of the currency's own rounding_modes; a zero-decimal currency rejects nearest_99, nearest_95 and nearest_50 with CURRENCY_ROUNDING_MODE_UNAVAILABLE. The base currency keeps its original prices and does not use a rounding rule, so requests against it are rejected. Setting the current mode returns the currency without code or message and records nothing.

Enables or disables multi-currency for the store. Enabling requires the store's plan to include multi-currency. Disabling requires every additional currency to be removed first. A change returns CURRENCY_UPDATED and queues currencies/update; requesting the current value returns data.success without code or message and records nothing.

Switches exchange rates between market-managed automatic rates and merchant-managed manual rates. Turning automatic rates on requires the store to have no additional currencies. In automatic mode, selecting additional currencies is a Store Admin workflow, and currency reads report the live market rate with rate_source: "automatic". Each market-rate refresh that changes those rates fires currencies/rates_updated. Turning automatic rates off writes the current market rate onto every additional currency, enabled or disabled, in the same transaction; those values then become the store's manual rates. It fails with CURRENCY_EXCHANGE_RATE_UNAVAILABLE (503) and changes nothing when a current rate is missing for any additional currency. The response echoes use_auto_exchange_rates. A change returns CURRENCY_UPDATED and queues currencies/update; requesting the current value returns without code or message and records nothing.