Shopify için Çoklu Para Birimli Ödeme: 2026 Geliştirici Rehberi

Bir Shopify mağazası — veya mağazaya hizmet veren bir uygulama — geliştiriyorsanız, çoklu para birimli ödeme artık ekstra bir özellik değil. Uluslararası alıcılar ürün sayfasından son "Şimdi Öde" butonuna kadar fiyatları kendi para birimlerinde görmeyi bekler. Bu deneyim bozulduğunda sepet terk oranları tırmanır, chargeback'ler artar ve destek talepleri birikir. Bu rehber Shopify'ın çoklu para birimi sisteminin gerçekte nasıl çalıştığını, native araçların nerede yetersiz kaldığını ve boşlukları doldurmak için Finexly gibi özel bir döviz API'sini nasıl entegre edeceğinizi anlatır.

Headless bir storefront, özel bir Shopify uygulaması veya olgun bir Shopify Plus mağazasında Liquid temasını geliştiriyor olun, bu rehber çalışan bir çoklu para birimli ödemeyi sessizce gelir kaybeden bir versiyondan ayıran mimari kararları, API entegrasyonlarını ve uç durumları kapsar.

2026'da Shopify'da çoklu para birimli ödemenin önemi

Sınır ötesi e-ticaret artık online perakendenin önemli bir dilimini oluşturuyor. Yabancı bir para biriminde fiyatlandırılmış bir ürüne düşen alıcılar — ya da daha kötüsü, kendi para birimlerinde ama kötü dönüştürülmüş fiyatlarla karşılaşanlar — orantısız biçimde vazgeçer. Sürtünme yalnızca psikolojik değildir: yabancı para birimindeki kart işlemleri banka ücretleri, beklenmeyen toplamlar ve hatta dolandırıcılık uyarıları tetikler.

Dönüşüm çalışmaları aynı örüntüyü gösterir: yerel para biriminde fiyat sunan, yerel yuvarlama kurallarına uyan ve o para biriminde tahsilat yapan mağazalar tek para birimli mağazalara göre belirgin biçimde daha iyi dönüşüm sağlar. Teknik yük eskiden büyüktü — bugün birkaç API çağrısı ve temiz bir yenileme stratejisinden ibaret.

Shop currency ve presentment currency

Shopify'ın çoklu para birimi modeli iki kavram üzerine kuruludur:

• Shop currency — satıcının fiyatlar, raporlama ve ödemeler için kullandığı temel para birimi.
• Presentment currency — alıcının storefront'ta, sepette ve ödemede gördüğü para birimi.

Türkiye'deki bir müşteri shop currency'si USD olan bir mağazayı gezerken ürün ₺3.250 (presentment currency) olarak görünürken Shopify dahili olarak satışı $99,00 (shop currency) olarak kaydedebilir. Siparişler, iadeler ve işlemler her iki değeri saklar. GraphQL Admin API'de bunları her para değerli nesnede shopMoney ve presentmentMoney alanlarında görürsünüz.

Yaygın hata, API'den çekilen fiyatın her zaman birinde olduğunu varsaymaktır. Öyle değildir. Güncel API versiyonlarında Refund API'sindeki tüm okumalar varsayılan olarak presentment currency kullanır ve çoklu para birimli bir siparişte iade işlemi oluştururken currency alanını açıkça geçmezseniz çağrı hata döndürür. Katı kural: para değerine eşlik eden para kodunu her zaman okuyun.

Shopify'ın native seçenekleri (ve sınırları)

İki ana özellik:

1. Otomatik dönüşümlü Shopify Payments. Mağazanız uygunsa birden fazla presentment currency aktifleştirip Shopify yaklaşık 15 dakikada bir yenilenen kurlarla fiyatları otomatik dönüştürür. Küçük bir dönüşüm ücreti (genelde %1,5–2) uygulanır ve para birimi başına yuvarlama işlenir.

2. Shopify Markets üzerinden manuel kurlar. Kurları siz tanımlarsınız, Shopify şu formülü uygular:

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

Bu seçenekler temeli karşılar ama gerçek dünyada yetersiz kalır:

