Multi-Currency Checkout voor Shopify: Volledige Ontwikkelaarsgids 2026

Als je een Shopify-winkel bouwt — of een app die er één bedient — is multi-currency checkout geen nice-to-have meer. Internationale shoppers verwachten prijzen in hun eigen valuta, van de productpagina tot de uiteindelijke "Nu betalen"-knop. Breekt die ervaring, dan stijgen winkelwagenverlatingen, chargebacks en supporttickets. Deze gids legt uit hoe Shopify's multi-currency systeem echt werkt, waar de native tooling tekortschiet, en hoe je een toegewijde wisselkoers-API zoals Finexly aansluit om de gaten te dichten.

Of je nu een headless storefront, een aangepaste Shopify-app of een Liquid-thema op een volwassen Shopify Plus-winkel bouwt, deze gids behandelt de architectuurkeuzes, API-integraties en randgevallen die een werkend multi-currency checkout onderscheiden van één die stilletjes omzet lekt.

Waarom multi-currency checkout in 2026 telt

Grensoverschrijdende e-commerce vormt inmiddels een flink deel van online retail. Shoppers die op een product in vreemde valuta landen — of erger, in hun valuta maar met slordige koersen — haken onevenredig vaak af. De wrijving is niet alleen psychologisch: kaartbetalingen in vreemde valuta activeren extra bankkosten, onverwachte totalen en zelfs fraudemeldingen.

Conversiestudies laten steeds hetzelfde patroon zien: winkels die prijzen in de lokale valuta tonen, lokale afrondingsconventies respecteren en in die valuta afrekenen, converteren aanmerkelijk beter dan single-currency winkels. De technische inspanning was ooit groot — vandaag komt het neer op een handvol API-calls en een nette refresh-strategie.

Shop currency vs. presentment currency begrijpen

Shopify's multi-currency model draait om twee concepten:

• Shop currency — de basisvaluta van de merchant voor prijzen, rapportage en payouts.
• Presentment currency — de valuta die de shopper daadwerkelijk ziet in de storefront, de cart en het checkout.

Wanneer een klant uit Nederland een winkel met shop currency USD bezoekt, kan het product worden getoond als €92,50 (presentment currency) terwijl Shopify intern de verkoop als $99,00 registreert. Orders, refunds en transacties slaan beide waarden op. In de GraphQL Admin API zie je ze als shopMoney en presentmentMoney op elk money-object.

De klassieke fout is aannemen dat een prijs uit de API altijd in één van beide staat. Dat is niet zo. In recente API-versies gebruiken alle reads van de Refund API standaard presentment currency, en een refund-transactie op een multi-currency order zonder expliciete currency geeft een error. Harde regel: lees altijd de valutacode die bij het money-object hoort.

Shopify's native opties (en waar ze stoppen)

Twee hoofdfuncties:

1. Shopify Payments met automatische conversie. Is je winkel in aanmerking, dan activeer je meerdere presentment currencies en Shopify converteert prijzen met koersen die ongeveer elke 15 minuten verversen. Er wordt een kleine conversion fee (doorgaans 1,5–2%) opgeteld en afronding per valuta wordt afgehandeld.

2. Handmatige koersen via Shopify Markets. Jij definieert de koersen en Shopify past toe:

converted_price = (product_price × conversion_rate) × (1 + conversion_fee)

Deze opties dekken de basis maar schieten tekort in diverse scenario's:

• Headless storefronts. Met Storefront API, Hydrogen of een eigen frontend heb je meer controle nodig — en vaak ook rijkere data (historische koersen, cross-rates, non-payment use cases als leveranciersfacturatie).
• Merchants zonder Shopify Payments. Stripe, PayPal, Adyen of lokale processors krijgen de automatische pipeline niet.
• Custom prijslogica. Marketplaces, B2B met tiered pricing, gelokaliseerde promoties.
• Post-checkout apps. Accounting-sync, fraude-tools, loyaliteit en aggregators moeten multi-currency orders normaliseren op één rapportagevaluta — met betrouwbare historische koersen op het exacte ordertijdstip.

In al deze gevallen heb je naast Shopify een toegewijde wisselkoers-API nodig.

Wanneer een externe wisselkoers-API gebruiken

Vuistregel: als één van de volgende waar is, plug een externe API zoals Finexly aan:

1. Je draait een headless of hybride storefront en wilt programmatisch live-koersen.
2. Je ondersteunt valuta die Shopify Payments in jouw regio niet automatisch converteert.
3. Je bouwt apps die historische orders verwerken en de exacte koers op ordertijdstip nodig hebben.
4. Je wilt prijzen tonen in valuta zonder je te committeren aan afrekenen in die valuta.
5. Je hebt updates sneller dan Shopify's 15 minuten nodig.

