Lista kontrolna QA dla metafields Shopify przed API 2026-10

Metafields w Shopify pozwalają sprzedawcom i aplikacjom przechowywać własne dane na zasobach Shopify, takich jak produkty, klienci i zamówienia. Mogą wspierać informacje o produktach, notatki dotyczące realizacji, relacje między produktami, automatyzacje Shopify Flow oraz procesy backendowe.

Wraz z tym, jak metafields stają się częścią coraz większej liczby mechanizmów sklepu i integracji, ich konfiguracja nabiera większego znaczenia, zwłaszcza gdy aplikacje wykorzystują je w zapytaniach API.

Istotna zmiana pojawi się wraz z wersją 2026-10 interfejsu Shopify Admin GraphQL API, zaplanowaną na 1 października 2026 roku. Od tej wersji zapytanie filtrujące po metafield, który nie został poprawnie skonfigurowany do filtrowania, zwróci błąd. Wcześniej Shopify mogło po cichu zignorować nieprawidłowy predykat i zwrócić mylące wyniki. Shopify ogłosiło tę zmianę w swoim dzienniku zmian dla deweloperów z 24 lipca 2026 roku. 

Dla deweloperów utrzymujących aplikacje Shopify lub własne integracje to wyraźny sygnał, aby przed aktualizacją do wersji 2026-10 przejrzeć definicje metafields i filtrowane zapytania GraphQL.

Co zmienia się w Shopify API 2026-10

Od wersji API 2026-10 GraphQL Admin API weryfikuje filtry metafields przed wykonaniem zapytania. Według Shopify filtr metafield najczęściej kończy się niepowodzeniem, gdy:

• metafield nie ma definicji;
• definicja metafield nie jest skonfigurowana tak, aby umożliwiać filtrowanie;
• typ metafield nie obsługuje użytego filtra lub porównania.

Wcześniej nieprawidłowy predykat metafield mógł zostać zignorowany. Oznaczało to, że zapytanie mogło sprawiać wrażenie działającego, mimo że zwracane wyniki nie odzwierciedlały zamierzonego filtra. W wersji 2026-10 Shopify zamiast tego zwraca błąd wyjaśniający problem z filtrowaniem. Zmiana dotyczy aplikacji i integracji, które filtrują zasoby po metafields przez GraphQL Admin API w wersji 2026-10 lub nowszej. Zapytania korzystające z wersji 2026-07 i wcześniejszych zachowują dotychczasowe działanie do momentu aktualizacji.

Zapytania korzystające z metafields poprawnie skonfigurowanych do filtrowania, wraz z obsługiwanymi porównaniami, powinny nadal działać tak jak wcześniej.

Dlaczego definicje metafields mają znaczenie

Definicja metafield określa strukturę i zasady dla metafields współdzielących dany namespace i key. Definicje mogą określać takie właściwości jak:

• typ danych
• reguły walidacji
• ustawienia dostępu
• obsługiwane możliwości

Shopify udostępnia osobną dokumentację dotyczącą zarządzania tymi definicjami.

W kontekście filtrowania szczególnie ważna jest jedna możliwość: adminFilterable. Gdy jest włączona dla obsługiwanej definicji, adminFilterable pozwala używać wartości metafield podczas filtrowania obsługiwanych typów zasobów w panelu Shopify Admin i w GraphQL Admin API.

Shopify obecnie podaje wsparcie dla:

• produktów
• firm
• lokalizacji firm
• metaobiektów
• zamówień

Istnieją dodatkowe ograniczenia zależne od zasobu i typu metafield. Na przykład Shopify podaje, że Admin Filterable nie jest dostępne dla metafields typu JSON ani rich text. Oznacza to, że samo istnienie metafield nie gwarantuje jeszcze, że można go użyć w filtrze GraphQL. Poprawna konfiguracja filtrowania zależy od definicji, jej możliwości, typu metafield oraz porównania użytego w zapytaniu.

Inne ostatnie zmiany w Shopify również opierają się na definicjach metafields

Aktualizacja filtrowania w 2026-10 nie jest jedyną niedawną zmianą w Shopify, która zwiększa znaczenie definicji metafields.

Dostęp przez Customer Account API

16 czerwca 2026 roku Shopify zmieniło sposób dostępu do niektórych metafields przez Customer Account API. Metafields przechowywane na zasobie app resource muszą teraz mieć definicję metafield oraz odpowiednie uprawnienia konta klienta, aby były dostępne przez API.

Shopify zaleca deweloperom, których aplikacje zależą od tych pól w rozszerzeniach interfejsu konta klienta, Hydrogen lub sklepach headless, aby upewnili się, że metafields mają definicje i odpowiednie ustawienia dostępu.

Co ważne, Shopify wskazuje, że metafields należące do zasobów Customer lub Order nie są objęte tą konkretną zmianą.

Zmiany metafields mogą być używane w Shopify Events

Shopify rozszerzyło również podgląd deweloperski Events w lipcu 2026 roku. Aplikacje mogą subskrybować ukierunkowane zmiany metafields na zasobach takich jak:

