Currency and FX

Which currency a sale may be in, how a secondary currency is checked, and the dated rate your statement converts at.

The short version#

A sale must be in a currency the SKU is priced in for the country you declare, or in one the Content Owner has explicitly authored for that SKU. Your agreement's Commercial Schedule then narrows that further: it lists the currencies you may sell in, and a currency outside that list is outside the grant even when the SKU is priced in it.

Your statement is denominated in your agreement's payment currency, not in the currency of each sale. Conversion happens once, at a dated reference rate, and the statement names the rate, its source and its fixing time for every currency it converted.

Which currency you may declare#

Send integrationOrderContext.currencyCode on every order. These checks run against it, in this order, and each returns a different error because each has a different fix.

CheckError when it failsWhat to do
The country you declared is one you have declared you sell intoFOOTPRINT_COUNTRY_NOT_DECLAREDDeclare the country. The error body carries a fixItUrl
The currency is one you have declared you sell inFOOTPRINT_CURRENCY_NOT_DECLAREDDeclare the currency, if you actually settle in it
The Commercial Schedule (or your partner access) permits the currencyCURRENCY_NOT_PERMITTED_BY_TERMAmend the agreement. See "Changing what you may sell" below
The currency is the one the country is priced in, and the Content Owner still allows it thereCURRENCY_NOT_PRICED_FOR_COUNTRYSell in the priced currency

Other checks sit between them: the territory the agreement grants comes right before its currency, and the SKU's territory, its region locks and the catalog price come before the priced currency. When several refuse the same order, every order surface (preview, hold, reserve, commit) names the first in this order. A country with no price at all is refused with CATALOG_PRICE_NOT_SET: there is no priced currency to check the last two against.

CURRENCY_MISMATCH is a different failure and keeps its own meaning: the currency you sent disagrees with the snapshot a checkout hold froze. Re-read the hold, or create a new one.

Call GET /api/seller/v1/whoami to see all three boundaries before you hit one. data.footprint is what you have declared, data.permittedCurrenciesByPublisher is what each Content Owner's Commercial Schedule permits, and data.geoPolicyByPublisher is their geo-mismatch policy together with any per-SKU tightening. That last one has no other route to you: a Content Owner sets it alone, because it can only ever refuse.

One currency per country#

