Shopify API Maliyeti: Sorgu Noktaları, Kovalar ve Hız Sınırlaması Rehberi

Shopify API maliyeti ticari müşteriler için bir şey ("API faturama ne kadar ek maliyet ekler?") ve geliştirici için tamamen başka bir şey ("neden saat 2'de senkronizasyonum 429 alıyor?") anlamına gelir. İlk sorunun cevabı basittir: Shopify API çağrısı başına ücret almaz. İkinci sorunun cevabı gerçek işin başladığı yerdir, çünkü GraphQL Admin API, çoğu geliştiricinin öğrendiği REST uç noktasından hiç benzemeyen karmaşıklık tabanlı bir maliyet modeli kullanır.

Önemli noktalar

• Shopify API çağrısı başına hiçbir şey almaz. Hız limitleri finansal değil, teknikseldir.
• GraphQL Admin API istek sayısı değil, puanla hesaplanan sorgu maliyetini ölçer.
• Tek bir sorgu, planınız ne olursa olsun 1.000 puana kapatılmıştır.
• Plan başına iyileştirme oranları: 100 puan/sn (Standart), 200 puan/sn (Gelişmiş), 1.000 puan/sn (Plus), 2.000 puan/sn (Kurumsal).
• 2026-01 API sürümünden itibaren, her uygulama mağaza başına tip başına beş eşzamanlı toplu işlem çalıştırabilir, önceden bir tane vardı.

Neden "Shopify API maliyeti" iki farklı şey anlamına gelir

Bu sorguyu arayan ticari müşteriler genellikle API çağrısının Shopify faturalarına eklenmesinin gerekip gerekmediğini bilmek ister. Hayır, eklenmez. Admin API, Storefront API ve Customer Account API hepsi planınıza dahildir ve çağrı başına ücret yoktur. Planın kontrol ettiği şey hız limiti bütçesi ve bu bütçe entegrasyonlarınızın ne kadar hızlı hareket edebileceğini belirler.

Geliştiriciler bu konuyu diğer yönden karşılarlar: Standart planda iyi çalışan bir senkronizasyon, katalog boyutu artışından sonra müşterinin mağazasında başarısız olmaya başlar ya da bir depoda ki başsız yapı Plus hesaba benzer kod çalıştığında azaltılır. Her iki semptom de aynı maliyet modeline bağlı olur.

GraphQL sorgu maliyeti nasıl hesaplanır

GraphQL Admin API'sine yapılan çağrılar hesaplanan sorgu maliyetine göre sınırlandırılır, bu da istek sayısından ziyade zaman içinde istek maliyetini göz önünde bulundurmanız gerektiği anlamına gelir.

Shopify GraphQL için istek sayımını kaldırdı. Sunucu yürütmeden önce sorgunuz üzerinde statik analiz çalıştırır, karmaşıklığa göre puanlandırır ve bir kovadan puan çıkarır.

Puanlama kuralları sabittir ve belgelenmiştir. Shopify geliştirici belgelerinden tam maliyet tablosu:

İstenen maliyet, istekte seçilen alanların bileşimine dayanır. Gerçek maliyet, sorgu sonuçlarına dayanır ve döndürülen gerçek nesneler veya istenen daha az kenar döndüren bağlantılar nedeniyle istenen maliyetten daha düşük olabilir.

Hız limitleri istenen ve gerçek sorgu maliyetinin bir kombinasyonunu kullanır. Yürütme başlamadan önce, bir uygulamanın kovasında sorgunun istenen maliyeti için yeterli kapasite olması gerekir. Yürütme tamamlandığında, kova istenen maliyet ile sorgunun gerçek maliyeti arasındaki fark için geri ödenir.

Bu gerçekten yararlı bir özelliktir. products(first: 250) sorgularsanız ama yalnızca 12 ürün varsa, 252 puan ayırsınız ama yürütmeden sonra çoğu geri ödenir. Tehlikeli durum tersidir: bir döngü içinde iç içe bir bağlantıda first: 250 istersiniz ve statik analiz sonuçlarınız gelmeden en kötü durum maliyetini görür.

Çalışan örnek

Bu sorgu puanlamayı pratikte gösterir:

{
  products(first: 50) {
    edges {
      node {
        id
        title
        variants(first: 10) {
          edges {
            node {
              id
              sku
              price
            }
          }
        }
      }
    }
  }
}

• products(first: 50) bağlantısı: 2 + 50 = 52 puan
• 50 ürünün içindeki her variants(first: 10) bağlantısı: (2 + 10) x 50 = 600 puan
• Skaler alanlar (id, title, sku, price): 0 puan
• İstenen maliyet: yaklaşık 652 puan

Bu tek sorgu, Standart planın tüm kovasının yarısından fazlasıdır. Tek bir kötü yapılandırılmış sorgu 1.000 puana mal olabilir. İyi optimize edilmiş bir sorgu 50'nin altında maliyeti olabilir.

