Gift card webhooks — do gift_cards/create and gift_cards/update exist? Looking for the right pattern to sync balances to an external POS

Technical Q&A
1

We are building an integration that connects a Shopify store to an external POS / ERP system. The flow we want is:

  1. Customer buys a gift_card: true product on the Shopify storefront. Shopify issues the GiftCard natively (emails the code, lists it under Products → Gift cards). :white_check_mark: already working
  2. Our app mirrors the issued balance into the external POS so the same code can be redeemed at the physical store.
  3. Whenever the balance changes — customer redeems at Shopify checkout, admin manually adjusts, or another channel debits — we want to push the new balance to the POS so the two sides stay in sync.
  4. Reverse direction: when the customer redeems part of the balance at the physical POS, we call giftCardDebit on the Shopify side so the storefront balance reflects the spend.

We assumed the loop would be closed by two webhook topics:

  • gift_cards/create (fired when Shopify issues a gift card)
  • gift_cards/update (fired when the balance changes)

But when we try to subscribe via the Admin REST API and the GraphQL webhookSubscriptionCreate mutation, Shopify rejects both:

REST (POST /admin/api/2024-10/webhooks.json with topic: "gift_cards/create"):

422 Unprocessable Entity
"Invalid topic specified: gift_cards/create. Does it exist?
Is there a missing access scope?"

GraphQL (webhookSubscriptionCreate with topic: GIFT_CARDS_CREATE):

INVALID_VARIABLE — Expected "GIFT_CARDS_CREATE" to be one of [list of valid topics]

Neither GIFT_CARDS_CREATE nor GIFT_CARDS_UPDATE appears in the WebhookSubscriptionTopic enum returned by the API. Yet some community threads and at least one Shopify-side AI assistant mention them — leading us to believe they may have existed at some point, or are planned, or are exclusive to a specific tier.

Our questions:

  1. Are gift_cards/create / gift_cards/update webhook topics supposed to exist on the current Admin API? If yes, in which API version, under which scopes?
  2. If they do not exist, what is the recommended pattern for keeping a Shopify-issued gift card balance in sync with an external system?
  3. Is the right approach a combination of:
    • Detecting issuance from orders/paid (line item gift_card: true) and then reading the resulting GiftCard via giftCards(query: "order_id:X")
    • Detecting redemptions from the gift_cards array embedded in the orders/paid payload
    • Polling giftCards(query: "updated_at:>...") on a schedule for everything else (admin adjustments, manual disables, etc.)?
  4. For the reverse direction (POS-initiated debit), giftCardDebit works for us with write_gift_card_transactions. Is there any planned way for our system to be informed by Shopify when our own debit is processed, other than getting it back through the queried balance?

Our app already has all gift-card-related scopes granted (read_gift_cards, write_gift_cards, read_gift_card_transactions, write_gift_card_transactions). The store is a Dev/Partners store.

Any guidance from someone who has implemented this — or from Shopify staff — would be hugely appreciated.

Thanks!

2

Yeah gift_cards/create and gift_cards/update are both real webhook topics, and gift_cards/update is the one you want since it fires when the balance moves (checkout redemption, manual admin adjust).

One thing that bit me building a similar sync: treat the webhook as a “go re-read” signal, not the source of truth. They can arrive out of order or get collapsed when a card gets debited a few times in quick succession, so on each one I’d query the gift card back via GraphQL (giftCard(id)) and push that authoritative balance to the POS rather than trusting the amount in the payload.

Worth confirming the gift card webhook + API surface is available on your plan too, parts of it have been Plus-gated historically. Is the POS ever allowed to be source of truth for balance, or is Shopify always the master?