• Headless storefront'lar. Storefront API, Hydrogen veya özel frontend kullanırken gösterimi siz kontrol edersiniz — ve sıklıkla daha zengin veri gerekir (geçmiş kurlar, cross-rate'ler, tedarikçi faturalaması gibi ödeme dışı senaryolar).
• Shopify Payments dışındaki satıcılar. Stripe, PayPal, Adyen veya yerel işlemci kullananlar otomatik pipeline'a sahip değildir.
• Özel fiyat mantığı. Marketplace'ler, kademeli B2B fiyatlandırma, yerelleştirilmiş promosyonlar.
• Post-checkout uygulamalar. Muhasebe senkronu, fraud, sadakat sistemleri ve aggregator'lar çoklu para birimli siparişleri tek bir raporlama para birimine normalize etmek zorundadır — tam sipariş anındaki güvenilir geçmiş kurlarla.

Tüm bu durumlarda Shopify'ın yanında özel bir döviz API'sine ihtiyacınız vardır.

Harici döviz API'si ne zaman kullanılmalı

Pratik kural: aşağıdakilerden biri doğruysa Finexly gibi harici bir API devreye alın:

1. Headless veya hybrid bir storefront işletiyor ve canlı kurlara programatik erişim istiyorsunuz.
2. Shopify Payments'ın bölgenizde otomatik dönüştürmediği para birimlerini destekliyorsunuz.
3. Geçmiş siparişleri işleyen uygulamalar yazıyor ve sipariş anındaki kesin kura ihtiyaç duyuyorsunuz.
4. Tahsilat taahhüdü olmadan fiyatları farklı para birimlerinde göstermek istiyorsunuz.
5. Shopify'ın 15 dakikasından daha sık güncelleme gerekiyor — merkez bankası duyuruları gibi dönemlerde.

Daha fazla bağlam için döviz API karşılaştırmamıza ve FX verisi için REST vs WebSocket yazımıza bakın.

Finexly, 170+ para birimi için gerçek zamanlı ve geçmiş kurları temiz bir REST arabirimiyle, kurlara gizli dönüşüm ücretleri gömülmeden sunar.

Finexly ve Shopify ile çoklu para birimli ödeme oluşturma

Minimum mimari:

1. Alıcının para birimini tespit edin — geolokasyon, tarayıcı locale veya açık seçici ile.
2. Güncel kuru Finexly'den alın (edge'de cache'lenmiş, birkaç dakikada bir yenilenen).
3. Fiyatları dönüştürün — yuvarlama ve marj kurallarıyla.
4. Ödemede Shopify'ın presentment currency parametresini geçin ki sipariş doğru para biriminde oluşturulsun.
5. Kullanılan kuru mutabakat için sipariş metadata'sı olarak kaydedin.

Adım 1: Finexly'den güncel kuru alın

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"]

Hızlı kontrol için cURL:

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

Production'da bunu bir cache katmanına sarın — Redis, Cloudflare KV veya 60–300 saniye TTL'li in-process cache. Cache ve hata yönetimi rehberimize bakın.

Adım 2: Storefront'ta ürün fiyatlarını dönüştürün

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

Adım 3: Shopify ödemesine doğru para biriminde aktarın

Storefront API ile cart oluştururken presentment currency'yi geçirin. GraphQL Cart API'de buyerIdentity.countryCode hangi presentment currency'nin uygulanacağını belirler:

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

Shopify ardından fiyatları uygun presentment currency'de gösterir ve checkoutUrl o para biriminde tahsilat yapar — ödeme geçidiniz destekliyorsa.

Klasik (headless olmayan) bir storefront'ta API ile cart oluşturmazsınız. Geolocation uygulamasını kullanın veya URL parametresi ?currency=EUR ile para birimini belirleyin. {{ product.price | money }} gibi Liquid filtreleri aktif presentment currency'ye uyar.

Adım 4: Her siparişle kullanılan kuru saklayın

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() } });

Üç ay sonra bir muhasebeci neden #10042 siparişinin EUR toplamının USD × güncel kur ile eşleşmediğini sorduğunda, geleceğinizin kendiniz buna şükredeceksiniz.

Dönüştürülmüş fiyatları göstermek: Liquid vs Headless

Liquid (klasik temalar)

<!-- 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, özel)

// 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} />;
}

Next.js para birimi dönüştürücü eğitimimize bakın.

Zor kısımlar: yuvarlama, ücretler, tazelik

Yuvarlama kuralları. Japon yeninin ondalığı yoktur. İsviçre frangı geleneksel olarak en yakın 0,05'e yuvarlanır. Müşteriler çoğu ülkede .99 veya .95 ile biten fiyatlar bekler:

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);
}

