Refunding an order before the capture via GraphQL

Retired Boards Appdev Graphql Basics And Troubleshooting
, , ,

Topic summary

Implementing manual payment capture and handling pre-capture refunds in Shopify via GraphQL.

  • Order cancellation: Cancelling an order automatically voids the payment authorization and cannot be reversed; the customer must place a new order. Use the OrderCancel mutation (Admin GraphQL API).

  • Partial refund before capture: Capture only the desired amount by setting OrderCaptureInput.amount to the adjusted charge (e.g., after a coupon). The remaining authorized, un-captured amount will be released either automatically or when the authorization period ends (typically ~7 days), subject to the payment gateway’s rules (including multiple captures policies).

  • Key terms: “Authorization” is the hold placed on funds; “Capture” is the actual collection of funds; “Void” releases the authorization.

  • References: Admin GraphQL mutations (orderCancel) and input objects (OrderCaptureInput.amount), plus Shopify Help Center guidance on getting paid.

Status: Clear guidance provided; actionable next steps identified. No conflicting viewpoints raised.

Summarized with AI on January 3. AI used: gpt-5.
1

Hello,

I am looking at implementing the manual capture payment capture method and am wondering how this would impact creating refunds before the capture. A couple scenarios would be an order is cancelled, or a customer would like a partial refund from a coupon code they found after placing their order.

Currently we are capturing payment at the time of sale, so creating a refund against that sale is the standard procedure, however I am unsure of how this would look pre-capture and could use some insight before migrating over to the manual capture.

Thanks!

Jeremiah

2

Hey @JeremiahClaspel ! That’s a great question.

In the scenarios you mentioned,

  1. If an order is cancelled, the authorization is automatically voided, so in that scenario, the customer would need to make a new purchase as cancelling an order can’t be reversed. Relevant mutation if you’re wanting to cancel via API https://shopify.dev/docs/api/admin-graphql/2024-01/mutations/orderCancel

  2. For orders where you have not yet captured the amount, and the customer is requesting a refund for a coupon code they found, then you just need to specify the amount you want to capture in your request. The remaining un-captured authorized amount (depending on the gateway and it’s rules around multiple captures), will either be returned automatically, or returned once the authorization period ends (typically 7 days). https://shopify.dev/docs/api/admin-graphql/2024-01/input-objects/OrderCaptureInput#field-ordercaptureinput-amount

There’s a little more context in the help center here as well: https://help.shopify.com/en/manual/orders/get-paid

Hope that helps!

  • Kyle G.