Shopify a introdus câmpul countryCode în Customer Address API, începând cu versiunea 2026-10, iar vechiul territoryCode este marcat ca deprecat, dar funcționează în continuare. Pentru magazinele care citesc sau scriu adrese de client prin API, asta înseamnă o migrare de cod simplă, fără întreruperi pentru integrările vechi, conform anunțului din changelogul Shopify.

Ce s-a schimbat concret în Customer Address API

Pe scurt: obiectul de input CustomerAddressInput și obiectul CustomerAddress includ acum câmpul countryCode. El folosește enumul CountryCode și acceptă coduri ISO 3166-1 alpha-2, de tipul US sau CA. Vechiul câmp territoryCode este marcat ca deprecat în versiunea 2026-10, dar nu a fost eliminat. Interogările și mutațiile care îl folosesc merg în continuare, inclusiv cele care rulează pe versiuni mai vechi de API. Dacă trimiți ambele câmpuri într-un input de adresă, countryCode are prioritate.

Asta e tot ce spune sursa la nivel de fapte. Restul e interpretare și decizie de business, pe care o tratăm separat mai jos.

Un detaliu care merită subliniat: Shopify nu a anunțat nicio versiune în care territoryCode va fi eliminat. Deci nu vorbim despre o urgență, ci despre o curățenie de cod pe care o faci când oricum atingi versiunea 2026-10. Cine rămâne pe 2026-07 sau mai devreme nu e afectat deloc.

De ce contează alinierea la ISO 3166-1 alpha-2

Motivul din spate e coerența. Restul API-urilor Shopify folosesc deja terminologia de country code și un enum puternic tipizat pentru țări. Customer Address API rămăsese cu un termen diferit, territoryCode, care amesteca noțiunile de țară și teritoriu. Rezultatul era o zonă gri de interpretare: ce valoare trimiți de fapt, un cod de țară, un cod de regiune, un teritoriu?

Din perspectiva unui operator de ecommerce, ambiguitatea asta se transformă în bug-uri silențioase. O adresă cu țara greșit formatată poate ajunge într-un câmp pe care tool-ul de facturare nu îl citește, poate rupe un export către un ERP, poate strica un feed de shipping. Nu sunt erori care apar în log-uri zgomotos. Sunt erori care ies la iveală abia când un client din altă țară încearcă să finalizeze o comandă sau când reconciliezi rapoartele de taxe.

Un enum tipizat cu valori ISO 3166-1 alpha-2 reduce exact acest tip de problemă. Ai o singură formă acceptată, două litere, iar inputul devine previzibil. Pentru echipele care lucrează cu mai multe piețe, asta e diferența dintre un câmp pe care te poți baza și un câmp pe care îl validezi manual la fiecare integrare.

Ce verifici în codul tău înainte să migrezi

Atenție la capcană: valori de tipul USA sau 840 nu sunt acceptate. Sursa e explicită, countryCode cere ISO 3166-1 alpha-2. Dacă integrarea ta actuală trimite coduri alpha-3 sau numerice prin territoryCode, trecerea la countryCode le va respinge. Deci nu e o simplă redenumire de câmp. E o redenumire plus o normalizare de valori.

Iată o listă de lucru, propusă de noi, nu preluată din sursă:

  1. Caută în cod toate aparițiile territoryCode în interogări și mutații de adrese de client.
  2. Verifică ce format de valoare trimiți acum. Dacă ai alpha-3 sau numeric, ai de lucru la normalizare, nu doar la numele câmpului.
  3. Înlocuiește cu countryCode acolo unde adaugi versiunea 2026-10.
  4. Testează crearea, actualizarea și citirea unei adrese de client pe versiunea nouă.
  5. Rulează un test separat pentru cazul în care trimiți ambele câmpuri, ca să confirmi că prioritatea countryCode se comportă cum te aștepți.
  6. Verifică dacă vreun export, webhook sau job de sincronizare depinde de numele vechi al câmpului în downstream.

Punctul 6 e cel pe care îl ratăm cel mai des. Chiar dacă API-ul acceptă ambele câmpuri, sistemele din aval (ERP, CRM, tool de facturare) pot fi configurate pe un nume de câmp care nu se mai potrivește cu ce primești. Aici nu vorbim despre o funcție nouă care lipsește, ci despre o verificare de integrare pe care un audit automat nu o poate face singur. O verificare incompletă nu dovedește că ceva e stricat. Doar semnalează unde trebuie să te uiți.

