Shopify just rolled out a handy addition to its Store Credit API. Starting with GraphQL Admin API version 2027-01, merchants can attach a private note to every credit, debit, or debit‑revert transaction. The note stays invisible to customers, but it’s instantly readable via the API, making it easier to track refunds, adjustments, or internal accounting details directly within the platform.
What Changed
StoreCreditAccountCreditInput and StoreCreditAccountDebitInput now accept an optional note string.StoreCreditAccountTransaction.note returns the stored note for credit, debit, and debit‑revert transactions (null for expiration transactions).NOTE_TOO_LONG user error and the transaction isn’t created.read_store_credit_account_transactions and write_store_credit_account_transactions scopes remain sufficient.Who Is Affected
The update is relevant for any app—or custom integration—that manages store credit via the GraphQL Admin API. Only versions 2027-01 and newer expose the note fields; earlier versions (2026-10 and before) will ignore them. Both developers building apps and merchants using third‑party credit apps should be aware of the new capability, though no immediate code changes are required for existing functionality.
How to Implement Notes in Your App
2027-01 (or later).note in your query to retrieve it.Here’s a minimal example for a credit transaction with a note:
`mutation {
storeCreditAccountCredit(
input: {
storeCreditAccountId: "gid://shopify/StoreCreditAccount/123456789",
amount: "50.00",
note: "Refund for order #1001 – product out of stock"
}
) {
storeCreditAccountTransaction {
id
note
}
}
}`
If the note exceeds 5,000 characters, the API will return a NOTE_TOO_LONG error, so you may want to validate length client‑side before sending the request.
Testing and Verifying
note field appears in the returned StoreCreditAccountTransaction object.NOTE_TOO_LONG user error.By following these steps, you’ll guarantee that the new note functionality works smoothly before rolling it out to production.
Key Takeaways
note field provides internal context for merchants.NOTE_TOO_LONG errors.Conclusion & Next Steps
Adding merchant notes to store credit transactions is a low‑effort win for anyone managing refunds, promotions, or internal adjustments. Update your app to target the 2027-01 API, start attaching meaningful notes, and give merchants the audit trail they need—without exposing any extra data to shoppers. Need help upgrading your integration? Reach out to our developer support or drop a comment below, and we’ll walk you through the change.
