Returns Processing API - how do you refund to a gift card?

GraphQL Admin API Troubleshooting
1

Using returnProcess (the current Returns Processing API), I can’t find a way to issue a refund to a gift card. The input only seems to allow two outcomes:

input ReturnProcessRefundInput {                                                                                                                                                                                                                                                                                           
    orderTransactions: [ReturnRefundOrderTransactionInput!]!   # parentId is required — ties it to the original tender                                                                                                                                                                                                       
    refundMethods: [RefundMethodInput!]                        # only member is storeCreditRefund                                                                                                                                                                                                                            
  }

So a refund either goes back through the original payment, or to store credit. No gift card option, same in 2025-07, 2026-01 and 2026-04

Use Case: A POS exchange on a cash order, where the customer received a gift card as the exchange item. We then need to refund one more line onto that same card.

What I have trie:

  • returnProcess with orderTransactions: [ ] - creates a $0 refund record linked to the return. The line is marked refunded but no money moves, and the order is left showing the value as still owe
  • returnProcess with the cash SALE as parentId - order balances, but records a cash refund that never happened
  • refundCreate with gateway: “gift_card” - rejected without a parentId; with exchange-credit it succeeded but Shopify rewrote the gateway to cash
  • giftCardCredit - puts money on the right card, but creates no refund, so the order still shows the amount owed
  • An exchangeLineItems gift card variant with a fixed appliedDiscount - the line showed the discounted price, but the issued card was minted at the variant’s face value

Question: Is there a supported way to direct a refund to a specific existing gift card? If not, is a gift card member of RefundMethodInput planned, and what’s the recommended pattern in the meantime?

2

A gift card can receive a refund through returnProcess if it was an original payment method. In the example shared, the original tender was cash, so there isn’t currently a supported way to direct the refund to a gift card or link a giftCardCredit adjustment to the return.

For cash orders, a possible workaround is to process the return against the original cash transaction and then add the equivalent value using giftCardCredit. This records a cash refund and a separate gift card adjustment, so reporting won’t reflect the actual movement of value.

Regarding whether adding gift card support to RefundMethodInput is planned, we’re not able to share roadmap details at this time.

3

Thanks.
One correction: the cash tender in my example was incidental. The gift card we need to refund onto was issued by the exchange itself, so it was never a payment method on the order. The same applies on a card-tendered order, the customer ends up holding a gift card Shopify created, and the returns API can’t put anything on it.

On the suggested workaround: processing against the original transaction and then adding giftCardCredit books a cash refund that never happened, so it isn’t something we can use..

A narrower question about the exchange path instead.

ExchangeLineItemInput has a giftCardCodes field, documented as “the gift card codes associated with the physical gift cards”. But no query returns a gift card’s code - GiftCard exposes only maskedCode and lastCharacters - so the field only works for a physical card whose code you already have, never for one Shopify created.

Could the exchange input accept a gift card ID instead - giftCardIds: [ID!], or a GID in the existing field?
That would let the API do what POS does: put exchange value on a specific existing card, with the order balanced and the return associated. GiftCard.order already records which order a card came from.

4

Exactly. Refunds can only be issued to an original payment method or store credit, regardless of which original payment method was used.

That’s fair. The cash workaround was offered only as a possible workaround, not a complete solution. Because it records a cash refund that didn’t occur and a separate gift card adjustment, it won’t suit many merchants’ accounting requirements.

For the exchange input specifically, giftCardCodes doesn’t accept GiftCard GIDs, and there isn’t a giftCardIds option today. I can see how the ability to refund to gift cards would be useful for many merchants, so I have submitted a feature request on your behalf. Due to the nature of feature requests, we’re not able to confirm whether or when this might be implemented.