Shopify returns API: what it does, and what it can't see

Does Shopify have a returns API?

Shopify's returns API is the returns half of the GraphQL Admin API: queries and mutations that request, approve, create, process, close and reopen a return against an order, plus webhooks that fire as each state changes. It exists, the first answer most people find says it does not, and the refund path inside it was rebuilt underneath everybody in July 2025. The sharper point: even fully current, it can only ever show you the returns Shopify already knows about. The sequence I see most often: an operations lead asks for returns in the dashboard, the developer finds a years-old answer saying there is no endpoint, and the company builds a spreadsheet instead.

Dates settle it, and stale answers never carry any. Returns on Shopify are managed on the GraphQL Admin API and nowhere else, returns webhooks have existed since Admin API version 2023-01, and self-serve requests reached the Customer Account API in version 2025-01. Several returns apps sell an API of their own; this isn't one of them.

What a return is, as an object

A return and a refund are two different objects, and most pages on this subject blur them. The return object represents items coming back and can carry refunds inside it. A refund is money moving, and Shopify will let you issue one with no return attached at all. Build on the assumption that they're one thing and your returns report is a refund report.

A return holds one of five statuses.

• REQUESTED: the customer has asked, through self-serve or your storefront, and nobody has decided yet.
• OPEN: approved, or created directly by you, and waiting on the goods.
• DECLINED: refused, permanently, and it can't be refunded afterwards.
• CLOSED: finished, and the only status that can be reopened.
• CANCELED: withdrawn while open, and only possible if nothing has been refunded, disposed or labeled against it.

Hanging off the object are return line items, exchange line items, shipping fees, refunds, transactions, reverse fulfillment orders and the staff member who created it. That last field is your audit trail, and nobody asks for it until somebody needs to know who approved what.

The lifecycle, request to refund

There are two ways in. The customer requests a return, which lands at REQUESTED and waits for a decision, or you create one with returnCreate, which skips approval entirely. The documented sequence is short.

1. Ask what is even returnable. returnableFulfillments names the qualifying line items: only fulfilled items that haven't been refunded.
2. Price it before you commit. returnCalculate gives the financial picture under your own return rules, including shipping and restocking fees.
3. Open it. The request arrives at REQUESTED, or you create the return directly and it opens.
4. Decide. returnApproveRequest or returnDeclineRequest, and read the next section before you wire either to a rule.
5. Adjust while you can. Line items come off an open return only before anything is processed.
6. Check the suggested outcome. suggestedFinancialOutcome is what replaced the old suggested-refund field.
7. Process it. returnProcess confirms quantities, sets each item's disposition, creates any exchange fulfillment order, records the transactions and issues the refund.
8. Close it, and reopen it later if you must. Only a closed return can be reopened.

Steps one and seven are the two the business feels: one decides what is allowed to happen; seven is where the money and the inventory both move. The syntax belongs in Shopify's reference.

The calls you cannot take back

Five of these operations are one-way doors, and the documentation states them as preconditions rather than as risks.

• Approving a request: permanent. It can't be moved back to requested or to declined.
• Declining a request: permanent, and a declined return can't be refunded afterwards.
• Canceling a request: not possible at all. A requested return can only be approved or declined.
• Canceling an open return: allowed only while nothing has been refunded, disposed or labeled against it.
• Refunding: a refund can't be canceled or reversed once initiated, and a return can't be created against an order already refunded.

In the admin a person takes those actions one at a time, on a screen, hesitating in front of each. In an integration a rule takes them in bulk, at three in the morning, against an order nobody has looked at. The documented permanence is identical and the exposure is not. Auto-approval is the automation operators ask for first, and it's built entirely out of one-way doors.

The version clock nobody prices in

The change has already happened. In API version 2025-07 the old returnRefund mutation was deprecated and replaced by returnProcess, and the suggested-refund field was replaced by suggestedFinancialOutcome. Anything built against the old shape needs migrating, and most of what a search returns still describes it.

The clock behind that is published. Shopify ships a new API version every three months at the start of the quarter, and each stable version carries a minimum twelve-month support window with at least nine months of overlap between consecutive versions. Deprecated fields are removed in a later release, and an app still running on unsupported resources can be delisted and blocked from new installs.

The translation an operations lead needs: a returns integration isn't a project with an end date. It's a standing maintenance obligation on a quarterly cycle, and it belongs in the build-versus-buy conversation before anybody estimates the first sprint.

