Shopify Storefront API: Tüm Geliştiriciler ve Satıcılar için Kapsamlı Rehber

Shopify Storefront API, headless vitrinler, mobil uygulamalar ile IoT ve yapay zeka ajanı entegrasyonlarına kadar tamamen özel alışveriş deneyimleri oluşturmanıza imkan tanıyan herkese açık bir GraphQL API'sidir. Shopify ticaret arka ucunu yönetirken siz özel çözümler geliştirebilirsiniz. Admin API'nin aksine, tarayıcılar ve mobil istemcilerden güvenli bir şekilde çağrılması için tasarlanmıştır. Şu anda bir proje için değerlendiriyorsanız, mevcut kararlı sürüm 2026-04'tür ve 2026-07 sürüm adayı zaten test için hazırdır.

Ana noktalar

• Storefront API herkese açık ve istemci tarafından güvenli bir şekilde çağrılabilir; Admin API güvenli bir sunucuda kalmalıdır.
• Sepet mutasyonları (cartCreate, cartLinesAdd, cartBuyerIdentityUpdate) her yapının ihtiyaç duyduğu temel yazma işlemleridir.
• API sürümleri üç aylık bir döngüyü takip eder: 2026-01, 2026-04, 2026-07, 2026-10. Eski 2024-10 sürümü Ekim 2026'da sona erecektir.
• Hydrogen 2026.4.0, Storefront API proxy'sini zorunlu hale getirdi ve arka uç onay modunu varsayılan olarak etkinleştirdi. Upgrade etmeden önce denetim yapmanız gereken iki kırılan değişikliktir.
• Hydrogen 2026.1.4 itibariyle, Oxygen üzerindeki her Hydrogen vitrine /api/mcp'de bir MCP uç noktası otomatik olarak sunulur ve hiçbir özel kod olmadan yapay zeka ajanı için hazır bir ticaret uç noktası oluşturur.

Shopify Storefront API nedir?

Storefront API, Shopify'ın müşteriye yönelik GraphQL API'sidir. Ürünlere, koleksiyonlara, metaobjelere ve menülere okuma erişimi, artı alıcıların gerçekten yaptığı iki şey için yazma erişimi sağlar: sepeti yönetmek ve müşteri olarak kimlik doğrulaması yapmak.

Shopify'ın kendi dokümantasyonunun erişim modelini nasıl çerçevelediği aşağıda verilmiştir: Storefront API birincil olarak salt okunurdur; kimlik doğrulama ve sepet yönetimi hariç. Bu sınır kasıtlıdır. Hiçbir gizli kimlik bilgisine dokunmadan her ürün detayını getire, canlı bir filtre kullanıcı arayüzü oluştura ve tam bir ödeme akışı inşa edebilirsiniz.

Uç nokta deseni basittir:

https://{your-store}.myshopify.com/api/2026-04/graphql.json

Her istek, Shopify-Storefront-Public-Token başlığı gerektirir (veya sunucu tarafı Hydrogen çağrıları için özel token eşdeğeri). Token gizli değildir ve tarayıcı veya mobil koddaki içine gömmek için uygundur. Admin API anahtarınız ve şifreniz ise istemci tarafı kodunda asla görünmemelidir.

Storefront API ile Admin API: gerçek fark

Bu, her satıcının ve geliştiricinin ilk sorduğu sorudur ve cevap mimarî, sadece özelliklerin bir listesi değildir.

Admin API, Shopify mağazanız verilerine tam okuma ve yazma erişimi sunar: siparişler, müşteriler, ürünler, envanter, yerine getirme, analitik ve daha fazlası. Storefront API bu idari işlevleri kasıtlı olarak eksik bırakır. Siparişleri değiştiremez, envanteri yönetemez veya iç analitiğe erişemezsiniz. Bu, geçici bir sorunu değildir; bu, tokeni güvenle bir React bileşenine gömmek için gereken güvenlik sınırıdır.

Yaygın bir hata: İstemci tarafı kodunda Admin API kimlik bilgilerini kullanmak. Bu, mağaza kimlik bilgilerinizi halka açık hale getirir. Admin API çağrılarını her zaman güvenli bir arka uç sunucusunda tutun. Depolama verilerine istemci tarafı erişime ihtiyacınız varsa, bu tam olarak Storefront API'sinin amacıdır.

Temel yetenekler: gerçekten ne inşa edebilirsiniz

Ürün ve koleksiyon sorguları

Ürün başlıklarını, açıklamaları, varyant fiyatlandırmasını, envanter durumunu, görselleri ve metaalan alanlarını getirin. GraphQL, yalnızca ihtiyacınız olan alanları istemenize imkan tanıdığından, bir ürün kartı sorgusu şişirgin REST yükü yerine yalın bir 3 alanlı yanıt döndürebilir. Yalnızca istediğiniz verileri almak hızı ve verimliliği, performansa duyarlı uygulamalar için ideal kılar.

Bir önemli son değişiklik: GraphQL ürün varyantları şimdi ürün başına 2.000'e kadar destekler, önceki 100 varyant tavanından genişletilmiştir. Yapılandırılabilir ürünler satıyorsanız (boyut x renk x malzeme), bu önemlidir.

