Returns apps provide merchants with various ways to manage their returns. For example, a returns app can identify eligible items for a return and issue customers a refund for returned items on behalf of the merchant.

This guide describes what returns are, the lifecycle of a return, use cases for returns apps, and some considerations before you get started.

## 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 capture the financial, logistical, and business intent 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-9799f4ae118b325435263b834d6673084df966193fe2222e3d159543583b9267.png" class="lazyload" alt="A diagram showing the lifecycle of a return" width="100%" height="1418"></figure>


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

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

    - Determining the eligibility of the return
    - Manually approving the return
    - Manually issuing a refund

    > Tip:
    > A merchant can manage returns that have been created by an app. For example, a merchant can cancel or close a return that was created by an app. Your app can get notified about returns-related events by subscribing to [webhooks](#webhooks).

- The **returns app** automates the return management process by taking actions on behalf of merchants. These actions can include the following:

    - Retrieving returnable fulfillments
    - Approving or declining returns
    - Creating and optionally canceling returns
    - Creating sales for return/exchange items
    - Creating fulfillments for exchange items
    - Sending shipping and tracking information to the customer
    - Issuing refunds to the customer
    - Closing and optionally reopening returns

- **Shopify** creates a reverse fulfillment order.

- The **third-party fulfillment service** disposes or restocks items. If a merchant is only using a returns app, and not a third-party fulfillment service, then an alternate workflow can be for the app to manage disposing and restocking items.

### 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-b720f73b962b5e40d5b1b954cb8b5666eac9cb9ef691cdfc2dcba52d900a1793.png" class="lazyload" alt="A diagram showing the transition of return statuses" width="100%" height="978"></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 [`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:

- Updating orders to reflect that a merchant or third-party fulfillment service has initiated or completed a return
- Marking items as returned, refunded, or restocked
- Adding exchange items to a return
- Uploading app-created shipping information to Shopify
- Getting notified if shipping information has changed

## 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 without errors on an order, and includes data on changes made to the return.</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.