5 Kasım 2026 · 6 dk okuma

Shopify API 2027-01 Geriye Dönük Uyumluluğu Bozan Değişiklikleri: Kapsamlı Geliştirici Kontrol Listesi

Shopify API 2027-01, 1 Ocak 2027'de yayınlanacak ve beş önemli geriye dönük uyumluluğu bozan değişiklik içeriyor.

Shopify API 2027-01 Geriye Dönük Uyumluluğu Bozan Değişiklikleri: Kapsamlı Geliştirici Kontrol Listesi

Shopify API 2027-01 sürümü 1 Ocak 2027'de kararlı hale gelecek ve son çeyreklere kıyasla tek bir çeyrek yayında en yüksek oranda zorunlu kaldırma işlemi barındırıyor. Uygulamanız veya özel entegrasyon kodunuz automaticDiscounts çağrısı yapıyor, bir hediye kartında line_item_id yazıyor veya bildirilmemiş metafield sahip türleriyle bir ödeme sayfası UI uzantısı dağıtıyorsa, bu tarihte bozulacak veya engellenecektir. Düzeltmeler çoğunlukla basittir, ancak tatil sezonunun ortasındaki son tarihten önce büyük bir kod tabanında bunları bulmak gerçek zorluk.

Temel bilgiler

  • automaticDiscounts, QueryRoot'tan tamamen kaldırıldı; bunu discountNodes(query: "method:automatic") ile değiştirin ve tüm GraphQL türlerini yeniden oluşturun.
  • DiscountAutomaticConnection ve DiscountAutomaticEdge de ortadan kaybolduğundan, bu türlere referans veren herhangi bir üretilmiş istemci kodu 2027-01'de bozulur.
  • Hediye kartı line_item_id, REST Admin API'sinde salt okunur hale gelir; Shopify yazma sırasında alanı sessizce yoksayar ve hata döndürmez, bu da hatayı tespit etmeyi zorlaştırır.
  • owner_type, shopify.extension.toml'deki her metafield bildiriminde artık gereklidir; eksik alan dağıtımı tamamen engeller.
  • Aynı sürümde iki ek kaldırma gerçekleşir: metafieldInteger koleksiyon koşulları ve marketCurrencySettingsUpdate.

Karşısında olduğunuz zaman dilimi

2027-01 şu anda yayın adayı durumundadır (mevcut en son kararlı sürüm 2026-10'dur). Yayın adayı penceresi, üretim trafiğine dokunmadan göçleri test etmenizin son şansıdır. API sürümü 2026-01, 16 Ocak 2027'de kullanımdan kaldırılır, bu nedenle hala oraya sabitlenmiş olan herhangi bir uygulama yeni kararlı sürüm düştüğünde birkaç gün içinde 2027-01 bölgesine itilir.

Shopify API sürümüYayın tarihiKullanılabilirMevcut durum
2026-101 Ekim 202616 Ekim 2027En son kararlı
2027-011 Ocak 202716 Ocak 2028Yayın adayı
2026-011 Ocak 202616 Ocak 2027Yakında kullanımdan kaldırılacak

En güvenli yol: tüm göçleri 2026-10'da tamamlayın (zaten tüm değiştirme API'lerini destekliyor), sonra 1 Ocak kesintisinden önce 2027-01'e temiz bir sürüm güncellemesi yapın.

Geriye dönük uyumluluğu bozan değişiklik 1: GraphQL Admin'den automaticDiscounts kaldırıldı

automaticDiscounts, 2027-01'de QueryRoot üzerinde artık bulunmamaktadır. Bunu içeren herhangi bir sorgu doğrulama başarısız olur ve hemen hata döndürür, veri döndürmez. automaticDiscountNodes sorgusu da kullanımdan kaldırılmıştır (2027-01'de henüz kaldırılmasa da, buna yeni bir şey inşa etmeyin).

Değiştirme, method:automatic filtresiyle discountNodes'dir:

# Öncesi (2027-01'de başarısız olur)
query {
  automaticDiscounts(first: 10) {
    edges {
      node {
        ... on DiscountAutomaticBasic {
          title
          startsAt
        }
      }
    }
  }
}

