Din versiunea GraphQL Admin API 2027-01, Shopify permite atașarea unei note interne, vizibile doar pentru comerciant, la creditarea sau debitarea unui cont de store credit. Câmpul e opțional, deci integrările existente funcționează neschimbate. Notele se citesc pe tranzacție, au maximum 5.000 de caractere și nu pot fi editate ulterior. Sursa: Shopify Changelog.

Subiectul pare tehnic și, la prima vedere, fără legătură cu marketingul. În realitate, store credit-ul este un instrument comercial: rambursări sub formă de credit, compensații pentru clienți nemulțumiți, promoții, programe de loialitate, ajustări manuale făcute de echipa de suport. Fiecare dintre aceste tranzacții are o poveste în spate, iar până acum povestea trăia în afara sistemului: în emailuri, în ticket-uri, în capul celui care a făcut operațiunea. Noua funcție mută contextul direct pe tranzacție, acolo unde îl caută contabilitatea, suportul și, uneori, marketingul.

Ce s-a schimbat concret în API

Pe scurt, două input-uri acceptă acum un câmp opțional de tip text: StoreCreditAccountCreditInput și StoreCreditAccountDebitInput. Pe partea de citire, StoreCreditAccountTransaction expune câmpul note, care returnează textul salvat pentru tranzacțiile de credit, debit și debit-revert. Tranzacțiile de expirare returnează mereu null.

Limita este de 5.000 de caractere. Peste acest prag, API-ul returnează o eroare de tip NOTE_TOO_LONG și nu creează tranzacția, ceea ce e un comportament corect: mai bine blochezi operațiunea decât să trunchiezi silent o notă care poate conta. Notele sunt doar pentru comerciant, nu sunt vizibile clienților. Se pot seta la crearea tranzacției, dar nu se pot edita pe o tranzacție existentă.

Aplicabilitatea este clar delimitată: funcția vizează aplicațiile care administrează store credit prin GraphQL Admin API versiunea 2027-01 sau mai nouă. Versiunile 2026-10 și anterioare nu expun aceste câmpuri. Scopurile de acces existente, read_store_credit_account_transactions și write_store_credit_account_transactions, rămân valabile, fără cerințe suplimentare de permisiuni.

Pentru echipele care nu fac integrare proprie, ci folosesc aplicații terțe, mesajul e simplu: integrarea ta nu se strică. Notele apar doar dacă aplicația pe care o folosești decide să le implementeze și să țintească versiunea nouă de API. Nu presupune că funcția e disponibilă în aplicația ta doar pentru că Shopify a publicat schimbarea.

De ce contează pentru marketing și pentru operațiuni

Store credit-ul este adesea tratat ca un detaliu contabil. În practică, el atinge direct experiența clientului și, implicit, percepția asupra brandului. Un client care primește un credit în locul unei rambursări are nevoie de claritate: de ce a primit creditul, cât e valabil, în ce condiții. O notă internă bine scrisă rezolvă jumătate din problema asta la sursă, pentru că următorul operator care deschide tranzacția vede imediat contextul.

Există trei zone în care notele schimbă jocul:

Prima, suportul clienți. Când un agent deschide contul unui client și vede o tranzacție fără explicație, are două opțiuni: caută în istoricul de ticket-uri sau întreabă un coleg. Ambele costă timp. O notă de tipul „credit acordat ca gest comercial pentru comanda întârziată, aprobat de supervisor" elimină căutarea.

A doua, reconcilierea financiară. La sfârșit de lună, cineva trebuie să explice de ce au apărut o serie de credite. Fără note, explicația vine din memorie sau din foi de calcul paralele. Cu note, tranzacția poartă propria justificare.

A treia, marketingul promoțional. Campaniile care oferă credit în loc de discount au nevoie de urmărire. Dacă fiecare credit acordat în cadrul unei campanii poartă o notă cu identificatorul campaniei, ai o pistă de audit pe care o poți corela ulterior cu datele din analytics. Nu înlocuiește un sistem de atribuire, dar îți dă un fir logic acolo unde înainte nu exista nimic.

Aici merită o precizare de metodă, ca să nu transformăm o funcție de API într-o promisiune de performanță. Notele sunt un instrument de documentare, nu de măsurare. Faptul că poți scrie „campania X" pe o tranzacție nu înseamnă că ai rezolvat atribuirea. Înseamnă doar că ai redus zona gri dintre ce s-a întâmplat în magazin și ce poți demonstra mai târziu.

Cum arată o implementare sănătoasă

Pentru echipele care au integrare proprie sau lucrează cu un dezvoltator, pașii din documentație sunt simpli: țintește versiunea 2027-01 sau mai nouă, include câmpul note în input la creare, selectează note pe tranzacția returnată, testează într-un magazin de dezvoltare. Recomandarea mea, dincolo de ce spune sursa: nu sări peste testul în dev store și nu te limita la un singur scenariu. Verifică un credit, un debit, un debit-revert și o expirare, ca să vezi exact ce primești în fiecare caz.