Meer context in onze vergleich van currency API's en het artikel over REST vs WebSocket voor FX-data.

Finexly levert real-time en historische wisselkoersen voor 170+ valuta via een schone REST-interface, zonder verborgen conversiekosten in de koersen.

Een multi-currency checkout bouwen met Finexly en Shopify

Minimale architectuur:

1. Detecteer de valuta van de shopper — via geolocatie, browser locale of expliciete selector.
2. Haal de huidige koers op bij Finexly (edge-cached, elke paar minuten ververst).
3. Converteer prijzen met afronding en marge.
4. Bij checkout geef je de presentment currency mee aan Shopify.
5. Bewaar de gebruikte koers als ordermetadata voor reconciliatie.

Stap 1: De huidige koers ophalen bij Finexly

Node.js:

// Fetch live rates from Finexly
async function getRates(base = 'USD') {
  const url = `https://api.finexly.com/v1/latest?base=${base}&apikey=${process.env.FINEXLY_KEY}`;
  const res = await fetch(url);
  if (!res.ok) throw new Error(`Finexly error: ${res.status}`);
  const data = await res.json();
  return data.rates; // { EUR: 0.9234, GBP: 0.7891, JPY: 151.42, ... }
}

Python:

import os, requests

def get_rates(base="USD"):
    url = "https://api.finexly.com/v1/latest"
    params = {"base": base, "apikey": os.environ["FINEXLY_KEY"]}
    r = requests.get(url, params=params, timeout=5)
    r.raise_for_status()
    return r.json()["rates"]

cURL voor een snelle sanity check:

curl "https://api.finexly.com/v1/latest?base=USD&apikey=YOUR_KEY"

In productie wikkel je dit in een cache-laag — Redis, Cloudflare KV of een in-process cache met TTL van 60–300 s. Zie onze gids voor caching en error handling.

Stap 2: Productprijzen converteren

function convertPrice(amountInBase, rate, roundingRule = 0.99) {
  const raw = amountInBase * rate;
  return Math.floor(raw) + roundingRule;
}

const rates = await getRates('USD');
const eurPrice = convertPrice(49.00, rates.EUR, 0.99);
// => e.g., 45.99

Stap 3: Doorgeven aan Shopify checkout in de juiste valuta

Met de Storefront API geef je de presentment currency mee bij het aanmaken van de cart. In de GraphQL Cart API stuurt buyerIdentity.countryCode welke presentment currency wordt toegepast:

mutation CreateCart {
  cartCreate(input: {
    buyerIdentity: { countryCode: NL }
    lines: [{ merchandiseId: "gid://shopify/ProductVariant/123", quantity: 1 }]
  }) {
    cart { id checkoutUrl
      cost { totalAmount { amount currencyCode } }
    }
  }
}

Shopify toont dan prijzen in de juiste presentment currency en checkoutUrl rekent af in die valuta — mits je payment gateway dat ondersteunt.

Bij een klassieke (niet-headless) storefront maak je geen carts via API. Gebruik de Geolocation-app of de URL-parameter ?currency=EUR. Liquid-filters als {{ product.price | money }} respecteren de actieve presentment currency.

Stap 4: De gebruikte koers per order opslaan

await admin.graphql(`
  mutation AddRateMetafield($orderId: ID!, $rate: String!, $ts: String!) {
    orderUpdate(input: {
      id: $orderId
      metafields: [
        { namespace: "fx", key: "rate", value: $rate, type: "single_line_text_field" }
        { namespace: "fx", key: "rate_timestamp", value: $ts, type: "single_line_text_field" }
        { namespace: "fx", key: "source", value: "finexly", type: "single_line_text_field" }
      ]
    }) { order { id } userErrors { field message } }
  }
`, { variables: { orderId, rate: String(rates.EUR), ts: new Date().toISOString() } });

Je toekomstige zelf zal je dankbaar zijn als drie maanden later een accountant vraagt waarom het EUR-totaal op order #10042 niet klopt met USD × huidige koers.

Geconverteerde prijzen tonen: Liquid vs Headless

