Shopify Storefront API: Neler Değişti ve Üzerinde Harekete Geçmeniz Gerekenler

Shopify Storefront API, geliştiricilerin headless storefrontlardan mobil uygulamalara ve AI ajanlarına kadar herhangi bir platformda tamamen özel alışveriş deneyimleri oluşturmasını sağlayan kamuya açık bir GraphQL API'sidir. 2026'da önceki herhangi bir yıldan daha hızlı ilerleme kaydetti: 2026-04 sürümü mevcut kararlı sürüm, 2026-07 bugün (30 Haziran 2026) release candidate olarak yayınlanıyor ve breaking changes ile beraber geliyorken, 2024-10 sürümü Ekim'de kullanımdan kaldırılıyor ve ekiplere geçiş için beş aylık bir süre veriliyor. Headless mağazanız şu anda desteklenen bir versiyonda değilse, sayaç çoktan çalışmaya başlamış demektir.

Temel çıkarımlar

• 2026-04 mevcut kararlı Storefront API sürümüdür; 2026-07 breaking cart ve product query değişiklikleri ile aktif release candidate'tir.
• Eski 2024-10 sürümü Ekim 2026'da sunsetlenecek, özel yapılandırmalar 8.000 dolar, çok geç kaldıysanız 40.000 dolar iyileştirme maliyetine maruz kalır.
• Sürüm 2025-10 @inContext direktifi üzerinde visitorConsent parametresini tanıttı ve GDPR/gizlilik onayını doğrudan checkout URL'sine kodluyor.
• 2026-07 başlayarak Cart, PRODUCT_UNAVAILABLE_IN_BUYER_LOCATION ve DELIVERY_SELECTED_OPTION_NOT_AVAILABLE uyarıları yayınlıyor, böylece kullanıcı arayüzünüzü alıcılara bunları gösterebilir.
• Storefront MCP get_cart/update_cart araçları UCP Cart MCP lehine kullanımdan kaldırılıyor, eski araçlar sadece 31 Ağustos 2026'ya kadar korunuyor.

Versiyonlama modeli: Shopify'ın üç aylık sürüm döngüsü nasıl çalışır

Shopify, her üç ayda bir Storefront API'nin yeni bir sürümünü yayınlar, Ocak, Nisan, Temmuz ve Ekim'de. Her kararlı sürüm, desteklenen yaşam döngüsü boyunca değişmez ve her kararlı sürüm en az 12 ay boyunca desteklenir, yani iki ardışık sürüm arasında en az dokuz aylık bir örtüşme vardır. Bu örtüşme sizin geçiş pencerenizdir.

Anlaşılması gereken üç izleme türü vardır:

• Kararlı (örneğin 2026-04), üretim için güvenli, garantili geriye dönük uyumlu.
• Release candidate (örneğin 2026-07), yeni kararlı sürün ile aynı gün yayınlanır, şimdi test için kullanılabilir ancak üretim için önerilmez.
• Kararsız, sürekli güncellenir, özellikler uyarı olmadan kaybolabilir; sadece geliştirme ve test için.

Bilmesi değer bir tuzak: entegrasyon erişilemeyen (emekli) bir sürümü hedefliyorsa, Shopify sessizce ileriye gider ve en eski erişilebilir kararlı sürümü sunar. X-Shopify-API-Version yanıt başlığı talep ettiğinizden farklı olacaksa, bu desteklenen bir sürümden sapıp sessiz breaking changes riskinde olduğunuzun sinyalidir.

Shopify App Store'da yayınlanan uygulamalar için tehlikeler daha yüksektir. Yükseltme tarihinden sonra desteklenmeyen kaynakları kullanmaya devam eden uygulamalar App Store'dan kaldırılır, kullanıcıların en az yedi gün boyunca yüklemesi engellenir.

API sürüm karşılaştırması: kararlı, release candidate ve kararsız izleme

