Merchant notes on store credit transactions

As of GraphQL Admin API version 2027-01, you can attach a merchant-only note when crediting or debiting a store credit account and read those notes on store credit transactions. Notes are optional, so existing integrations continue to work without changes or required updates.

What changed

• StoreCreditAccountCreditInput and StoreCreditAccountDebitInput accept an optional note string.
• StoreCreditAccountTransaction.note returns the stored note for credit, debit, and debit-revert transactions, or null when no note is set. Expiration transactions always return null.
• Notes support up to 5,000 characters. Longer notes return a NOTE_TOO_LONG user error and the API doesn’t create the transaction.
• Notes are for merchants only and aren't visible to customers. You can set a note when you create a transaction, but you can’t edit a note on an existing transaction.

Who's affected

This change applies to apps that manage store credit using GraphQL Admin API version 2027-01 or later. Versions 2026-10 and earlier don’t expose these fields.

Existing read_store_credit_account_transactions and write_store_credit_account_transactions access scopes and permission requirements still apply. No new scope is required.

What to do

You don’t need to change existing integrations. To start using notes:

1. Target GraphQL Admin API version 2027-01 or later in your app.
2. When you create a credit or debit, include note in the input.
3. Select note on the returned StoreCreditAccountTransaction to read the stored value.
4. Test in a dev store by creating a transaction with a note and verifying that the response includes the expected note string.

Related docs

• storeCreditAccountCredit mutation reference
• storeCreditAccountDebit mutation reference