A return needs more than a refund
A customer requests a return. Support approves it, the warehouse receives the parcel, and finance expects the correct refund and stock update.
Connecting those steps is where the Shopify Returns API becomes useful. It gives applications a way to manage return records and related actions inside Shopify.
The implementation still needs clear rules for eligibility, inspection and customer communication. A successful API call only confirms the action covered by that call.
- Shopify's GraphQL Admin API provides operations for return requests, approvals, processing and related logistics.
- A return record and a refund represent different parts of the workflow.
- Applications need to handle item identifiers, permissions, errors and repeated events correctly.
- Claimlane connects post-purchase work across systems, with the exact Shopify workflow checked during implementation.
What is the Shopify Returns API?
"Shopify Returns API" commonly refers to the return-related queries, objects and mutations within Shopify's GraphQL Admin API. A mutation is an operation that changes data, such as creating or approving a return.
The main Return object connects a return to its order and the items involved. Related objects represent exchange items, reverse fulfilment work and return shipments.
Shopify's official returns integration guide explains how those pieces fit together. This article focuses on the Admin API workflow used by connected applications.
Understand the main return operations
The integration should choose an operation based on the stage of the case. Creating a request for review is different from recording a return that has already been approved.
| Operation | Purpose | When it matters |
|---|---|---|
| returnableFulfillments | Find fulfilled items and quantities available for return | Before constructing a return request |
| returnRequest | Create a return that requires approval | When the request still needs review |
| returnApproveRequest | Approve an existing return request | After the reviewer accepts it |
| returnDeclineRequest | Decline an existing return request | After the reviewer rejects it |
| returnCreate | Create an open, already-approved return | When approval happens outside Shopify |
| returnProcess | Process return and exchange quantities, disposition and optional refunds | When the agreed items are ready for processing |
| removeFromReturn | Remove line items from a return | When the agreed scope of the return changes |
| returnCancel | Cancel a return | When the case ends before any items are processed |
| returnClose | Close a return | When the return is finished and needs no further work |
| returnReopen | Reopen a closed return | When a closed case needs further work |
| return | Retrieve an existing return | When checking its current state |
The exact inputs depend on the operation and API version. Production integrations should use the reference for their selected version.
Check returnable items before creating the request
An order line alone isn't enough to identify a returnable item. The application needs the relevant fulfilment information and available quantity.
The returnableFulfillments query provides returnable fulfilments for an order. Its results help the application identify the fulfilment line items needed for the request.
This distinction matters when an order ships in separate parcels or contains repeated quantities of the same product. The integration should preserve Shopify's identifiers instead of matching items by product name.
Technical returnability also doesn't settle the business decision. The application still needs to assess the applicable policy and reason for return.
Choose between returnRequest and returnCreate
Requests that still need approval
Use returnRequest when a customer submits a return that needs review. It creates a return with the REQUESTED status.
The workflow then uses returnApproveRequest or returnDeclineRequest to record the decision.
Returns approved outside Shopify
Use returnCreate when approval has already happened in another system. Shopify creates the return in the OPEN state and creates a reverse fulfilment order.
This operation assumes approval. It shouldn't be used merely because a customer has submitted a form.
For example, a support platform can collect evidence and approve the request before creating the open return in Shopify.
Keep return creation separate from refunding
A return records the intent and work associated with items coming back. A refund records a financial adjustment.
Calling returnCreate doesn't itself issue the customer's refund. The integration needs an explicit financial step at the appropriate point in its workflow.
Shopify provides refundCreate for creating refunds, while returnProcess can optionally issue a refund as part of return processing. The chosen path should match the intended return workflow.
The application must prevent the same refund from being issued through both paths. It should also check transaction results before telling the customer that payment has been returned.
Use returnProcess for the processing stage
The returnProcess mutation confirms quantities for return and exchange items already attached to a return. It also handles disposition and can include a refund.
Shopify introduced return processing in API version 2025-07 and advises existing returns apps to migrate to returnProcess to avoid disruptions and unexpected outcomes. Integrations built before that version should check their processing path against the current reference.
This allows the integration to distinguish the planned return from the items actually being processed.
A warehouse might receive only part of an authorised return. The processing input should reflect the confirmed quantities rather than assuming the complete parcel arrived.
The business decides when processing should happen. That could follow inspection or another defined event, depending on the workflow and refund policy.
Connect return shipping to the right records
Return logistics use reverse fulfilment orders and reverse deliveries. The former describes return-processing work, while the latter groups items for a return shipment.
The reverseDeliveryCreateWithShipping mutation creates a reverse delivery with shipping information. Its inputs can include tracking and label details.
Attaching label information shouldn't be confused with purchasing postage. The implementation needs to establish where the label comes from and which system arranges the shipment.
The customer message should follow the confirmed shipping result. A failed label request needs a visible recovery path.
Treat exchanges as a connected workflow
An exchange includes both an item coming back and an item going out. It can also involve a price difference or other financial adjustment.
Recording an exchange item doesn't prove that its replacement has shipped. The integration needs to follow the relevant processing and fulfilment steps.
Before release, the team should test equal-value exchanges, price differences, unavailable variants and discounted items. These scenarios can expose assumptions hidden by a simple demonstration.
The support view should retain the original return and replacement context so agents can explain the current position.
Set the required access scopes
Shopify's return queries and mutations require the relevant access scopes. For ordinary merchant integrations, these include read_returns and write_returns, depending on the operation.
Other actions can require additional permissions. Refund creation, order access and fulfilment work should each be checked against their own API references.
Admin API credentials belong in the application's secure server-side environment. They shouldn't be exposed in a customer-facing return form.
A permissions failure should produce an actionable internal error. It shouldn't leave the customer believing a return was created successfully.
Handle errors before moving the case forward
A completed network request isn't enough to confirm a successful business action. Shopify mutation responses can contain userErrors that explain why the requested change wasn't accepted.
The integration should inspect the returned object and relevant errors before updating its own case status.
Suggested recovery categories include:
- Missing permissions that require an installation or access change.
- Invalid item references that require refreshed order data.
- Unavailable quantities that require another eligibility check.
- Temporary failures that can be retried safely.
- Uncertain outcomes that require checking Shopify before retrying.
That last category matters for refunds. Repeating an action after a timeout without checking the result can create a financial mistake.
Use webhooks without repeating actions
Webhooks notify connected applications about changes in Shopify. A returns integration can use them to react when a merchant or another application changes a case.
Shopify's delivery guidance explains how to verify webhook authenticity and identify duplicate events. The receiving application should perform those checks before acting on a message.
A practical design records processed event identifiers and separates receiving the event from performing the business action.
For financial or inventory changes, the application should also check current records. Receiving the same notification again mustn't create another refund or stock movement.
Map warehouse decisions explicitly
A parcel arriving at the warehouse doesn't establish whether its contents can return to saleable stock. Inspection can identify damage, missing accessories or an incorrect item.
The integration should define how each warehouse outcome maps to the return-processing and inventory actions.
It should also identify which system owns each stock movement. If both the warehouse system and another application independently restock the same item, inventory can become inaccurate.
Support needs visibility into exceptions. A case waiting for inspection should be distinguishable from one waiting for a refund retry.
Test the workflow beyond the first successful call
A useful test plan follows the complete customer case. Creating a return successfully proves only that the creation step worked for that input.
Suggested test cases include:
- A requested return that is approved and completed.
- A declined request.
- A return approved in the connected platform.
- A partial return from a split fulfilment.
- A parcel with fewer items than expected.
- A refund failure or uncertain transaction result.
- A repeated webhook.
- A merchant changing the return directly in Shopify.
The final check should compare the customer message, Shopify records, warehouse state and financial result. They should describe the same outcome.
Decide which work the integration should own
The Shopify Returns API provides operations for managing Shopify records. The business still needs a place to collect evidence, assign responsibility and coordinate exceptions.
That becomes more important when returns involve repairs, supplier approval or spare parts. An order update doesn't capture every conversation or decision needed to resolve those cases.
Claimlane's ecommerce and ERP integrations connect post-purchase work with surrounding systems. The required Shopify actions and data flow should be confirmed for the specific setup.
Issuing refunds and replacements without switching between systems has been a huge time saver for our team.
Patrick Zangenberg, Head of Customer ServiceThe implementation should make ownership explicit: which system approves the case, which issues the refund and which confirms the stock update.
Claimlane has a 4.8/5 rating on G2.
Frequently asked questions about the Shopify Returns API
Connect the API to the actual process
A reliable Shopify returns integration follows the case from request to confirmed outcome. It keeps approval, shipping, inspection and financial actions connected without treating them as interchangeable.
Clear ownership and visible errors matter as much as the API calls. They give the team a way to resolve exceptions when the normal path stops.
Book a Claimlane demo to discuss how Shopify returns can connect with support, warehouse and supplier workflows.