2026-04'te gerçekten neler değişti (mevcut kararlı sürüm)

Hydrogen skeleton 2026-04 olarak yükseltildi. Hydrogen config'inizi 2026-01 olarak sabitlediyseniz, güncellemeniz gerekir. Skeleton paketi (skeleton@2026.4.0) şimdi Storefront API ve Customer Account API çağrıları genelinde 2026-04 hedeflemektedir.

Shopify Functions'ta Metaobject Erişimi. 2026-04, Shopify Functions'ın metaobject verilerini doğrudan sorgulamasını mümkün kılar. Metaobject tanımlarını çalışma zamanında okuyabilecek Functions tabanlı indirim veya teslimat mantığınız varsa, şimdi kullanılabilir.

128KB'de JSON metafield sınırı. API sürümü 2026-04'ten başlayarak, Shopify JSON metafield değerlerini 128KB'de sınırlandırır. Mağazanızı büyük JSON metafield'ları okuyorsa, herhangi bir sürüm yükseltmesi payloadları sessizce kırmadan önce verinizi şimdi denetleyin.

2026-07 breaking changes: headless yapılandırmalar hangi yama gerekir

Shopify'ın Yaz 2026 Baskısı (kod adı Compass) 65 ürün güncellemesini sunarken, Storefront API 2026-07 her headless yapılandırmayı etkileyen cart ve product query yapılarında breaking changes tanıtıyor, Hydrogen, Next.js Commerce, Nuxt veya tamamen özel.

Ekim'den önce dikkat gerektiren işte budur:

Cart uyarı sinyalleri. 2026-07 başlayarak Cart nesnesi iki yeni uyarı türü yayınlar:

• PRODUCT_UNAVAILABLE_IN_BUYER_LOCATION, cart satırı alıcının konumunda kullanılamayan bir ürün içerdiğinde ateşlenir. Etkilenen her cart satırı kendi uyarısını döndürür, target Cart Line ID olarak ayarlanır, böylece UI'deki doğru satıra eşleyebilirsiniz.
• DELIVERY_SELECTED_OPTION_NOT_AVAILABLE, alıcının seçtiği teslimat seçeneği kullanılamaz hale geldiğinde ateşlenir (örneğin, cart adres değişikliğinden sonra). Daha önce, sistem alıcıya hiçbir bildirim olmaksızın teslimat seçeneklerini sessizce değiştirirdi. Şimdi bunu programsal olarak tespit edebilir ve alıcıdan tekrar seçim yapmasını isteyebilirsiniz.

Metaobject enum kaldırması. Metaobject tanımlarında kullanımdan kaldırılan PRIVATE ve PUBLIC_READ erişim kontrol enumları 2026-07'de kaldırılır. Uygulamanız veya mağazanız bu enum değerlerine referans veriyorsa, sürüm kararlı hale gelmeden önce mevcut erişim kontrol modeline güncelleyin.

İndirim alanı yeniden yapılandırması. 2026-07 Cart üzerindeki indirim ile ilgili alanları yeniden yapılandırır. Mağazanızda özel indirim görüntüleme veya kupon mantığı varsa, şimdi release candidate'a karşı yeniden düzenlemeye başlayın. Hydrogen kullanıcıları çoğu yapısal alan yeniden adlandırması için codemods alırlar; özel çerçeveler kendi başlarına kalırlar ve iyileştirme tahminleri mağaza karmaşıklığına bağlı olarak 8.000 ile 40.000 dolar arasında değişir.

Ekim 2026 tarihi sabittir. API sürümü 2024-10 Ekim 2026'da sunsetlenir. Beş ay rahat görünüyor, ama staging deploy'ları, regresyon testleri ve cart mantığının genellikle herhangi bir headless stack'in en kırılgan bölümü olduğu gerçeği işlem yapıldığında, kesinlikle öyle değildir. Şimdi 2026-07 release candidate'a karşı test etmeye başlayın.

