See all services → Shopify Plus Partner
API Developer

Record why you issued store credit with merchant notes

GraphQL Admin API 2027-01 lets you attach an optional merchant-only note when crediting or debiting a store credit account, and read it back on the transaction. Notes are capped at 5,000 characters and cannot be edited after the fact.

Executive summary

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

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

  1. List every system and process that currently credits or debits store credit accounts.
  2. Agree a note convention with finance before you write code, covering source, reference, and who authorised it.
  3. Move the relevant app or middleware to GraphQL Admin API version 2027-01.
  4. Include note in storeCreditAccountCredit and storeCreditAccountDebit calls, validating length before sending.
  5. Select note when reading StoreCreditAccountTransaction and surface it in your internal reporting.
  6. 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.