Shopify GraphQL tarifleri
Geliştiricilerin en çok aradığı işler için sorgular ve mutation’lar: toplu dışa aktarma, metafield’lar, ürünler, stok, indirimler, siparişler ve Storefront sepeti.
Kısaca
Bunlar Shopify’ın Admin ve Storefront API’leri (sürüm 2026-10) için kopyalanmaya hazır GraphQL belgeleri. Her sayfada sorgu ya da mutation, örnek değişkenler, gereken erişim yetkileri (scope) ve yanıtın nasıl göründüğü var. Yayımlamadan önce her belgeyi ve değişkenlerini Shopify’ın yayımladığı şemayla doğruluyoruz. REST Admin API artık eski (legacy) kabul edildiği için yeni uygulamalarda bu GraphQL çağrılarını kullanın.
- 27 sayfa; müşteri işleri dahil her mağazada ücretsiz kullanılabilir (MIT lisansı)
Toplu işlemler
Büyük verileri sayfa sayfa gezmeden dışa ve içe aktarın.
Tüm ürünleri bulk operation ile dışa aktarma
Tüm Shopify ürünlerini ve varyantlarını bulkOperationRunQuery ile JSONL dosyasına aktarın, işlemi takip edin ve sonucu indirin.
Bir tarih aralığındaki siparişleri bulk operation ile dışa aktarma
Belirli bir tarih aralığındaki tüm Shopify siparişlerini satır kalemleriyle birlikte bulkOperationRunQuery ve orders filtresiyle JSONL dosyasına aktarın.
Staged upload ve bulkOperationRunMutation ile toplu içe aktarma
Bir mutation’ı binlerce kez çalıştırın: değişkenlerden oluşan JSONL dosyasını stagedUploadsCreate ile yükleyin, ardından bulkOperationRunMutation’ı başlatın.
Metafield ve metaobject’ler
Ürünlere, müşterilere ve diğer kayıtlara kendi verilerinizi yazın ve okuyun.
metafieldsSet ile metafield yazma
Herhangi bir kayıtta en fazla 25 metafield’ı tek ve atomik bir çağrıyla oluşturun ya da güncelleyin; compareDigest ile yeni değerlerin üzerine yazmayın.
Metafield tanımı oluşturma
metafieldDefinitionCreate ile tipli ve doğrulamalı bir metafield tanımı oluşturun, admin’de sabitleyin ve Storefront API’ye açın.
Metaobject tanımı oluşturma ve kayıtları upsert etme
Beden tablosunu metaobject olarak kurun: tanımı metaobjectDefinitionCreate ile oluşturun, kayıtları handle’a göre metaobjectUpsert ile ekleyip güncelleyin.
Ürünler ve stok
Ürün ve varyant oluşturun, stoğu senkron tutun.
productSet ile ürünü tek seferde oluşturma ya da güncelleme
Harici bir sistemden ürünü tek çağrıda senkronize edin: productSet, ürünü seçenekleri ve varyantlarıyla birlikte handle’a göre oluşturur ya da günceller.
Varyantları toplu oluşturma ve güncelleme
Yeni beden ya da renkleri productVariantsBulkCreate ile ekleyin, varyant fiyatlarını productVariantsBulkUpdate ile toplu değiştirin; her çağrı tek ürün içindir.
Harici bir sistemden stok miktarlarını ayarlama
inventorySetQuantities ile ürün ve lokasyon bazında stoğu ayarlayın; 2026-10’da zorunlu olan changeFromQuantity ve idempotency key dahil.
Lokasyona göre stok seviyelerini okuma
Bir lokasyondaki tüm ürünlerin satılabilir, eldeki, ayrılmış ve yoldaki stoğunu ya da tek bir ürünün tüm lokasyonlardaki stoğunu okuyun.
Ürünleri combined listing altında birleştirme
Ayrı renk ürünlerini tek bir ilan olarak gösterin: bir parent ürün oluşturun, ardından combinedListingUpdate ile child ürünleri ve seçenek değerlerini bağlayın.
İndirimler ve Functions
İndirim oluşturun ve Function’ları koddan açın.
Bir indirim Function’ını otomatik indirim olarak etkinleştirme
İndirim Function’ınızı discountAutomaticAppCreate ile mağazada etkinleştirin: function handle, indirim sınıfları, birleşme kuralları ve JSON ayar metafield’ı.
Toplu indirim kodu ekleme
discountRedeemCodeBulkAdd ile mevcut bir kodlu indirime çağrı başına 250’ye kadar benzersiz kod ekleyin, ardından hangi kodların eklendiğini kontrol edin.
Teslimat, ödeme ya da doğrulama Function’ını etkinleştirme
Deploy edilmiş bir Function’ı deliveryCustomizationCreate, paymentCustomizationCreate ya da validationCreate ile mağazada açın; ayarları metafield’la verin.
Siparişler ve müşteriler
Sipariş düzenleyin, taslak oluşturun, gönderin, iade edin ve etiketleyin.
Verilmiş bir siparişi düzenleme
orderEditBegin, orderEditAddVariant, orderEditSetQuantity ve orderEditCommit ile siparişe ürün ekleyin, adetleri değiştirin ve değişikliği onaylayın.
Özel fiyatlı taslak sipariş oluşturma
draftOrderCreate ile teklif ya da B2B siparişi oluşturun: priceOverride ile varyant fiyatını değiştirin, kendi fiyatıyla özel satırlar ekleyin.
Takip numarasıyla gönderim (fulfillment) oluşturma
Bir siparişin açık fulfillment order’larını okuyun, ardından fulfillmentCreate ile kargo firması, takip numarası ve URL’siyle gönderim oluşturun.
Sipariş iadesi oluşturma
suggestedRefund ile iade tutarını hesaplayın, ardından refundCreate ve bir idempotency key ile ürünleri iade edin, stoğa alın ve ödemeyi geri gönderin.
Siparişlere, müşterilere ya da ürünlere toplu etiket ekleme
tagsAdd ile tek bir kayda mevcut etiketlerini silmeden etiket ekleyin ya da tagsAdd’i bir bulk mutation içinde çalıştırıp binlerce kaydı birden etiketleyin.
Bir segmentteki müşterileri listeleme
customerSegmentMembers ile bir müşteri segmentinin üyelerini sayfalayın ya da customerSegmentMembersQueryCreate ile anlık bir segment sorgusu çalıştırın.
Çevirileri kaydetme, gerekirse pazar bazında
translatableResource ile çevrilebilir içeriği ve digest’leri okuyun, çevirileri translationsRegister ile, isterseniz tek bir pazar için kaydedin.
Webhook’lar
Sürekli sorgulamak yerine bir şey değiştiğinde haber alın.
Filtreli webhook aboneliği oluşturma
Yalnızca gereken webhook’ları alın: webhookSubscriptionCreate ya da shopify.app.toml ile Shopify arama sözdiziminde filtreli bir abonelik oluşturun.
Storefront API
Headless vitrinler için sepet, yerel fiyatlar ve özel veriler.
Storefront API ile sepet oluşturma ve ürün ekleme
Headless bir sepet kurun: satırlar ve alıcı ülkesiyle cartCreate, yeni ürünler için cartLinesAdd ve alıcıyı ödemeye yönlendirmek için checkoutUrl.
@inContext ile yerel fiyat ve dil gösterme
Sorguya @inContext(country, language) ekleyerek Storefront API’den fiyatları alıcının para biriminde, içeriği de kendi dilinde alın.
Storefront API ile metafield ve metaobject okuma
Bir ürünün metafield’larını okuyun, beden tablosu gibi bir metaobject referansını takip edin ve SSS gibi bir tipteki tüm metaobject’leri listeleyin.
Temeller
Sayfalama, sorgu maliyeti ve istek sınırları.
Sorgu maliyetini ve throttle durumunu okuma
Her Admin API yanıtı, maliyetini ve kalan kotayı extensions.cost içinde bildirir. Bunu istekleri dengelemek ve THROTTLED hatalarını yönetmek için kullanın.
Sonuçları cursor ile sayfalama
Tüm ürün, sipariş ya da müşterileri sayfa sayfa okuyun: pageInfo isteyin, endCursor’ı after olarak verin, hasNextPage false olunca durun.
Kod hakkında
- Gösterilen tarihte, 2026-10 sürümünün Admin veya Storefront API şemasıyla doğrulandı. İstek adresinizdeki sürümü kontrol edin.
- Örneklerdeki ID’ler ve mağaza adresleri yer tutucudur. Kendi değerlerinizle değiştirin.
- Admin API çağrıları uygulamanızdan bir erişim anahtarı (access token) ister. Admin API anahtarını asla vitrine ya da temaya koymayın.
- MIT lisansı. Kodu kendi mağazanızda da müşteri işlerinizde de kullanabilirsiniz.
Mağazanız için kurulmasını, test edilmesini ve bakımını isterseniz: API entegrasyonları.
Sık sorulan sorular
- Shopify REST Admin API kullanımdan kalktı mı?
- Shopify, Ekim 2024’ten beri REST’i eski (legacy) olarak tanımlıyor ve yeni herkese açık uygulamaların Nisan 2025’ten beri GraphQL kullanması gerekiyor. REST’in tamamen kapanacağı bir tarih henüz açıklanmadı. Buradaki her tarif, yerini aldığı REST çağrısını da belirtiyor.
- Bu sorguları nerede çalıştırabilirim?
- Mağazanızın GraphiQL uygulamasında, uygulamanızın kodunda bir erişim anahtarıyla ya da Shopify CLI ile. Storefront API sorguları, herkese açık bir Storefront anahtarıyla tarayıcıdan da çalışır.
- Tarifler hangi API sürümünü kullanıyor?
- Her sayfanın kontrol edildiği tarihteki en güncel kararlı sürüm olan 2026-10’u. Belgelerin çoğu önceki ve sonraki sürümlerde de çalışır; değişen bir alan varsa sayfada belirtiyoruz.