Sepet mutasyonları

Sepet nesnesi, her Storefront API yapısının kalbidedir. Mevcut mutasyon yüzeyi şunları içerir:

• cartCreate, yeni bir sepet oluşturun ve isteğe bağlı olarak tek bir çağrıda bir satır öğesi ekleyin
• cartLinesAdd, mevcut bir sepete bir veya daha fazla ürün varyantı ekleyin
• cartLinesUpdate, mevcut satırları güncelle (çağrı başına 250 değere kadar kabul eder)
• cartLinesRemove, satırları kimlik ilerine kaldırın
• cartDiscountCodesUpdate, indirim kodlarını uygulayın veya temizleyin (tüm mevcut kodları sağlanan listede değiştirin)
• cartGiftCardCodesAdd / cartGiftCardCodesRemove, hediye kartı kullanımını yönetin
• cartBuyerIdentityUpdate, oturum açmış bir müşteriyi ilişkilendirin, bir B2B şirket konumu ayarlayın veya teslimat yöntemi gibi ödeme tercihlerini yapılandırın
• cartMetafieldsSet, özel ödeme mantığı için sepete rasgele metaalanları yazın

Bilmek için değer olan bir son ekleme: CartLine türü şimdi viewKey alanını döndürür, böylece döndürülen satırları cartLinesUpdate ve cartLinesRemove'a gönderilen view_key ile ilişkilendirebilirsiniz. Iyimser kullanıcı arayüzü güncellemeleri oluştururken yararlıdır.

Gizlilik uyumlu onay

Storefront API sürümü 2025-10 ve sonrası itibariyle, @inContext yönergesi visitorConsent bağımsız değişkenini kabul eder. Bu, onay durumunu doğrudan sepet oluşturma çağrısına kodlemenize ve bunu ortaya çıkan checkoutUrl'ye otomatik olarak dahil etmenize imkan tanır. Sonuç: Ayrı bir çerez yazma katmanı olmadan GDPR ve CCPA uyum akışları.

Metaobjeleri ve token tabanlı erişim

Bazı özellikler herkese açık erişim tokeni ötesinde token tabanlı kimlik doğrulama gerektirir. Ürün etiketleri, metaobjeleri, metaalanları, mağaza navigasyon menüleri ve müşteri verileri token kapsamlı erişimin arkasında bulunur. Bu kapsamları talep etmek, Shopify yönetim panelinde Storefront API uygulaması oluştururken yapılır.

API sürümü oluşturma: satıcıların ve geliştiricilerin takip etmesi gereken

Shopify'ın Storefront API'si üç aylık bir yayın döngüsünü takip eder: sürümler 2026-01, 2026-04, 2026-07 ve 2026-10 olarak adlandırılır. Her sürüm yayınlandıktan sonra 12 ay boyunca desteklenir. Desteklenmeyen API sürümlerine yapılan çağrılar, uygulamaların listesinin kaldırılması veya yüklenmesinin engellenmesiyle sonuçlanır.

Şu anda anahtar tarihler şunlardır:

• 2026-04 mevcut kararlı (en son) sürümdür.
• 2026-07 yayın adayıdır ve Shopify'ın Yaz 2026 Sürümü'ne (kod adı Compass) bağlıdır ve sepet ve ürün sorgu yapılarında 65 ürün güncellemesi ve kırılan değişiklikler içerir.
• 2024-10 Ekim 2026'da sona erecektir. Headless yapınız hala bu sürümdeyse, göçü için sonlu bir süreniz vardır.

2026-07 kırılan değişiklikleri her headless yapıyı etkiler: Hydrogen, Next.js Commerce, Nuxt veya tamamen özel. Shopify, Hydrogen projelerine sorgu göçlerini otomatikleştirmek için codemods sağlar.

Şimdi harekete geçip geçmeyeceğini değerlendiren satıcılar için: 2025-04'ten daha eski herhangi bir sürümde özel bir headless yapı çalıştırıyorsanız, bu çeyrek içinde geliştiricinizle bir sürüm denetimi planlayın. Bir sürüm denetiminin tipik olarak neleri içerdiğini görmek için Shopify geliştirici hizmetleri sayfamızı ziyaret edin.

Hydrogen bağlantısı: Storefront API proxy'si artık zorunludur

Hydrogen, doğrudan Storefront API'nin üzerine inşa edilen Shopify'ın React tabanlı çerçevesidir ve 2026'da ikisi arasındaki ilişki önemli ölçüde sıkılaştı.