# Sonrası (2026-10 ve 2027-01'de çalışır)
query {
  discountNodes(first: 10, query: "method:automatic") {
    edges {
      node {
        discount {
          ... on DiscountAutomaticBasic {
            title
            startsAt
          }
        }
      }
    }
  }
}

Satır içi fragmentlerin DiscountNode üzerindeki discount alanına bir seviye daha derine gittiğine dikkat edin. Yapısal bu değişiklik, otomatik olarak oluşturulan istemcileri bozar: DiscountAutomaticConnection ve DiscountAutomaticEdge her ikisi de kaldırılmıştır, bu nedenle türlerinizi 2027-01 şema anlık görüntüsüne göre yeniden oluşturmak zorunludur.

Bu değişiklik için göç kontrol listesi:

  • Kod tabanında (oluşturulan dosyalar da dahil) automaticDiscounts, DiscountAutomaticConnection ve DiscountAutomaticEdge arayın.
  • Tüm eşleşen sorguları query: "method:automatic" ile discountNodes kullanacak şekilde yeniden yazın.
  • GraphQL şema anlık görüntüsünü ve istemci türlerini 2027-01'e göre yeniden oluşturun.
  • 1 Ocak'tan önce bitiremediyseniz, güvensiz geri dönüşe güvenmek yerine açıkça 2026-10'a sabitleyin.

Geriye dönük uyumluluğu bozan değişiklik 2: Hediye kartı line_item_id REST'te salt okunur

REST Admin API sürümü 2027-01'de, Hediye Kartı kaynağındaki line_item_id salt okunur olur. Uygulamalar bu alanı oluşturma veya güncelleme isteklerinde gönderebilir, ancak Shopify bunu sessizce yoksayacak. Hediye kart ile kaynak siparişi satır öğesi arasındaki ilişki artık yalnızca Shopify tarafından yönetilir.

Bu sessiz yoksayma davranışı tehlikeli kısımdır. Entegrasyon sisteminiz 422 veya kullanıcı hatası almayacak. 200 alacaksınız ve yazma işlemi basitçe atılacak. Değişikliğin hiçbir etkisi olmadığını doğrulamanın tek yolu aynı hediye kartını tekrar okuması ve line_item_id'nin değişmediğini doğrulaması gerekir.

Bu ilişkiyi harici olarak ayarlamak, değiştirmek veya temizlemek için değiştirme API'si yoktur. ERP veya yerine getirme sisteminiz hediye kartlarını siparişlere bağlamak için line_item_id yazıyorsa, bu kod yolu kaldırılması ve veri modeli güncellenmesi gerekir.

Bu değişiklik için göç kontrol listesi:

  • REST entegrasyon kodunda Hediye Kartı oluşturma (POST /admin/api/.../gift_cards.json) ve güncelleme (PUT /admin/api/.../gift_cards/{id}.json) çağrılarını arayın ve istek gövdesinde line_item_id içeren olanları bulun.
  • Bu alanları yük taşıyıcılarından kaldırın.
  • Test suite'inize bir geri okuma onaylaması ekleyin: line_item_id olmadan bir hediye kartı oluşturun ve yanıt değerinin Shopify'ın natively ayarladığıyla eşleştiğini doğrulayın.
  • REST Admin API'si 1 Ekim 2024'ten beri eski sistem olarak atanmış; yeni hediye kartı işi GraphQL Admin API'sini kullanmalıdır.

Geriye dönük uyumluluğu bozan değişiklik 3: Uzantı metafield bildirimlerde owner_type gerekli

Bu bir, TOML'de sessizce oturacak ve CLI dağıtmayı reddedene kadar. API sürümü 2026-10 ile başlayarak, Ödeme Sayfası ve Müşteri Hesabı UI uzantıları, shopify.extension.toml'deki her metafield bildiriminde bir owner_type içerebilir. 2027-01 ile başlayarak, bu gereklidir ve herhangi bir bildirim eksikse CLI dağıtımı engeller.