Dönüşüm marjı. Shopify Payments kullanmıyorsanız ödeme işleyicinizin spread'ini karşılamak için gösterdiğiniz kura küçük bir marj (genelde %1–3) ekleyin. Açık ve pazar başına yapılandırılabilir olsun.

Kur tazeliği. Kurlar hareket eder. Merkez bankası duyurularında kurlar dakikalar içinde %1–2 oynayabilir. Finexly 60 saniyede bir günceller; 2 dakikalık edge cache ile neredeyse canlı fiyatlandırma elde edersiniz. Döviz dalgalanmasını yönetme yazımıza bakın.

Çoklu para birimli siparişleri takip ve mutabakat

Üç yaklaşım:

1. Sipariş anındaki kur — ekonomik gerçekliğe en yakını.
2. Ödeme anındaki kur — bankanıza düşen tutara denk gelir.
3. Aylık ortalama kur — muhasebe için daha yumuşak; Finexly geçmiş endpoint'ten.

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 ekipleri genelde gelir tanımı için #1'i, nakit mutabakatı için #2'yi tercih eder. İkisini de saklayın.

Yaygın tuzaklar

• Kurları sonsuza kadar cache'lemek. 24 saat çok uzun. TTL 5–10 dakika, circuit breaker ile.
• İstemciye güvenmek. Nihai fiyatları sadece JavaScript'te hesaplamayın — sunucuda veya Shopify Function'da doğrulayın.
• Sadece toplamı yuvarlamak. Satır bazında yuvarlayın ki "toplam kalemlerle eşleşmiyor" hataları çıkmasın.
• İadeleri unutmak. Çoklu para birimli iadelerde currency alanını açıkça geçin.
• Gözlemlenebilirliği atlamak. Her kur fetch'ini kaynak, zaman damgası ve gecikmeyle loglayın.

Sıkça Sorulan Sorular

Shopify Payments her para birimini destekliyor mu? Hayır. Presentment currencies listesi sınırlıdır ve bölgeye bağlıdır. Desteklenmeyen para birimleri için başka bir işlemciye yönlendirin ya da hedef para biriminde tahsilat yapmadan yalnızca dönüşümleri gösterin.

Finexly'yi Shopify'ın dönüşüm kurlarını doğrudan yönlendirmek için kullanabilir miyim? Doğrudan değil — Shopify Payments kendi kaynağını kullanır. Ancak Admin API üzerinden Finexly kurlarını manuel Markets ayarına besleyerek otomatik kurları etkin şekilde değiştirebilirsiniz.

Kurları ne sıklıkta yenilemeliyim? Çoğu storefront için Finexly'nin dakikalık güncellemelerinin üzerinde 2–5 dakikalık edge cache ideal noktadır. Yüksek AOV veya düşük marjlı ürünlerde 30–60 saniyeye; düşük AOV ve hızlı hareket eden ürünlerde 15 dakikaya kadar uzayabilir.

Shopify Payments kullanıyorsam çoklu para birimi API'sine ihtiyacım var mı? Sıklıkla evet — checkout'un çevresindeki her şey için: muhasebe mutabakatı, pazarlama analitiği, tedarikçi faturalaması ve Shopify'ın kapsamadığı pazarlardaki fiyat gösterimleri. Muhasebe yazılımı entegrasyon rehberimize bakın.

Çoklu para birimli ödemeyi nasıl test etmeli? Geliştirme mağazasında Bogus Gateway'i kullanın, farklı ülke bağlamlarını simüle etmek için VPN ile IP'nizi değiştirin ve sipariş onayının, makbuzun ve Admin'in eşleşen presentment tutarlarını gösterdiğini doğrulayın. Ardından bir iadeyi test edin — entegrasyonların çoğu sessizce orada kırılır.

Finexly ile daha hızlı yayına alın

Shopify'da çoklu para birimli ödeme dışarıdan basit görünür ve içeride uzun bir uç durum kuyruğu saklar. Altta sağlam bir döviz API'si varken, bu durumların çoğu bilinen örüntülere indirgenir — cache, yuvarla, sakla, mutabakat kur.

Shopify mağazanıza veya uygulamanıza güvenilir döviz kurlarını entegre etmeye hazır mısınız? Ücretsiz Finexly API anahtarınızı alın — kredi kartı gerekmez. Ayda 1.000 ücretsiz istekle başlayın ve mağazanız büyüdükçe ölçeklenin.