Hydrogen 2026.4.0 (17 Nisan 2026'da gönderildi) iki kırılan değişiklik sundu:

1. Storefront API proxy'si artık her zaman etkindir. proxyStandardRoutes yapılandırma seçeneği kaldırılmıştır. Eğer bir istek işleyicisi, yük bağlamında storefront örneği olmadan çalışırsa, çalışma zamanı hatası fırlatır. Proxy'yi atlatan herhangi bir özel Hydrogen kurulumu güncellenmelidir.
2. Arka uç onay modu artık varsayılandır. Hydrogen artık istemci tarafı _tracking_consent çerezine dayanmaz. Onay artık Storefront API proxy'si aracılığıyla sunucu tarafı çerezileri aracılığıyla yönetilir. _tracking_consent için document.cookie okuyan özel onay afişleri yükseltmeden sonra boş bir değer görecektir.

Bu iki değişikliğin neden birleştirildiği nedeni: arka uç onay modunun tüm amacı, onay yazışımalarının proxy eksik olduğunda sessizce başarısız olamamasıdır. Proxy'nin zorunlu hale gelmesi, ön koşuldu.

Özel bir Hydrogen kurulumu çalıştırırsanız (temiz bir create-hydrogen iskeletine benzer olmayan herhangi bir proje), 2026.4.x'e yükseltmeden önce createRequestHandler çağrılarınızı ve onay afişi mantığını denetleyin.

2026'daki en büyük değişim: vitriniz artık bir yapay zeka ajanı uç noktasıdır

Bu, Storefront API'sinin rolünü en temel düzeyde değiştiren geliştirmedir.

Hydrogen 2026.1.4 yerleşik Storefront MCP (Model Context Protocol) proxy desteği ekledi. Oxygen üzerindeki her Hydrogen mağazası şu anda /api/mcp'de hiç özel kurulum olmadan bir MCP uç noktası sunmaktadır. Uygulamada bunun anlamı: ChatGPT, Perplexity ve özel alışveriş ajanları gibi yapay zeka asistanları, ürünlerinizi keşfedebilir, sepetleri yönetebilir ve Storefront API'sinden gerçek zamanlı verilerle desteklenen doğal dili kullanarak alıcıları ödeme yoluyla rehberlik edebilir.

Shopify üç ayrı MCP yüzeyini ortaya koymaktadır:

• Katalog MCP, Shopify satıcıları arasında küresel ürün keşfi
• Storefront MCP, satıcıya özel arama, politikalar ve SSS'ler
• Ödeme MCP, programlı sepet oluşturma, güncellemeler ve ödeme tamamlama

Storefront MCP aracılığıyla herkese açık ürün keşfi ek kimlik doğrulama gerektirmez. Kimliği doğrulanmış sepet işlemleri, Hydrogen uygulamanızın zaten gönderdiği mevcut Shopify-Storefront-Private-Token başlığını kullanır.

Proxy'nin mağazanızda etkin olduğunu doğrulamak için: Oxygen dağıtımınızda /api/mcp isabet edin. Shopify'ın Storefront MCP sunucusuna yönlendirirse, canlısınız.

Henüz Hydrogen'a geçmemiş satıcılar için bu, göçü değerlendirmek için somut bir nedentir. Shopify'ın CDN'sindeki Liquid temalar tutarlı ancak sabit performans sunar. Oxygen'de Hydrogen bu performans temelini artı hiçbir bozulma olmadan yapay zeka ajanı entegrasyonunu sunar. Yapay zeka ticaret özelliklerinin ROI hesaplaması Hydrogen'ın lehine kaymaktadır. Hydrogen göçünün neleri içerdiğini Shopify headless geliştirici sayfamızda keşfedebilirsiniz.

Satıcılar ve geliştiriciler için pratik denetim listesi

Hydrogen vitrine çalıştırıyorsanız:

• Storefront API 2026-04 (mevcut en son) üzerinde olduğunuzu doğrulayın
• createRequestHandler'ı artık kaldırılmış proxyStandardRoutes seçeneği için denetleyin
• Onay afişinizin _tracking_consent yerine sunucu tarafı çerezileri okuduğunu kontrol edin
• Oxygen dağıtımınızda /api/mcp'yi test edin ve MCP'nin etkin olduğunu doğrulayın
• 2026-07 yayın adayına karşı sınama başlatın; Ekim'e kadar beklemeyin

Özel headless yapı çalıştırıyorsanız (Next.js, Nuxt, vb.):

• Mevcut API sürümünüzü belirleyin ve 2024-10'un Ekim 2026 batışına karşı eşleyin
• Sepet ve ürün sorgu yapılarıyla kırılma değişiklikleri için 2026-07 changelog'unu gözden geçirin
• Sonraki Shopify Editions döngüsünden önce codemods veya el ile sorgu güncellemelerini planlayın

Standart bir Liquid teması çalıştırıyorsanız:

• Storefront API, istemci tarafı onu çağıran herhangi bir üçüncü taraf uygulamayı kullanan durumlarda hala geçerlidir
• Bu uygulamaların 2026-04 veya daha yeni sürümleri hedeflediğini doğrulayın
• Hydrogen'daki yapay zeka ajanı yeteneklerinin göç değerlendirmesini haklı kılıp kılmadığını göz önünde bulundurun

Storefront API artık sadece "headless Shopify" API'si değildir. Bu, kataloğunuzu alıcının kullanabileceği her yüzeye bağlayan veri katmanıdır: tarayıcı, mobil, ses ve şimdi yapay zeka ajanları. Sürümünüzü güncel tutmak ve Hydrogen kurulumunuzu Shopify'ın proxy ve onay gereksinimleriyle uyumlu tutmak, bu yüzeyleri açık tutan bakım işidir.