Tahmin etmeden alan başına dökümler almak için istek başlığına X-GraphQL-Cost-Include-Fields: true ekleyin. İsteğinize X-GraphQL-Cost-Include-Fields: true başlığı ekleyerek uzantı nesnesinde ayrıntılı alan başına sorgu maliyetleri alabilirsiniz.

Hiçbir planın kaldıramadığı sert tavan

Tek bir sorgu plan limitlerinden bağımsız olarak 1.000 puanı aşamaz. Bu limit, sorgunun istenen maliyetine dayalı olarak sorgu yürütülmeden önce uygulanır.

Bu, sorunu düzeltir düşünerek Plus'a yükselen geliştiriciyi yakalayan tuzaktır. Kova boyutu ve iyileştirme hızı her ikisi de plan ile ölçeklenir, ancak 1.001 istenen puanı vurmuş bir sorgu her planda reddedilir. Üstel geri tepme bunu asla düzeltmez. Sorguyu yeniden yapılandırmanız gerekir.

Plana göre hız limitleri (Ekim 2026 doğrulanmış)

Resmi Shopify plan iyileştirme oranları aşağıdaki gibidir:

Eylül 2026 itibariyle, kova kapasitesi eşleşecek şekilde ölçeklenir: Standart'ta 2.000 puan ve Plus'ta 20.000.

Karşılaştırma için, eski REST Admin API hala istek tabanlı sızdıran kova kullanır. Eski REST Admin API, 40 isteğin sızdıran kovasını saniyede 2 ile doldurarak kullanır, Plus'ta onkat artırılır.

Pratik sonuç: aynı bağlayıcı iki farklı depoda tamamen farklı bir ürün gibi davranır ve azaltılmış bir senkronizasyonun düzeltilmesi neredeyse hiçbir zaman daha büyük bir plan değildir. Standart'tan Plus'a yükseltme size 10 kat iyileştirme hızı verir, ancak zaten 1.000 puanın üzerinde olan bir sorguyu ya da throttleStatus yanıtını yok sayan senkronizasyon modelini düzeltmez.

Üretimde throttleStatus okuma

Shopify Admin GraphQL API'sinden gelen her başarılı ve azaltılmış yanıt, extensions.cost.throttleStatus nesnesini içerir. Bu nesne üç kritik tam sayı içerir: maximumAvailable, currentlyAvailable ve restoreRate.

Azaltılmış bir yanıt şu şekildedir:

{
  "errors": [{
    "message": "Throttled",
    "extensions": {
      "code": "THROTTLED",
      "cost": {
        "requestedQueryCost": 500,
        "throttleStatus": {
          "maximumAvailable": 2000,
          "currentlyAvailable": 120,
          "restoreRate": 100
        }
      }
    }
  }]
}

currentlyAvailable (120) ve restoreRate (100 puan/sn) adresinden, yeniden denemeden önce ne kadar bekleneceğini tam olarak hesaplayabilirsiniz: (requestedCost - currentlyAvailable) / restoreRate = (500 - 120) / 100 = 3,8 saniye. Bu bir tahmin değil, belirleyici bir gecikmedir.

Güvenilir bir üretim modeli, her yanıttan sonra uzantı bloğundan currentlyAvailable okur ve kalan bütçe sonraki sorgunun requestedQueryCost'unun altına düştüğünde önceden uyku uyur. Çoğu geliştirici yalnızca THROTTLED hatalarına yanıt verir, bu da her reddetme sırasında bir gidiş dönüşü yakmak anlamına gelir. Bütçeyi önceden okumak bu boşa giden çağrıları tamamen ortadan kaldırır.

Kova ile mücadele etmeyi bırakıp Toplu İşlemler'i ne zaman kullanacağı

10.000+ SKU içeren depolar üzerinde yaptığım katalog çalışması için, sayfalanmış GraphQL döngüleri kayıt sayısı birkaç yüzü aştığında yanlış araçtır. Toplu İşlemler API'si tam olarak bunun için vardır.

Büyük veri setlerini çıkarmanız gerektiğinde, Toplu İşlemler API'sine geçmelisiniz. Bu API, Shopify'ın eşzamansız olarak yürüttüğü tek bir GraphQL sorgusu göndermenizi sağlar. Sonuçlar JSONL dosyasına yazılır ve Shopify işlem tamamlandıktan sonra dosyayı indirmek için güvenli bir URL sağlar.

Eşzamanlılık modeli 2026'nın başlarında önemli ölçüde değişti. API sürümleri 2026-01 ve üzeri için, her uygulama mağaza başına tip başına beş toplu mutasyon işlemi eşzamanlı olarak çalıştırabilir. Bu, her işlemin tamamlanmasını beklemeden aynı anda birden fazla veri setini içe aktarmanızı sağlar. 2026-01'den önceki API sürümlerinde, her uygulama mağaza başına her tip için aynı anda yalnızca bir toplu işlem çalıştırabilir.

