Idempotency key for store credit update APIs

GraphQL Admin API Troubleshooting
1

Looks like there is an oversight by shopify for not supporting Idempotency key for store credit update transactions which will result in double adding or double debiting, will it be added to the API in the future? storeCreditAccountCredit - GraphQL Admin

2

Hi @Andrew_Jaanuu

Is the storeCreditAccount API called through a webhook? Can verify the webhook_id to avoid duplicate calls

3

Hi @Andrew_Jaanuu

Can you describe your use case more for having this available?

4

@Liam-Shopify @kyle_liu the basic use case of graphql to add or remove store credit, since store credit is like some payment method, there should be idempotency key on the request to prevent credit being added or removed twice because of duplicate requests:

mutation storeCreditAccountCredit($id: ID!, $creditInput: StoreCreditAccountCreditInput!) {
  storeCreditAccountCredit(id: $id, creditInput: $creditInput) {
    storeCreditAccountTransaction {
      amount {
        amount
        currencyCode
      }
      account {
        id
        balance {
          amount
          currencyCode
        }
      }
    }
    userErrors {
      message
      field
    }
  }
}
5

I would second this, we recently had a flow creating store credit via a graphQL call. There was a case where the flow executed twice for the same triggering event (confirmed as a bugged execution by Shopify support). This resulted in a duplication of store credit for a customer account.

An idempotency key would have prevented this for us

7

is there any update for shopify 2026 graphql api for this? I saw a documentation about Idempotent requests but it is not specific about which api supports.

8

Hey @Andrew_Jaanuu, the 2026-01 changelog has some information regarding the mutations the idempotency directive is available on: Adding idempotency for inventory adjustments and refund mutations - Shopify developer changelog

However the changes seem to not yet be fully rolled out: Idempotency directive not required or preventing duplicate inventoryAdjustQuantities requests

The idempotency docs you referenced state that the individual mutation pages in the docs will specify if the mutation supports the directive. I don’t see anything on the store credit mutations currently

9

Hi @Liam-Shopify , I’d like to add another concrete use case for idempotency on storeCreditAccountCredit and storeCreditAccountDebit.

We are building a store credit campaign feature for merchants. The app automatically credits customers based on order lifecycle events, such as order creation, payment, or fulfillment, and it also needs to debit or reverse store credit when refunds or full reversals happen. We also plan to support Flow-based workflows around these store credit operations.

The challenge is that these mutations change a financial balance, but there is currently no app-provided idempotency key or external reference that can be attached to the resulting Store Credit transaction.

Webhook deduplication only solves one layer of the problem. The unsafe retry can happen after our app has already decided to perform one logical credit or debit operation: task retries, Admin API timeouts, connection resets, HTTP 5xx responses, lost responses, Flow retries, or app crashes after the mutation was sent but before the returned transaction ID was persisted.

Without API-level idempotency, the app has two bad choices:

  • retry the mutation and risk duplicate customer credit or duplicate debit
  • avoid retrying and move the operation into manual reconciliation because the result is unknown

For a financial operation, the second option is safer, but it creates unnecessary operational complexity for merchants and app developers.

What would help us is support for either:

  • an idempotencyKey field on StoreCreditAccountCreditInput and StoreCreditAccountDebitInput, or
  • the Admin GraphQL @idempotent directive on storeCreditAccountCredit and storeCreditAccountDebit

Ideally, duplicate requests with the same key would return the original StoreCreditAccountTransaction, and requests with the same key but different parameters would fail with a parameter mismatch error.

Store credit is similar to refunds, inventory adjustments, and billing attempts in this regard: duplicate execution creates merchant-facing financial discrepancies. Platform-level idempotency would let apps safely retry after network or response failures without risking duplicate balance changes.