Liquid (klassieke thema's)

<!-- Respects presentment currency -->
<p class="price">{{ product.price | money }}</p>

<!-- Explicit formatting -->
<p class="price">{{ product.price | money_with_currency }}</p>

Headless (Hydrogen, Next.js, custom)

// app/lib/fx.ts - server-side rate fetcher with caching
export async function getFxRates(base = 'USD') {
  const res = await fetch(
    `https://api.finexly.com/v1/latest?base=${base}&apikey=${process.env.FINEXLY_KEY}`,
    { next: { revalidate: 120 } }
  );
  return res.json();
}

export default async function Product({ params }) {
  const [product, fx] = await Promise.all([
    getProduct(params.handle),
    getFxRates('USD'),
  ]);
  const userCurrency = getUserCurrency();
  const displayPrice = product.priceUsd * fx.rates[userCurrency];
  return <ProductView product={product} price={displayPrice} currency={userCurrency} />;
}

Zie onze Next.js currency converter tutorial.

De moeilijke delen: afronding, kosten, versheid

Afrondingsregels. De Japanse yen heeft geen decimalen. De Zwitserse frank rondt traditioneel af op 0,05. Klanten verwachten prijzen eindigend op ,99 of ,95:

const ROUNDING = {
  JPY: (v) => Math.round(v),
  CHF: (v) => Math.round(v * 20) / 20,
  default: (v) => Math.floor(v) + 0.99,
};
function round(value, currency) {
  return (ROUNDING[currency] || ROUNDING.default)(value);
}

Conversiemarge. Zonder Shopify Payments voeg je een kleine marge (1–3%) toe aan de getoonde koers om de spread van de processor te dekken. Expliciet en per markt configureerbaar.

Koersversheid. Koersen bewegen. Bij centrale-bank­aankondigingen kunnen koersen in minuten 1–2% verschuiven. Finexly ververst elke 60 s; met een 2-minuten edge cache heb je bijna-live pricing. Zie omgaan met valutavolatiliteit.

Multi-currency orders volgen en reconciliëren

Drie aanpakken:

1. Koers op ordertijd — trouwst aan de economische realiteit.
2. Koers op payout-tijd — sluit aan op wat op je bank komt.
3. Gemiddelde maandkoers — rustiger voor boekhouding; via Finexly's historical endpoint.

curl "https://api.finexly.com/v1/historical/2026-03-15?base=USD&apikey=YOUR_KEY"

curl "https://api.finexly.com/v1/timeseries?start=2026-03-01&end=2026-03-31&base=USD&symbols=EUR&apikey=YOUR_KEY"

Finance-teams verkiezen meestal #1 voor revenue recognition en #2 voor cash-reconciliatie. Bewaar beide.

Veelvoorkomende valkuilen

• Koersen eeuwig cachen. 24 uur is te lang. TTL 5–10 minuten met circuit breaker.
• De client vertrouwen. Nooit eindprijzen alleen in JavaScript berekenen — server- of Shopify Function-side revalideren.
• Alleen het totaal afronden. Rond per regel af om "totaal klopt niet met som"-bugs te vermijden.
• Refunds vergeten. Bij multi-currency refunds moet currency expliciet meekomen.
• Observability overslaan. Log elke koers-fetch met bron, timestamp en latency.

Veelgestelde vragen

Ondersteunt Shopify Payments elke valuta? Nee. De lijst presentment currencies is beperkt en regio-afhankelijk. Voor niet-ondersteunde valuta route je via een andere processor of toon je alleen conversies zonder in die valuta af te rekenen.

Kan ik Finexly rechtstreeks Shopify's conversiekoersen laten sturen? Niet direct — Shopify Payments gebruikt de eigen bron. Wel kun je Finexly-koersen via de Admin API in de handmatige Markets-instelling voeden en zo de automatische koersen effectief vervangen.

Hoe vaak koersen verversen? Voor de meeste storefronts is 2–5 minuten edge cache bovenop Finexly's per-minuut updates de sweet spot. Bij hoge AOV of lage marge strakker (30–60 s); bij lage AOV en snelbewegende goederen tot 15 minuten.

Heb ik een multi-currency API nodig als ik Shopify Payments gebruik? Vaak wel — voor alles rondom het checkout: boekhoudreconciliatie, marketinganalytics, leveranciersfacturatie en prijzen in markten buiten Shopify's dekking. Zie onze accounting software integratiegids.

Wat is de beste manier om multi-currency checkout te testen? Gebruik Bogus Gateway in een development store, wissel je IP via VPN om landen te simuleren en controleer of orderbevestiging, ontvangst en Admin consistente presentment-bedragen tonen. Test daarna een refund — daar breken de meeste integraties stilzwijgend.

Sneller opleveren met Finexly

Multi-currency checkout op Shopify lijkt simpel van buiten en heeft een lange staart aan randgevallen. Met een sterke wisselkoers-API eronder worden de meeste casussen voorspelbare patronen — cachen, afronden, opslaan, reconciliëren.

Klaar om betrouwbare wisselkoersen in je Shopify-winkel of app te integreren? Haal je gratis Finexly API-key — zonder creditcard. Start met 1.000 gratis requests per maand en schaal mee met je winkel.