> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Cross-currency buying

> How a buyer can transact in a currency a storefront does not settle in — the marketplace converts each source cost at the platform spot rate while the source is still paid in its own currency.

A storefront settles in its own currencies — its `paymentCurrencies` (the payout
set). A buyer whose currency is one of these pays exactly what the seller is paid
in: no FX.

When a buyer's currency is **not** one a storefront settles in, the **marketplace**
can still admit the buy via **cross-currency FX**: it converts each source cost to
the buyer's currency at the platform spot rate and quotes the buyer in their own
currency. The source keeps quoting and being paid in its own currency — nothing
about the source changes. Scope3 sits on the storefront's curation edge and holds
the cross-currency relationship between buyer and source.

## Two decisions, two owners

Currency support is split between the operator and the marketplace:

* **The operator decides which currencies its storefront settles in** —
  `paymentCurrencies`. These are the operator's money and the operator's call;
  there is no FX on them.
* **The marketplace decides which directed buyer→settlement pairs it accepts via
  FX.** A buyer currency is admitted only when the exact pair to the seller's
  settlement currency is supported.

FX remains automatic where a pair exists, but support is not a global cross-product.
For example, IDR→USD may be supported while IDR→GBP and USD→IDR are not. An FX
pair also does not make its buyer currency a supported seller settlement currency.

The storefront must first confirm a supported settlement currency. Interchange
never assumes USD when that currency is missing: the storefront is blocked and
rejects new media buys until its seller sets a supported currency. Its independent
pause override is unchanged. Official sales-adapter storefronts settle through
the connected platform instead and do not use this Interchange settlement gate.

## When it applies

A buyer is locked to one currency (say ZAR) and wants to buy from a source that
prices and settles only in another (say USD). Because the marketplace supports
ZAR→USD, the storefront admits the buy, converts each USD source cost to ZAR at the
platform spot rate, and quotes the buyer in ZAR. The source is still paid in USD.

A buyer whose currency is neither settled by the storefront nor supported by an
exact pair to its settlement currency is not admitted — discovery returns no products (a normal
"nothing for me here" outcome, not an error), and a media buy in that currency is
rejected.

## How it works

<Steps>
  <Step title="Discovery admits the buyer's currency">
    A buyer whose currency the storefront settles, or whose exact directed FX pair
    the marketplace supports, is surfaced products in their own currency.
  </Step>

  <Step title="Quotes are converted at the rate-of-the-day">
    Each source cost (in the storefront's settlement currency) is converted to the
    buyer's currency at the **rate-of-the-day** before the buyer is quoted — one
    rate per pair per UTC day, fixed at first use.
  </Step>

  <Step title="The quote holds for the day, then re-prices">
    An FX-converted product carries a hard **`expires_at`** (the next UTC
    midnight). Within that window the rate the buyer was quoted is the rate the buy
    books — quote and `create_media_buy` resolve the *same* rate-of-the-day, so
    "quoted ZAR 52 → booked ZAR 52" holds. After it expires, re-discover to be
    re-quoted at the new day's rate. Re-executing from that fresh quote creates a
    new media buy; it never re-prices the earlier booked buy.
  </Step>

  <Step title="The booked rate is locked for the campaign">
    When a media buy is created, the rate in effect is snapshotted onto that buy,
    so it bills the source and settles the campaign at the rate committed at
    booking — every package, inventory source, update, delivery report, and payout
    for that media buy uses the same rate. A retry cannot replace it with a later
    rate; a later rate move never changes a booked buy.
  </Step>
</Steps>

## Rates

The conversion is keyed by a currency pair written `BASEQUOTE` (e.g. `USDZAR`):

* **BASE** is the settlement currency the source is paid in (the storefront's
  `defaultCurrency`).
* **QUOTE** is the buyer currency.
* The **rate** is QUOTE units per 1 BASE unit — the standard market quote
  (`USDZAR` = ZAR per USD). The buyer price in QUOTE = source cost in BASE × rate.

Rates come from a **platform spot feed** (ECB-backed reference rates). The
marketplace fixes a **rate-of-the-day** per pair (the first value seen each UTC
day is locked and not moved intraday), so a buyer quoted at discovery books at
that same rate as long as they transact within the day — that hold is the
window the FX-converted product's `expires_at` expresses. The day's rate is the
same for every buyer (not a per-buyer rate). A buy **locks the rate when it is
created** (`create_media_buy`): that snapshot bills the source and settles the
campaign for its whole life, so a later rate move never changes a booked buy. The
pilot uses spot rates and takes no hedge over the booking-to-settlement gap; a
longer hold means re-pricing (re-discovering) at the prevailing day's rate.

If the rate feed is temporarily unavailable when a new day's rate would be
fixed, the marketplace carries the **most recent locked rate forward** (up to 7
days old) as that day's rate-of-the-day rather than blocking buys, and pages its
operations team to restore the feed. Beyond that window the pair is treated as
unpriceable: cross-currency requests for it fail with `FX_RATE_UNAVAILABLE`
(retry later, or re-discover once rates are flowing) rather than pricing at a
stale rate.

## What the source sees

Nothing changes for the source. It advertises one currency, is paid in that
currency, and never sees the buyer's currency. The cross-currency relationship is
entirely a property of the storefront's curation edge between the buyer and the
source.

## Where it applies

FX applies to both **composed** products and **wholesale / passthrough** products,
including live, account-specific products returned for a buyer's brief. In every
case, the source's price is converted to the buyer's currency for the quote and
the source is still paid in its own currency. Conversion happens **once, at the
buyer's edge** (the first storefront the buyer transacts with). In a curation
chain, internal storefront-to-storefront hops carry the settlement currency
through and never re-convert, so a buy is never FX'd twice.

## Multiple currencies in one campaign

A campaign is not restricted to a single currency. A buyer can select products
that settle in different currencies — across storefronts, and within a single
storefront that sells in more than one currency — all in the same campaign. The
buyer always transacts and is billed in their own primary currency; the
marketplace converts each product's cost at the rate-of-the-day described above.

Products are split into **one media buy per (storefront, settlement currency)**.
For example, a buyer in ZAR who selects USD and GBP products from storefront A and
USD products from storefront B gets three media buys — (A, USD), (A, GBP) and
(B, USD). Each media buy is denominated in the buyer's primary currency and carries
its own settlement currency and its own locked FX rate.

<Note>
  Cross-currency FX applies on currency-discovery, `create_media_buy`, and
  `update_media_buy`, including on manual-approval storefronts. Updating a buy
  re-applies its locked life rate — re-budgeting never re-quotes; **changing a
  buy's currency is not supported**, a buy's currency is fixed for its whole life.
  On a manual-approval storefront the rate quoted at submission is held for a
  limited window and re-applied when the buy is approved.
</Note>