Nedeni performanstır: sahip türünü bildirmek, ödeme sayfasının metafield'ları yalnızca uzantının gerçekte kullandığı kaynak türlerinden önceden yüklemesine izin verir, geniş bir seti düşünceyle yükleme yerine.

Geçerli bir bildirim şöyle görünür:

# shopify.extension.toml

[[extensions.metafields]]
namespace = "custom"
key       = "badge"
owner_type = "PRODUCT"

[[extensions.metafields]]
namespace = "custom"
key       = "note"
owner_type = "CUSTOMER"

Ödeme Sayfası UI uzantıları için desteklenen sahip türleri CART, COMPANY, CUSTOMER, PRODUCT, SHOP ve VARIANT'dir (her birinin ne sahip olduğuna dair bir hatırlatıcıya ihtiyacınız varsa Shopify metafields sözlüğü'ne bakın). COMPANY ve CUSTOMER sahip türleri, uygulamanızda korumalı müşteri verileri erişim bildirimini gerektirir.

Aynı namespace/key kombinasyonunu birden fazla kaynak türünden okursanız, her sahip türü için ayrı bir [[extensions.metafields]] bloğu gereklidir. Bunları daraltamazsınız.

Düzeltme bugün 2026-10'da kullanılabilir. owner_type ekleyin, yeniden dağıtın ve 2027-01 yükseltmesi, Ocak ortasındaki dağıtım bloğu yerine tek satırlı bir sürüm değişikliği haline gelir.

Bu değişiklik için göç kontrol listesi:

  • Ödeme Sayfası ve müşteri hesabı uzantıları için her shopify.extension.toml dosyasını açın.
  • Hem [[extensions.metafields]] hem de [[extensions.targeting.metafields]] bloklarını kontrol edin.
  • Her bildirimine owner_type ekleyin. Doğru tür açık değilse (B2B ödeme sayfaları şirket konum metafields kullanırken yaygın bir sınır durumu), önce 2026-10 çalıştıran bir geliştirme mağazasında test edin.
  • Yeniden dağıtın ve CLI'nin hiçbir doğrulama uyarısı bildirmediğini doğrulayın.

Aynı sürümde iki ek kaldırma

2027-01 için değişik günlük, üç başlık değişiklikten daha geniştir. Burada işaretlemeye değer iki ek kaldırma vardır.

metafieldInteger koleksiyon koşulları kaldırıldı. metafieldInteger giriş ve CollectionSourceInclusionConditionMetafieldInteger türü ortadan kayboldu. Değiştirme, metafieldInt ve karmaşık olmayan bir yakalama vardır: value alanı türü Int hazır değerinden String'e değişir. Yani value: 2000, value: "2000" olur. İlişki enumerasyonları (EQUALS, GREATER_THAN, LESS_THAN) değişmeden kalır. Kesmeye geçmeden önce 2026-10'da metafieldInt'i test edebilirsiniz.

marketCurrencySettingsUpdate mutasyonu kaldırıldı. Para birimi ayarlarını yönetmek için marketCreate ve marketUpdate'i kullanın. 2027-01'de kaldırılan mutasyona referans veren herhangi bir istek, yalnızca sorun alanı değil, tüm işlemi başarısız kılar, çünkü GraphQL doğrulama tüm istek belgesini reddeder.

Doğrulama yaklaşımı