• Product
• Order
• Customer
• Collection
• Location

Dzięki temu aplikacja może reagować na konkretną zmianę danych niestandardowych zamiast subskrybować każdą ogólną aktualizację zasobu i porównywać otrzymane payloady. Nie należy jednak jeszcze traktować tej funkcji jako stabilnej możliwości produkcyjnego API. Obecne przykłady Shopify konfigurują Events z użyciem: api_version = "unstable"
Opisana tutaj funkcjonalność Events pozostaje więc powiązana ze środowiskiem developer preview / unstable API Shopify.

Łącznie te zmiany pokazują, dlaczego deweloperzy powinni wiedzieć, od których metafields zależą ich aplikacje, jak są one zdefiniowane i gdzie są wykorzystywane.

Lista kontrolna QA dla Shopify Metafields przed 2026-10

Przed aktualizacją objętych zmianą integracji do API 2026-10 przejrzyj metafields używane w filtrowaniu GraphQL i potwierdź, że są poprawnie skonfigurowane.

1. Znajdź zapytania GraphQL filtrowane po metafields
   Zidentyfikuj zapytania w swoich aplikacjach i integracjach, które używają metafields jako filtrów w GraphQL Admin API.
2. Potwierdź definicje metafields
   Sprawdź, czy każdy metafield używany do filtrowania ma odpowiednią definicję z poprawnym owner type, namespace, key i typem danych.
3. Sprawdź możliwości filtrowania i typy pól
   Zweryfikuj, czy adminFilterable jest włączone tam, gdzie jest wymagane, oraz czy typ metafield obsługuje filtr lub porównanie użyte w zapytaniu.
4. Przetestuj zapytania na API 2026-10
   Uruchom objęte zmianą zapytania z użyciem wersji API 2026-10 i potwierdź, że zwracają oczekiwane wyniki bez błędów filtrowania metafields. Shopify wyraźnie zaleca testowanie zapytań filtrowanych po metafields przed aktualizacją.
5. Przejrzyj powiązane zależności API
   Jeśli Twoje wdrożenie korzysta z metafields zasobu aplikacji przez Customer Account API, potwierdź, że wymagane definicje i ustawienia dostępu są na miejscu. Jeśli używasz Shopify Events, przejrzyj też workflow reagujące na zmiany metafields. Pamiętaj, że ta funkcjonalność Events obecnie korzysta z wersji API Shopify unstable.
6. Udokumentuj właścicieli i pola legacy
   Zapisz, która aplikacja, integracja lub który zespół odpowiada za ważne metafields. Zidentyfikuj też zduplikowane lub starsze pola przed wprowadzaniem zmian w schemacie. Nie jest to wymóg wprowadzony przez API 2026-10, ale ułatwia utrzymanie i audyt zależności od metafields.

Nie czekaj z wykrywaniem nieprawidłowych filtrów do momentu aktualizacji API

Od wersji 2026-10 Admin GraphQL API nieprawidłowe filtry metafields będą zwracać błędy zamiast być po cichu ignorowane. Przed aktualizacją przejrzyj metafields używane przez Twoje integracje do filtrowania, potwierdź poprawność ich definicji i możliwości filtrowania oraz przetestuj objęte zmianą zapytania na wersji 2026-10.

Dodatkowe kontrole, takie jak dokumentowanie właścicieli lub przegląd pól legacy, są przydatnymi dobrymi praktykami, ale nie stanowią nowych wymagań wprowadzonych przez tę wersję API.

Lista kontrolna QA dla Shopify Metafields

Skorzystaj z tej skróconej listy kontrolnej przed aktualizacją objętych zmianą integracji:

• Znajdź zapytania GraphQL Admin API, które filtrują po metafields.
• Zapisz owner type, namespace, key i typ każdego metafield objętego zmianą.
• Potwierdź, że każdy filtrowany metafield ma definicję.
• Zweryfikuj, że definicja pozwala na filtrowanie.
• Potwierdź, że typ metafield obsługuje używany filtr lub porównanie.
• Popraw nieprawidłowe filtry metafields.
• Przetestuj objęte zmianą zapytania na API 2026-10.
• Potwierdź, że po filtrowaniu zwracane są oczekiwane zasoby.
• Osobno przejrzyj odpowiednie zależności związane z Customer Account API.
• Udokumentuj właścicieli metafields tam, gdzie z tego samego pola korzysta wiele systemów.
• Przed zmianami w schemacie przejrzyj starsze lub zduplikowane pola niestandardowe.

Podsumowanie

Shopify API 2026-10 zaostrza zasady filtrowania metafields, dlatego to dobry moment, aby przejrzeć dane niestandardowe, od których zależą Twoje aplikacje i integracje.

Przed aktualizacją upewnij się, że filtrowane metafields mają prawidłowe definicje, wymagane możliwości filtrowania są włączone, a objęte zmianą zapytania GraphQL zostały przetestowane względem nowej wersji API. Krótki audyt metafields już teraz może pomóc uniknąć niepotrzebnych błędów, gdy wersja 2026-10 wejdzie w życie 1 października 2026 roku.