Bu göç boru hatları için anlamlı bir değişikliktir. 2026-01 öncesi kodunda, çalışan bir ürün dışa aktarması aynı mağazada aynı uygulamadan bir sipariş dışa aktarmasını engeller. 2026-01 ile beş paralel mutasyon işini ve beş paralel sorgu işini aynı anda çalıştırabilir, bu büyük içe aktarma sürelerini önemli ölçüde azaltır.

Toplu işlemler karar rehberi

Toplu sorgu sonuçları tamamlanmadan sonra yedi gün boyunca kullanılabilir kalır, bu nedenle akış aşağı worker URL'si süresi dolmadan önce JSONL akışını ve işlemesini yapması için cömert bir pencereye sahiptir.

Sorgu maliyetini gerçekten azaltan beş model

Bunlar, inşa ettiğim uygulamalar ve entegrasyonlar arasında azaltma konusunda tutarlı olarak needle taşıyan ayarlamalardır:

• Sadece ihtiyacınız olan alanları isteyin. Skaler alanlar 0 puan maliyetindedir. 50 öğe ürün bağlantısına id ve title eklemek hiçbir şey ekstra masraflı değildir. Ancak her iç içe bağlantı çoğaltılır. Yanıtta etkin olarak kullanmadığınız herhangi bir alanı kaldırın.
• first argümanınızı küçültün. first: 250 içeren bir ürün bağlantısı hiçbir iç içe geçme öncesinde 252 puanın maliyeti vardır. 27 puana first: 25 öğeye bırakmak. Kullanıcı arayüzünüz yalnızca 24 öğe gösterirse, asla 250'ye ihtiyacınız olmadı.
• restoreRate'e karşı hız yapın, THROTTLED hatalarına karşı değil. Her yanıttan sonra currentlyAvailable'ı okuyun. Sonraki sorgunun requestedQueryCost'u currentlyAvailable'ı aşarsa, hesaplanan boşluğu uyutun. Bu reddedilen istekleri ortadan kaldırır.
• Mutasyonları doğru toplu olarak işleyin. Mutasyonlar, sorgulardan doğal olarak daha pahalıdır. Her mutasyonun varsayılan 10 puanlık maliyeti vardır ve Shopify bireysel alanları daha yüksek fiyatlandırma hakkını saklı tutar. Toplu iş boyutlarınızı yalnızca dizi uzunluğuna değil, maliyet modeline göre planlayın.
• Doğru eşikte Toplu İşlemler'e geçin. 1.000+ kayıtlara dokunan herhangi bir veri işlemi için Toplu İşlemler API'sini kullanın. 50.000 siparişi Standart planda sayfalandırmaya çalışmak kovayi tekrar tekrar tüketecektir. Tek bir toplu sorgu aynı veriyi eşzamansız olarak hiçbir puan maliyeti olmadan işler.

Kaynak tabanlı limitler: daha az konuşulan tavan

Sızdıran kovanın ötesinde, bilmeye değer ikinci bir limit sınıfı vardır. Bir mağazada 500.000 ürün varyantı bulunduğunda, herhangi bir API üzerinde her gün en fazla 10.000 yeni varyant oluşturulabilir. Bu eşiğin ötesinde, ilgili GraphQL Admin API mutasyonları günlük kısıtlamaya tabidir ve sınıra ulaşan bir uygulama, bir kısıtlamanın uygulandığını belirten bir ileti ile 429 Çok Fazla İstek yanıtı alır.

Sızdıran kova kısıtlaması ve bağlantı sayfalanması gibi kavramların sözlüğü için, bu terimler üretimde bu limitleri hata ayıklanırken tekrar tekrar ortaya çıkar.

Kendi sorgu maliyetlerinizi doğrulama

Herhangi bir yeni senkronizasyon veya veri yoğun özellik göndermeden önce, Shopify'ın yerleşik GraphiQL explorer'ında (https://your-store.myshopify.com/admin/apps/graphiql adresinde mevcuttur) hedef sorguyu çalıştırın ve yanıtındaki extensions.cost bloğunu kontrol edin. requestedQueryCost tam olarak kova ayırmanızı söyler. actualQueryCost gerçekten ödediğinizi söyler. Boşluk büyükse, first argümanınızı artırmak veya kapsama vurmadan bağlantılar eklemek için manevra alanınız vardır.

requestedQueryCost 800'ü aşan herhangi bir sorgu için, Standart plan deposuna ulaşmadan önce yeniden düzenleme adayı olarak davranın. Bu 200 puanlık arabellek, bir sorguda her müşteri hesabında çalışan ile ölçekte sessizce başarısız olan bir sorgu arasındaki farktır.