Returns apps provide merchants with various ways to manage their returns. For example, returns apps offer functionality such as a customer self-serve portal, rules to identify eligible items for a return, exchanges and refunds to store credit, automated workflows, and more.

You can use Shopify's [dedicated APIs](/docs/apps/build/orders-fulfillment/returns-apps/build-self-serve-returns) for building a customer self-serve returns experience on [customer accounts](https://help.shopify.com/manual/customers/customer-accounts). You can also choose to build an app on your own platform and interact with the [GraphQL Admin API](/docs/api/admin-graphql).

This guide offers best practices for integrating with the GraphQL Admin API. It covers the concept of returns, the lifecycle of a return, use cases for returns apps, and some considerations to keep in mind before you get started.

> Caution:
> In API version 2025-07, Shopify introduced return processing as part of the return lifecycle management. Return processing confirms return items, releases exchange items, and updates a merchant's financial reports. Existing return apps should migrate to use [`returnProcess`](/docs/api/admin-graphql/unstable/mutations/returnProcess) to avoid disruptions and unexpected outcomes.

Learn how to [migrate to return processing](/docs/apps/build/orders-fulfillment/returns-apps/migrate-to-return-processing) if you have an existing returns app.

## How it works

A return represents the intent of a buyer to ship one or more items from an order back to a merchant or a third-party fulfillment location. Return apps facilitate the financial, logistical, and business rules associated with the lifecycle of a return.

You can use the GraphQL Admin API to provide a [return management workflow](/docs/apps/build/orders-fulfillment/returns-apps/build-return-management) for merchants.

The following diagram shows an example lifecycle of a return:

<figure class="figure"><img src="https://cdn.shopify.com/shopifycloud/shopify_dev/assets/apps/fulfillments/return-apps/return-lifecycle-9f4eb9e3399ce2c8342b412ea20f9f00ebb75a64a2adaed9041d9f97f6b4c1fa.png" class="lazyload" alt="A diagram showing the lifecycle of a return" width="100%" height="1803"></figure>


- The **customer** requests to return an item that was previously fulfilled, sends the item back to the merchant, and receives a refund.

    - They might have opted for an exchange or requested a refund in the form of store credit rather than a return to their original payment method.

- The **merchant** manages the return. For example, a merchant might take the following actions:

    - Determine the eligibility of the items to be returned.
    - Approve the return.
    - Track the return.
    - Decide whether to restock the returned items.
    - Release the exchange and collect a balance.
    - Issue a refund.