Herhangi bir uygulamayı veya entegrasyonu 2027-01'e yükseltmeden önce, bu sırayı izleyin:

  1. Şema farkı. Shopify CLI (shopify app generate schema --api-version 2027-01) kullanarak 2027-01 şemasını indirin ve bunu mevcut şema anlık görüntünüzle karşılaştırın. Kodunuzun referans verdiği ve yeni şemada bulunmayan her tür veya alan, göç hedefidir.
  2. Tam metin araması. Kaldırılan her sembolü adıyla arayın: automaticDiscounts, DiscountAutomaticConnection, DiscountAutomaticEdge, line_item_id, metafieldInteger, CollectionSourceInclusionConditionMetafieldInteger, marketCurrencySettingsUpdate.
  3. TOML denetimi. Her shopify.extension.toml dosyasında [[extensions.metafields]] ve [[extensions.targeting.metafields]] blokları arayın, sonra her birinin owner_type olduğunu doğrulayın.
  4. Hazırlama çalışması. Hazırlama uygulamasını 2027-01 sürümüne işaret edin ve indirimler, hediye kartları, akıllı koleksiyonlar, pazarlar ve ödeme sayfası uzantılarına dokunan her kod yolunu uygulayın. Yalnızca HTTP 500'leri değil, doğrulama hatalarını izleyin.
  5. Açıkça sabitleyin. 1 Ocak 2027'de herhangi bir göç tamamlanmazsa, bu entegrasyonu açıkça 2026-10'a sabitleyin. Sürümü olmayan veya unstable uç noktasına güvenmeyin.

10.000'den fazla SKU kataloğu çalıştırıyor ve şema farkı adımı tek başına, özellikle de kırık tür referansının yazdığınız sorgudan iki katman uzakta bulunduğu oluşturulan Apollo veya urql istemcilerinde, manuel aramanın kaçırdığı sürüm yükseltmesi gerilemeçlerini yakalayor.

Sonuç

2027-01 şu anda yayın adayıdır, bu da bu göçleri zorunlu hale gelmelerinden önce test etmek için hafta, gün değil var demektir. Değişiklikler bireysel olarak küçük ancak toplu olarak yoğundur ve beş tanesinin üçü yığının farklı katmanlarını etkiler (GraphQL Admin, REST Admin ve uzantı TOML yapılandırması). En güvenli strateji, tüm göçleri bugün 2026-10'da tamamlamaktır, çünkü tüm değiştirme API'leri zaten orada desteklenmektedir ve 1 Ocak yükseltmesini bir göç olayı yerine bir sürüm dizesi değişikliği olarak ele alın.

Bu işi dışarıya vermek isterseniz, stüdyom Lintel Shopify API ve ERP entegrasyonları hizmeti veriyor.

shopifyapigraphqlbreaking-changescheckout-extensions

Sıkça sorulan sorular

Shopify API 2027-01'de automaticDiscounts sorgusunun yerini ne alıyor?

Bunun yerine discountNodes'i query: "method:automatic" ile kullanın. Temel yapısal fark, indirim türü üzerindeki satır içi fragmentlerin şimdi DiscountNode'un discount alanı üzerinde bulunması, eski automaticDiscounts yanıtından bir seviye daha derindir. Ayrıca herhangi bir otomatik olarak oluşturulan GraphQL istemci türünü yeniden oluşturmalısınız, çünkü DiscountAutomaticConnection ve DiscountAutomaticEdge aynı sürümde kaldırılmıştır.

2027-01'de bir hediye kartı REST isteğinde line_item_id göndermek için Shopify hata döndürür mü?

Hayır. REST Admin API sürümü 2027-01'de, Shopify line_item_id içeren oluşturma ve güncelleme isteklerini kabul eder, ancak alanı sessizce yoksayar. Shopify'ın dahili olarak ayarladığından değişmeden bir yanıt ile 200 alacaksınız, bu nedenle yazmanın hiçbir etkisi olmadığını doğrulamak için hediye kartını geri okumalısınız.

Shopify ödeme sayfası UI uzantısında metafield bildirimleri için owner_type nereye eklerim?

shopify.extension.toml içindeki [[extensions.metafields]] ve [[extensions.targeting.metafields]]'de her girişe owner_type ekleyin. Geçerli değerler CART, COMPANY, CUSTOMER, PRODUCT, SHOP ve VARIANT'ı içerir. Aynı namespace ve key birden fazla kaynak türü için geçerliyse, her sahip türü için ayrı bir bildirim bloğu oluşturun. Alan 2026-10'da isteğe bağlı ve 2027-01'de (eksikse dağıtım bloğu yapılır) gereklidir.

Yedi yıllık Shopify, tek sayfada.

Roller, projeler, teknoloji yığını ve sertifikalar özgeçmişte.

Özgeçmiş PDF indir LinkedIn