Processing a refund
To process a refund, Shopify makes an HTTP call to your app, and your app completes the refund by replying with a GraphQL mutation. This interaction is illustrated in the following diagram:
- Merchant requests refund.
- Shopify sends a backend request to the payments app, specifying the refund.
- The app replies with a 201 and an empty response body.
- The app finalizes the refund using either RefundSessionResolve or RefundSessionReject mutations.
- Shopify updates the refund status.
- You've completed the Getting started building payments apps.
- You've familiarized yourself with the general transaction requirements.
- To be eligible to build payments apps, you must meet the payments apps requirements.
To use the GraphQL mutations, your app must be aware of access scopes for payments apps.
Initiate the refund flow
The refund flow begins with an HTTP request sent from Shopify to the provider's refund session URL as provided during app extension configuration:
||Unique identifier for the refund attempt. Used as the idempotency key. It can be assumed that requests with a given ID are identical to any previously-received requests with the same ID.||
||Identifies the refund when communicating with Shopify (in GraphQL mutations, for example).||
||ID of the original payment that is to be refunded. For captured payments, this ID corresponds to the original authorization ID rather than the capture ID.||
||Amount to be refunded.||
||Three-letter ISO currency code.||
||IETF BCP 47 language tag representing the language used by the merchant.||
||Timestamp representing when the refund request was proposed.||
Shopify must receive a HTTP 201 response for the refund session creation to be successful.
If the request fails, then it is retried several times. If the request still fails, then the merchant needs to manually retry the refund in the Shopify admin.
Resolve a Refund
After you've successfully processed the refund request, you can resolve it by using the RefundSessionResolve mutation:
id argument corresponds to the
gid of the refund.
Reject a refund
If you cannot process a refund, then you should reject it. You should only reject a refund in the case of final and irrecoverable errors. Otherwise, you can re-attempt to process the refund.
You can reject a refund using the RefundSessionReject mutation:
As part of the rejection, you need to include a reason why the refund was rejected as part of RefundSessionRejectionReasonInput.
RefundSessionRejectionReasonInput.code is a
RefundSessionStatusReasonRejectionCode, which is an enum of standardized error codes.
RefundSessionRejectionReasonInput.merchantMessage argument is a localized error message presented to the merchant explaining why the refund was rejected.
If there's a Shopify service disruption (or if 5xx status codes are being returned), then requests must be retried. It is suggested to follow the guidelines in the retry policy section.