Limite și scenarii ipotetice

Ce nu știm din sursă și nu trebuie să presupunem: dacă și când va fi eliminat territoryCode, dacă vor exista schimbări conexe în alte obiecte de adresă, dacă valoarea deprecării va produce avertismente în loguri sau în tooling-ul de dezvoltare. Nimic din anunț nu confirmă aceste lucruri.

Aici intervine disciplina de operare. Separăm ce e măsurat de ce e ipoteză.

Ce e fapt, din sursă: countryCode există din 2026-10, territoryCode e deprecat dar funcțional, countryCode are prioritate la conflict.

Ce e ipoteză, a noastră: dacă istoricul Shopify ne învață ceva, este că deprecările de câmp durează mult și că eliminarea vine doar când apare o versiune nouă de API care le scoate din schemă. Nu avem confirmare pentru un termen. Deci orice planificare cu dată fixă ar fi inventată.

Ce putem face corect: să programăm migrarea odată cu următoarea actualizare de versiune API, nu separat, pentru a nu dubla munca de testare. Și să tratăm normalizarea valorilor ca pe un task separat de redenumirea câmpului, pentru că acolo e riscul real de eroare.

Ce înseamnă pentru tine, antreprenor sau marketer în România

Pentru majoritatea magazinelor românești care vând pe Shopify, schimbarea asta nu se simte direct. Dacă folosești o temă standard și aplicații din App Store, ele sunt cele care ating API-ul, nu tu. Tu vezi efectul final, adresa clientului.

Dar există două situații în care te privește direct.

Prima: ai o aplicație proprie sau o integrare custom care scrie adrese de client prin Customer Account API. Atunci ai cod de migrat, indiferent de mărimea magazinului. Aici recomandarea noastră e clară, pune pe listă verificarea câmpului înainte să sari pe versiunea 2026-10.

A doua: lucrezi cu mai multe piețe și ai rapoarte de taxe, shipping sau segmentare pe țară. Dacă vreunul dintre aceste rapoarte se bazează pe un câmp de adresă care își schimbă numele, verifică dacă maparea de coloane din raport mai e validă. Nu presupune că se rupe. Verifică.

Pentru un marketer care lucrează cu audiențe bazate pe țară, implicația e indirectă, dar reală. Datele de adresă curate înseamnă segmentări mai puțin zgomotoase. Un client cu țara corect formatată intră în audiența corectă. Unul cu un cod de țară scris greșit intră în cea greșită, sau nu intră deloc. Diferența nu se vede în dashboard până nu compari cu realitatea.

FAQ

Trebuie să schimb ceva urgent dacă magazinul meu rulează pe o versiune mai veche de API?

Nu. Sursa confirmă explicit că aplicațiile pe versiunea 2026-07 sau mai devreme rămân neschimbate și pot folosi în continuare territoryCode. Nu există întrerupere imediată și nu a fost anunțată o versiune de eliminare.

Ce se întâmplă dacă trimit atât countryCode, cât și territoryCode în același input?

countryCode are prioritate. Așa e specificat în anunț. Dacă trimiți ambele din inerție, rezultatul va reflecta countryCode, deci asigură-te că valoarea de acolo e cea corectă.

Ce format de valoare acceptă countryCode?

Coduri ISO 3166-1 alpha-2, adică două litere, de tipul US sau CA. Nu alpha-3 și nu coduri numerice. Dacă integrarea ta produce alt format, ai nevoie de o normalizare, nu doar de o schimbare de nume de câmp.

Unde se termină automatizarea și unde începi tu

Un asistent AI poate face bine câteva lucruri aici: să scaneze codul după aparițiile lui territoryCode, să propună înlocuirile, să genereze lista de teste, să compare valorile trimise cu formatul ISO cerut. Asta economisește timp real de căutare.

Ce nu poate face AI-ul: să decidă dacă migrarea intră în sprintul curent, să valideze că exportul din ERP respectă noul nume de câmp, să confirme că un test a trecut pe mediul tău real de producție. Decizia și execuția rămân umane, iar media buyer-ul sau developerul care atinge efectiv integrarea e cel care semnează că e corect. Un audit automat care nu găsește nimic nu dovedește că totul e în regulă, doar că nu a găsit încă.

Dacă vinzi pe Shopify și vrei să treci prin această verificare fără să pierzi vânzări pe drum, pasul concret îl face ALLSoft Agency. Fără hype, cu listă de verificat și testare pe mediul tău.