A return app can also allow merchants to manage returns that have been created by the app. For example, a merchant can cancel or close a return that was created by an app in the Shopify admin. Your app can get notified about returns-related events by subscribing to [webhooks](#webhooks).


### Reverse fulfillment orders and deliveries

Apps can manage [reverse fulfillment orders](/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-fulfillment-orders) and [reverse deliveries](/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-deliveries) on behalf of merchants.

A reverse fulfillment order represents the work that's required to process a return. It includes one or more items in a return that will be processed by the merchant or third-party fulfillment service. A reverse delivery is a set of items to be packaged together and sent back to the merchant or third-party fulfillment service.

The following diagram shows an example workflow of managing reverse fulfillment orders and reverse deliveries:

<figure class="figure"><img src="https://cdn.shopify.com/shopifycloud/shopify_dev/assets/apps/fulfillments/return-apps/fulfillment-orders-and-deliveries-6a3c63ed6569bd766495c4e7bd74fd2c8c0c4d169def3c01a9e592fd9e77e98f.png" class="lazyload" alt="A diagram showing the lifecycle of a return" width="100%" height="1098"></figure>

## Return statuses

Each return has a [status](/docs/api/admin-graphql/latest/enums/ReturnStatus), which indicates the state of the return. The following diagram shows how a return's status changes based on the GraphQL mutation that's executed:

<figure class="figure"><img src="https://cdn.shopify.com/shopifycloud/shopify_dev/assets/apps/fulfillments/return-apps/return-statuses-35ed6ebcf7d5b275db6a2d7d24aa6d4e137f7d4319e6554cac80eae3f6ccff44.png" class="lazyload" alt="A diagram showing the transition of return statuses" width="100%" height="1236"></figure>

- The [`returnRequest`](/docs/api/admin-graphql/latest/mutations/returnRequest) mutation changes the return's status to `REQUESTED`.
- The [`returnDeclineRequest`](/docs/api/admin-graphql/latest/mutations/returnDeclineRequest) mutation changes the return's status to `DECLINED`.
- The [`returnCreate`](/docs/api/admin-graphql/latest/mutations/returnCreate), [`returnApproveRequest`](/docs/api/admin-graphql/latest/mutations/returnApproveRequest), and [`returnReopen`](/docs/api/admin-graphql/latest/mutations/returnReopen) mutations change the return's status to `OPEN`.
- The [`returnProcess`](/docs/api/admin-graphql/unstable/mutations/returnProcess) mutation changes the return's status to `CLOSED` when all items have been processed and a restock decision has been made.
- The [`returnLineItemRemoveFromReturn`](/docs/api/admin-graphql/latest/mutations/returnLineItemRemoveFromReturn) mutation changes the return's status to `CLOSED` when all items have been removed.
- The [`returnCancel`](/docs/api/admin-graphql/latest/mutations/returnCancel) mutation changes the return's status to `CANCELED`.
- The [`returnClose`](/docs/api/admin-graphql/latest/mutations/returnClose) mutation changes the return's status to `CLOSED`.

## Use cases

Common use cases for returns apps include the following:

- A customer self-serve returns portal
- Limiting returns to eligible items
- Sending return labels to the customer
- Creating, canceling, and closing returns
- Automated workflows such as auto-approval, auto-restocking, and auto-refunds


## Webhooks

The following table describes the returns-related webhooks that your app can subscribe to in GraphQL Admin API version 2023-01 and higher. For more information about webhook topics, consult the [GraphQL Admin API reference](/docs/api/admin-graphql/latest/enums/WebhookSubscriptionTopic).

> Note:
> Return webhooks are available only in the GraphQL Admin API.


<table>
  <tr>
    <th>Webhook topic</th>
    <th>Description</th>
    <th>Payload information</th>
  </tr>
  <tr>
    <td><code>returns/request</code></li></td>
    <td>Occurs when a return is requested. This means that the return's status is <code>REQUESTED</code>.</td>
    <td rowspan="8"><a href="/docs/apps/build/orders-fulfillment/returns-apps/build-return-management#webhooks">Webhooks</a></td>
  </tr>
  <tr>
    <td><code>returns/approve</code></td>
    <td>Occurs when a return is approved. This means that the return's status is <code>OPEN</code>.</td>
  </tr>
  <tr>
    <td><code>returns/decline</code></td>
    <td>Occurs when a return is declined. This means that the return's status is <code>DECLINED</code>.</td>
  </tr>
  <tr>
    <td><code>refunds/create</code></td>
    <td>Occurs when a new refund is created without errors on an order, and includes returns data.</td>
  </tr>
  <tr>
    <td><code>returns/cancel</code></td>
    <td>Occurs when a return is canceled. This means that the return's status is <code>CANCELED</code>.</td>
  </tr>
  <tr>
    <td><code>returns/update</code></td>
    <td>Occurs when a return is updated, like when a return line item has been removed.</td>
  </tr>
  <tr>
    <td><code>returns/process</code></td>
    <td>Occurs when a return has been fully or partially processed. The return's status is <code>CLOSED</code> when all items have been processed and a restock decision has been made.</td>
  </tr>
  <tr>
    <td><code>returns/close</code></td>
    <td>Occurs when a return is closed. This means that the return's status is <code>CLOSED</code>.</td>
  </tr>
  <tr>
    <td><code>returns/reopen</code></td>
    <td>Occurs when a return is reopened. This means that the return's status is <code>OPEN</code>.</td>
  </tr>
  <tr>
    <td><code>reverse_fulfillment_orders/dispose</code></td>
    <td>Occurs when a disposition has been made.</td>
    <td><a href="/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-fulfillment-orders#webhooks">Reverse fulfillment orders webhook</a></td>
  </tr>
  <tr>
    <td><code>reverse_deliveries/attach_deliverable</code></td>
    <td>Occurs when a reverse delivery is created or updated with delivery metadata, such as the delivery method, label, and tracking information that's associated with a reverse delivery.</td>
    <td><a href="/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-deliveries#webhooks">Reverse deliveries webhook</a></td>
  </tr>
</table>

## Limitations and considerations

- You can return only items that have been fulfilled:
    - If you create a return on an [archived order](https://help.shopify.com/manual/orders/cancel-delete-order#archive-orders-manually), then the order is automatically unarchived.

    - If you need to make changes to an unfulfilled item, then you can [edit an order](/docs/apps/build/orders-fulfillment/order-management-apps/edit-orders).
- You can manage returns only using the GraphQL Admin API.
- If all items in a fulfillment are returned, or are in the process of being returned, then the fulfillment card won't render on the order detail page. You can access some fulfillment information from the [Timeline](https://help.shopify.com/manual/shopify-admin/timeline) instead.

## Next steps

- Learn how to [manage returns](/docs/apps/build/orders-fulfillment/returns-apps/build-return-management) by using the GraphQL Admin API.