Summary
The storeCreditAccountCredit and storeCreditAccountDebit mutations currently have no way to attach a human-readable reason or label to a transaction. We’d like a note (or description) field on the transaction input so that apps can record why a store credit was issued or debited — and have that label surface on the transaction record itself.
Problem
When an app issues store credit programmatically — for example, as compensation for a return or a damaged item — the resulting transaction appears in the customer’s store credit history with no context. There is no field to write something like:
“Compensation for Order #1234 — damaged item”
As a result:
-
Merchants have no audit trail to explain individual transactions without cross-referencing an external system.
-
Support teams cannot tell at a glance whether a credit came from a return compensation, a manual goodwill adjustment, or a third-party integration.
-
Customers who see their transaction history in Customer Account pages are left with unexplained balance changes.
The current transaction object returned by the API exposes id, amount, balanceAfterTransaction, createdAt, and expiresAt, but no freeform label field.
Use Case (Concrete Example)
Consider an app that issues store credit as compensation when a customer reports a damaged or missing item. The app calls storeCreditAccountCredit after verifying the claim, but the resulting transaction record contains no indication of why the credit was issued.
Today, there is no way to attach a note such as "Compensation for Order #1234 — damaged item" to the transaction itself. The app must maintain an external mapping (e.g., in its own database) to trace a transaction back to the originating order and claim.
This means:
-
Merchants must use our admin UI to trace a transaction back to an order — they cannot see it in native Shopify reports.
-
If our app is uninstalled, the mapping is lost and transactions are permanently unexplained.
A note field would make the transaction self-describing and eliminate the need for this external mapping.
Proposed Change
Add an optional note string field to both mutation inputs and the transaction response type:
# Input
input StoreCreditAccountCreditInput {
creditAmount: MoneyInput!
expiresAt: DateTime
notify: Boolean
note: String # ← new
}
input StoreCreditAccountDebitInput {
debitAmount: MoneyInput!
note: String # ← new
}
# Transaction type
type StoreCreditAccountTransaction {
id: ID!
account: StoreCreditAccount!
amount: MoneyV2!
balanceAfterTransaction: MoneyV2!
createdAt: DateTime!
expiresAt: DateTime
note: String # ← new, nullable
}
Prior Art
Several other Shopify APIs already attach human-readable context to balance-related operations:
giftCardCreate — GiftCardCreateInput.note / GiftCard.note
(docs)
refundCreate — RefundInput.note / Refund.note
(docs)
Impact
This is a relatively small, non-breaking addition that would benefit any app that issues store credit programmatically, including loyalty programs, campaign reward apps, and return/exchange automation tools.