What the API can never show you

One constraint decides everything else, and it's not a rate limit or a permission: a return can only exist against a line item that was fulfilled and not refunded. That's the shape of the object.

The parcel that never arrived, the item that failed at the depot, the order canceled before it shipped and the order refunded on the spot to be kind can't carry a return, so none of them can be read out of this API. Not with better scopes, not with more engineering. Your developer builds exactly what was asked for, and the dashboard becomes a view of your own failures filtered by which customers were patient enough to file a request.

Returns aren't small: the National Retail Federation puts returns at 19.3% of online sales in 2025, against $326.7 billion of US e-commerce in the first quarter of 2026. This API meets a subset of that, and never meets the rest.

Two design notes follow. An event stream isn't a system of record: an integration that only reacts to webhooks can't tell nothing happening apart from an event that never arrived, so it reconciles by querying the returns on the order. And a return is itself an order that breaks the same ways, the parcel that stops scanning on the way back, the exchange held because inventory isn't reserved until processing. The API records each state faithfully and watches none of them for movement.

Every one of those breaks reaches you as a customer message, usually a WISMO question. A helpdesk answers the message; it doesn't fix the order. Shopify order tracking has the same blind spot on the way out.

Build the record, watch the promise

The build-versus-buy answer is narrower than it looks: the returns API is the right tool for recording and moving a return, and the wrong place to look for the breaks that never became one. In the stores we work with, one in five orders hits an operational break after checkout, and most are settled or abandoned long before a return exists.

• Detect: watch the order against the promise it made, so a parcel that stops moving or a short shipment is a signal before anyone opens a return.
• Decide: work out what the situation warrants: reship, refund, replace, or tell the customer before they notice.
• Act: do it, then tell the customer it's done.

Keeyu is proactive e-commerce operations, and the boundary matters here. We're not a returns app, not a returns portal, not a helpdesk, not a carrier and not an order management system, and there's no Keeyu API you build against instead of Shopify's. A Shopify returns app can wrap this API in a workflow, and every constraint above stays true underneath it.

If your returns data looks clean, look again: the orders that broke before anyone could file a return aren't in it, and never will be. Every order is a promise, and we keep it on the ones that break quietly. Keeyu detects the order going wrong, decides what should happen, and acts before the customer writes in. Book a Keeyu demo and we'll show you what your returns API isn't telling you.

• Shopify. Apps in returns, developer documentation. Return management runs on the GraphQL Admin API, only fulfilled items can be returned, and returns webhooks have existed since Admin API version 2023-01.
• Shopify. Build for return management, developer documentation. The operation sequence, the fulfilled and unrefunded precondition, and the permanence rules on approving, declining, canceling and reopening.
• Shopify. Return object, GraphQL Admin API. What a return holds: statuses, return and exchange line items, shipping fees, refunds, transactions, reverse fulfillment orders and the staff member who created it.
• Shopify. returnProcess mutation, GraphQL Admin API. Confirms quantities, sets dispositions, creates exchange fulfillment orders, records transactions and issues the refund. Scopes: write_returns or write_marketplace_returns.
• Shopify. Returns Processing APIs replaces Return Refund APIs, developer changelog. In API version 2025-07 returnRefund was deprecated in favor of returnProcess, and the suggested-refund field in favor of suggestedFinancialOutcome.
• Shopify. Returns now supported in Customer Accounts API, developer changelog. Self-serve return requests, eligibility and expected refunds arrived in version 2025-01.
• Shopify. API versioning, developer documentation. A new version every three months, a minimum twelve-month support window, at least nine months of overlap, and delisting for apps on unsupported resources.
• Shopify Help Center. Creating and processing returns and exchanges. The merchant-side equivalent of the lifecycle, including exchange inventory not being reserved until the return is processed.
• Shopify Help Center. Refunding orders. A refund can exist with no return attached, a refund cannot be canceled or reversed once initiated, and a return cannot be created after a refund.
• Shopify Help Center. Return and cancellation rules. The merchant rules that returnCalculate evaluates against: return windows, return shipping, restocking fees and final sale.
• Shopify Help Center. Shopify Flow trigger: Return requested. Return events can start a workflow without an app writing against the API.
• National Retail Federation. 2025 Retail Returns Landscape. 19.3% of online sales returned in 2025.
• US Census Bureau. Quarterly Retail E-Commerce Sales. Q1 2026 e-commerce sales of $326.7 billion, 16.9% of total US retail.