A SKU has one currency per country: the one its price list resolves to for that country. A sale into that country is always in that currency and is checked against that price directly. Declaring any other currency is refused with CURRENCY_NOT_PRICED_FOR_COUNTRY (or CURRENCY_NOT_PERMITTED_BY_TERM when the agreement permits only each country's own currency), and the error names the currency the country is priced in.

Ordinary sales involve no exchange rate at all. Your monthly reports convert to your payment currency once, at a dated fixing.

The Content Owner decides which currencies it prices countries in. If it stops pricing a country in a currency, sales in that country stop until it is priced again; POST /orders/preview and GET /availability say so first.

Until 2026-10-09 a Content Owner could also permit a second currency on a SKU, settled at a reference-rate floor. That path is gone: SRP_MISMATCH_FOR_CURRENCY is deprecated and no longer returned, and the all_catalog_currencies mode permits exactly what primary_only permits.

Named currency lists#

A Commercial Schedule may state its permitted currencies as a named list instead of a rule. Where it does, whoami reports currencyMode: "custom" and a currencyDetail object beside it:

JSON
{
  "currencyMode": "custom",
  "currencyDetail": { "EUR": ["PL", "CZ"], "USD": "territory" }
}

Read it as: euros in Poland and Czechia only, dollars anywhere in the granted territory. A currency the list does not name is refused with CURRENCY_NOT_PERMITTED_BY_TERM however the SKU is priced, including a country's own currency. A currency it names in other countries than yours is refused with the same code and details.reason: "currency_not_permitted_for_country", and the body carries the countries that would have been accepted.

Everything else still applies underneath. The currency must be the one the country is priced in, and the country must be in your declared footprint. A named list narrows; it never widens.

The reference rate#

Rates are dated daily fixings, not live quotes. The source is the European Central Bank, or, where the ECB publishes no rate for a currency, the licensed reference provider recorded on the Platform and named with its fixing time on each statement. That sentence is in your agreement, in the FX Convention definition. In the API, that statement of the rate is the fx block of each monthly report, described below.

Two conventions exist, and which one applies to you is stated in your Commercial Schedule:

  • Period end converts at the last fixing on or before the end of the reporting period.
  • Period average converts at the mean of the business day fixings across the period.

Where no direct pair is published, the rate is derived through the euro at eight decimals. Rounding to the currency's minor unit happens once, at the end.

Where to read the rate that was used. Each monthly report freezes its rates when it is built. GET /api/seller/v1/finance/reports/{reportId} returns them under fx, one entry per sale currency: the rate into the report currency, its source, the fixing date (asOf), the fixingTime and the convention. A sale currency equal to the report currency has identity: true and was not converted. Each line of GET /finance/reports/{reportId}/lines carries the exchangeRate it was converted at, so you can recompute any share.

The rate on the report is not the rate you saw at preview. POST /orders/preview returns an indicative block so you can show a customer an approximate figure; it is labelled indicative because the binding rate is the period's fixing, which does not exist yet when you preview. Do not reconcile against it.

Sales channels#

Your Commercial Schedule lists the channels you may sell through, and integrationOrderContext.salesChannel declares which one each order came through. Accepted values are web, mobile_app, partner_embed, and marketplace:<slug>.

Under the default own_storefront term, the first three are permitted and any marketplace:<slug> is refused with SALES_CHANNEL_NOT_PERMITTED. Omitting the field entirely gives SALES_CHANNEL_REQUIRED.

A Schedule may instead admit named marketplaces. Where it does, whoami reports permittedChannels: "own_storefront_plus_named_marketplaces" and a marketplaceSlugs array beside it. Declare one of those as marketplace:<slug>, spelled exactly as the array spells it. Your own three channels stay permitted, and any marketplace the agreement does not name is still refused. Naming a marketplace does not change who the seller of record is: you remain responsible for a sale made there as if it were made on your own storefront.

This follows the Key Delivery article: the grant is to sell to an end user through your own storefront. Reselling, sub-distributing, or listing a Key on a third-party marketplace is outside it, and an operator of a marketplace may hold the agreement only in respect of its own first-party storefront.

Changing what you may sell#

Currencies, channels and territories are contract terms, frozen into the agreement when it is activated. Narrowing or widening one on a live contract is a countersigned amendment through the normal amendment flow. There is no settings screen that changes them, deliberately: a value that decides what a sale settles at should not be editable by one party alone.

Your footprint, the countries and currencies you sell in, is different. It is your own operational fact, you edit it yourself, and it can only narrow what a contract already grants. It never widens one.

Reading and writing your footprint#

GET /api/seller/v1/me/footprint returns the countries and currencies you have declared. PUT replaces them.

It is a replace, not a merge: send the complete set both times. On contract date 2026-12-01 and later the PUT answers with the footprint as stored, duplicates removed and sorted, which is what the next GET returns, and a code that names no country (ZZ) or no current ISO 4217 currency (XXQ) is refused with 422 VALIDATION_FAILED naming its position (countries.1). Earlier contract dates echo the lists you sent and store any two- or three-letter code. A merge would leave you unable to say "I no longer sell here", and would make a retry mean something different from the first call. Both lists must name at least one entry: an empty footprint would refuse every order, so the API refuses to store one, as the console always has.

JSON
{ "countries": ["NL", "DE", "BE"], "currencies": ["EUR"] }

Both halves are checked on every order, and they are checked first, because they are the only boundaries you can fix without talking to a Content Owner. A country you have not declared is refused with FOOTPRINT_COUNTRY_NOT_DECLARED, and a sale currency you have not declared with FOOTPRINT_CURRENCY_NOT_DECLARED. Declaring a currency does not price it: the Schedule still has to permit it and the title still has to carry a price for the country, so your declaration is the first of three checks rather than the only one.

Changing the footprint (PUT /me/footprint) needs seller:account:manage, which is opt-in at key creation and, like seller:keys:export, is not held by legacy keys. Your footprint decides what your sales settle against, so a key issued before scoping existed does not silently gain the ability to change it. Reading it (GET /me/footprint) works with any Seller API key.

GET /whoami reports the same footprint under data.footprint.

See also#

What links here

Published guides that link to this page.

Search docs

Search documentation…