Executive summary
- What: As of GraphQL Admin API 2027-01, store credit credit and debit inputs accept an optional note, and StoreCreditAccountTransaction returns it.
- Why: Store credit ledgers have always recorded the amount and the time but not the reason, which pushes the reason into a spreadsheet or a support ticket nobody can find at reconciliation.
- Who: Teams whose apps or middleware issue store credit for returns, goodwill, or loyalty, and the finance people who reconcile it.
What changed
StoreCreditAccountCreditInput and StoreCreditAccountDebitInput now accept an optional note string. On the read side, StoreCreditAccountTransaction.note returns the stored value for credit, debit, and debit revert transactions, or null when no note was set. Expiration transactions always return null, which makes sense given no operator initiates them.
Three constraints shape how you should use this. Notes are capped at 5,000 characters, and a longer note returns a NOTE_TOO_LONG user error without creating the transaction, so validate before you send. Notes are merchant facing only and are never shown to the customer. And a note can be set at creation but not edited afterwards, which makes the field an immutable audit record rather than a working comment thread. Existing read and write store credit account transaction scopes still apply, and nothing is required of integrations that ignore the field.
Why it matters
Store credit tends to start as a returns convenience and quietly become a liability line. Once the balance is material, finance asks the question that store credit systems are usually worst at answering: what was this for. Without a reason on the transaction, the answer lives in whatever system issued it, and correlating a ledger movement to a support ticket by timestamp is slow and unreliable.
Writing the reason at the point of issue fixes that at the source rather than in reporting. The practical payoff shows up in two places: month end reconciliation stops being archaeology, and disputes about whether a credit was authorised become answerable. This is the same discipline that keeps ledger data trustworthy when it crosses into a finance system, a theme we cover in our piece on connecting Shopify Plus financials without the drift.
Role-specific impact
- Marketers: If you issue store credit as a retention or win back incentive, tag the campaign in the note. It lets finance separate promotional credit from returns credit without you building a parallel report.
- Developers: Add note to your credit and debit mutations and enforce the 5,000 character limit client side. Decide on a structured convention now, because you cannot edit a note later and inconsistent free text ages badly.
- Store admins: Expect fewer requests to explain historical credit movements, provided whoever issues credit actually writes a useful reason rather than a single word.
Use-case example
Real-world scenario
A Plus merchant carrying roughly 180,000 dollars in outstanding store credit issued it from three places: the returns app, a customer service macro, and a quarterly goodwill process run by a manager. At each close, finance spent most of a day attributing a few hundred movements to a category, and about 12% stayed unclassified. Writing a note at issue with a short prefix per source, such as RET, CS, or GW, plus the originating reference, moved that attribution to zero manual effort and made the unclassified bucket a genuine exception rather than a standing allowance.
Implementation checklist
- List every system and process that currently credits or debits store credit accounts.
- Agree a note convention with finance before you write code, covering source, reference, and who authorised it.
- Move the relevant app or middleware to GraphQL Admin API version 2027-01.
- Include note in storeCreditAccountCredit and storeCreditAccountDebit calls, validating length before sending.
- Select note when reading StoreCreditAccountTransaction and surface it in your internal reporting.
- Test in a development store by creating a transaction with a note and confirming the response returns the expected string.
FAQ
Q: Can a customer see the note we write?
A: No. Notes are merchant only and are not exposed to the customer, so they are safe for internal references and authorisation detail. Treat them as internal records rather than customer communication.
Q: Can we correct a note that was written incorrectly?
A: No. Notes are set at transaction creation and cannot be edited, which is why agreeing a convention before rollout matters more here than it would for an ordinary editable field.
Resources
storeCreditAccountCredit mutation reference
Need guidance? Talk to Makro.