Gizlilik uyumlu checkout'lar @inContext visitorConsent ile

Bu 2025-10'da inişler ve son zamanlarda Storefront API'ye eklenen en pratik şeylerden biri olarak kalır. @inContext direktifi şimdi visitorConsent parametresini kabul eder, geliştiricilerin alıcı onay tercihlerini, analitikleri, tercihleri, pazarlamayı ve veri satışını cart işlemlerine geçmesine olanak tanır.

Mekanikler temizdir: onayı cartCreate veya cartBuyerIdentityUpdate mutasyonunda şu şekilde kodlarsınız:

@inContext(visitorConsent: {
  analytics: true,
  preferences: true,
  marketing: false,
  saleOfData: false
})

Onay bilgileri otomatik olarak kodlanır ve sonuçtaki checkoutUrl'ye dahil edilir, checkout süreci boyunca gizlilik uyumluluğu sağlanır. Shopify, URL'ye eklediği _cs parametresini checkout sırasında okur, bunu çıkarmayın.

Bu GDPR ve benzer rejimler için önemlidir. Daha önce bir çerez banner'ından onayı checkout'a yayınlamak için temiz bir yöntemi olmayan headless mağazalarının şimdi API'nin kendisinde yerleşik bir birinci taraf mekanizması vardır. Modern bir headless yapılandırmasının bunu uygulamayı göz ardı etme bahanesi yoktur.

Hız sınırları: yeni bot ve ajan gerçekliği

Shopify şimdi Storefront API'ye ve Shopify tarafından barındırılan çevrimiçi mağaza sayfalarına erişen botlara ve ajanlara daha katı hız sınırları uygulamaktadır. İsteklerini imzalamayan botlar ve ajanlar en katı sınırlara tabi tutulur; daha yüksek hız sınırlarına nitelendirilmek için operatörlerin Web Bot Auth kullanarak istekleri imzalaması gerekir.

Yasal mağaza sahipleri ve geliştiriciler için pratik çıkarım iki katlıdır:

1. Storefront API uç noktalarına çarpan özel bir tarayıcı, fiyat toplayıcı veya AI alışveriş ajanı işletiyorsanız, isteklerinizi imzalayın veya daralmayı bekleyin.
2. Storefront MCP entegrasyonu oluşturuyorsanız (sonraki bölüme bakın), ajanınızın profili düzgün şekilde kayıtlı olduğundan emin olun, böylece uygun erişim katmanı alır.

Storefront API'nin meşru alıcı isteklerinin sayısına uygulanan hız sınırı olmadığını ve flash satışlar sırasında eşzamanlılığı yönetmeden ölçeklenecek şekilde tasarlandığını unutmayın. Yeni sınırlar özellikle kötü amaçlı veya tanınmayan bot trafiğini hedefler.

Ajan ticareti: Storefront API UCP ve MCP ile buluşuyor

Bu 2026'da Storefront API'inin rolünde en yapısal olarak önemli kaymadır. API artık sadece headless insana yönelik mağazalar için omurga değildir. Şimdi AI ajanları için giriş noktasıdır.

Shopify, Universal Commerce Protocol'ü (UCP) Google ile ortaklaşa AI ajanlarının tüccarlarla işlem yapmasının nasıl yapılacağı için açık standart olarak geliştirdi. UCP keşiften cart'lar ve checkout'a kadar tüm ticaret yolculuğunu kapsar ve Amazon, Meta, Microsoft, Salesforce, Stripe ve Wayfair dahil olmak üzere geniş endüstri desteğine sahiptir.

Geliştiriciler için, somut uygulama yüzeyi Storefront MCP sunucusudur. Her Shopify mağazasının ürün araması, cart işlemleri ve politika soruları dahil olmak üzere storefront özellikleri sunan kendi MCP uç noktası vardır. search_catalog, lookup_catalog ve get_product araçları UCP spesifikasyonuna uyumludur.