Apoi vine partea care ține de proces, nu de cod. Stabilește o convenție de scriere a notelor înainte să lași oamenii să scrie liber. Altfel, în două luni, ai 400 de tranzacții cu texte de genul „ok", „vezi ticket", „rezolvat". O convenție minimă ar putea include motivul operațiunii, sursa aprobării și, unde e cazul, identificatorul campaniei sau al ticket-ului. Nu trebuie să fie rigidă, dar trebuie să fie comună.

Un al doilea lucru de decis: cine are voie să scrie note. Scopurile de acces existente rămân aceleași, deci nu apare o poartă nouă de permisiuni. Asta înseamnă că disciplina trebuie să vină din proces, nu din sistem.

Și un al treilea: ce faci cu notele vechi. Tranzacțiile create înainte de această versiune nu au cum să aibă note, iar notele nu pot fi editate ulterior pe o tranzacție existentă. Dacă ai nevoie de context retroactiv, îl documentezi în altă parte, nu forțezi API-ul să facă ce nu promite.

Limitele funcției, spuse direct

Am văzut destul de des tendința de a citi o schimbare de API ca pe o soluție completă. Aici, limitele sunt clare și merită enumerate.

Notele nu sunt vizibile clienților, deci nu rezolvă comunicarea către client. Dacă vrei ca omul să înțeleagă de ce a primit credit, ai nevoie de email, de pagină de cont sau de alt canal.

Notele nu pot fi editate. O greșeală de scriere rămâne în tranzacție. Asta impune o minimă atenție la momentul creării, nu o corecție ulterioară.

Notele nu înlocuiesc un sistem de evidență contabilă. Sunt context operațional, nu document fiscal.

Și, poate cel mai important, disponibilitatea depinde de aplicația pe care o folosești. Dacă lucrezi cu o aplicație terță care nu a migrat pe versiunea nouă de API, funcția nu există pentru tine, indiferent ce scrie în changelog. Verifică starea reală în aplicația ta înainte să promiți echipei că notele sunt live.

Asta e o distincție pe care o aplicăm constant în auditurile noastre: o verificare incompletă nu dovedește absența unei funcții. Dacă nu găsești câmpul într-un singur loc, nu înseamnă că nu există. Înseamnă că trebuie să verifici sursa corectă, versiunea de API și aplicația care face apelul.

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

Dacă ai un magazin pe Shopify și vinzi în România, cel mai probabil nu ai o integrare proprie de store credit. Folosești o aplicație sau funcționalitatea nativă, iar notele vor apărea la tine doar când furnizorul aplicației le implementează. Primul pas concret nu e tehnic, ci de proces: întreabă furnizorul dacă suportă versiunea 2027-01 și dacă expune notele în interfață. Dacă răspunsul e nu, ai acum un argument clar pentru o discuție de roadmap.

Dacă ai echipă tehnică proprie, schimbarea e mică la nivel de cod, dar poate avea impact operațional mare dacă o integrezi în fluxul de suport. Cel mai frecvent scenariu în magazinele românești: un client cere rambursare, suportul oferă credit în magazin, iar peste două săptămâni nimeni nu mai știe de ce există acel credit. O notă scrisă la momentul creării rezolvă exact această situație.

Pentru marketerul care rulează campanii cu credit în loc de discount, recomandarea mea e să tratezi notele ca pe o pistă de audit internă, nu ca pe un instrument de atribuire. Dacă vrei date curate despre performanța promoțiilor, ai nevoie de analytics și de un sistem de urmărire serios. Notele completează, nu înlocuiesc.

Și, ca regulă generală: nu confunda o schimbare de infrastructură cu o lansare de marketing. Shopify nu a lansat o funcție de marketing, a extins un API. Valoarea apare doar dacă echipa ta decide să o folosească disciplinat.

FAQ

Notele sunt vizibile clienților? Nu. Sunt exclusiv pentru comerciant. Clientul nu vede textul notei nicăieri în experiența sa de cumpărare.

Pot edita o notă după ce am creat tranzacția? Nu. Nota se setează la creare și rămâne neschimbată. Dacă ai greșit, corectezi prin proces, nu prin API.

Ce se întâmplă dacă nota depășește 5.000 de caractere? API-ul returnează eroarea NOTE_TOO_LONG și nu creează tranzacția. Verifică lungimea textului înainte de apel, mai ales dacă notele sunt generate automat.

Trebuie să schimb ceva în integrarea existentă? Nu. Câmpul e opțional, iar scopurile de acces rămân aceleași. Modifici doar dacă vrei să folosești funcția.

AI-ul ajută, dar decizia rămâne umană

Un asistent AI poate face munca pregătitoare: să structureze o convenție de note, să analizeze un eșantion de tranzacții și să semnaleze unde lipsesc explicații, să propună un format standard pentru echipe. Poate chiar să scrie primele drafturi de ghid intern. Ce nu poate face este să decidă ce înseamnă o notă bună pentru businessul tău și cine răspunde pentru ea.

Execuția rămâne la operatorul uman: media buyer-ul, omul de suport, cel care ține reconcilierea. Iar pasul concret, de la „am citit despre asta" la „funcționează în magazinul meu", îl face ALLSoft Agency. Fără promisiuni umflate, fără cifre inventate, cu verificare reală a ce e disponibil în contul tău înainte să construim ceva pe deasupra.