Kritik geçiş notu: Eski Storefront MCP cart araçları (get_cart ve update_cart) UCP Cart MCP lehine kullanımdan kaldırılıyor. Kullanımdan kaldırılan araçlar 31 Ağustos 2026'ya kadar korunacaktır, bu 2024-10 API sunset ile aynı çeyreklik. İki geçiş aynı sonbahar tarihine yakınsamaktadır.

Markali bir ajan veya özel bir AI alışveriş deneyimi oluşturuyorsanız, mimari basittir:

• Katalog araması ve ürün ayrıntı alımı için Storefront MCP kullanın.
• Cart işlemleri (ekle, güncelle, satır öğeleri oku) için UCP Cart MCP kullanın.
• Ödeme devri için Checkout Kit'i (veya yaklaşan Checkout MCP, şu anda iş ortağı önizlemesinde) kullanın.

Özel ajanlar oluşturmayan tüccarlar için pratik işlem daha basittir: Shopify admin'de Agentic Storefronts aracılığıyla satmak istediğiniz AI kanallarını açın ve Shopify protokol işini halleder. ChatGPT, Google AI Mode, Perplexity ve Microsoft Copilot hepsi tek bir admin konfigürasyonu aracılığıyla erişilebilir.

Kimlik doğrulama ve erişim tokenleri: Ocak 2027'de neler değişir

2026 API sürüm döngüsünün dışında kalan ancak Storefront API entegrasyonlarını doğrudan etkileyen bir öğe: 1 Ocak 2027'den başlayarak, tüm kamuya açık uygulamalar Admin API çağrıları için son kullanma tarihi olan çevrimdışı erişim tokenleri kullanmalıdır. Bu bir Admin API değişikliğidir, Storefront API değişikliği değil, ancak birçok entegrasyon her ikisini birlikte kullanır, headless yapılandırmanız arka uç işlemleri (envanter senkronizasyonu, sipariş yönetimi, metafield yazması) için uzun süreli Admin API tokenine dayanıyorsa, bunu Storefront API sürüm yükseltmesiyle birlikte planlaymanız gerekir.

2026'nın geri kalanı için geçiş kontrol listeniz

Sırasıyla aciliyet sırasına göre sıralanmış, ardışık eylem listesi:

1. Mevcut sabitlenmiş sürümünü kontrol edin. Hydrogen config'inizi veya GraphQL sorgu başlıklarını açın. 2025-07'den daha eski bir şey acil dikkat gerektiriyor.
2. 2026-07 RC'ye karşı test edin. Release candidate'a karşı staging ortamını ayarlayın. Cart mutasyonları ve özel indirim görüntüleme mantığına odaklanın.
3. @inContext üzerinde visitorConsent uygulayın. Headless yapılandırmanız henüz çerez banner'ından onayı checkoutUrl'ye yayınlamıyorsa, şimdi ekleyin. API sürümü 2025-10 veya daha yenisini gerektirir.
4. Kullanımdan kaldırılan metaobject enumlarını değiştirin. 2026-07 1 Temmuz'da kararlı hale gelmeden önce PRIVATE veya PUBLIC_READ referanslarını kaldırın.
5. Storefront MCP cart araçlarından UCP Cart MCP'ye geçiş yapın. Son tarih: 31 Ağustos 2026.
6. 128KB'den fazla JSON metafield'ları denetleyin. Herhangi bir 2026-04+ yükseltmesinden önce gerekli.
7. Storefront API uç noktalarına çarpan herhangi bir bot veya ajandır işletiyorsanız Web Bot Auth imzası kaydedin.

Bu geçişlerden herhangi birini planlama veya yürütme konusunda uygulamaya dayalı yardıma ihtiyacınız varsa, sunduğum Shopify geliştirici hizmetleri sürüm yükseltmeleri, headless mimari incelemeleri ve Storefront API performans denetimlerini kapsar.