--- title: Apps in returns description: >- Learn about how returns apps can provide a return management workflow for merchants and customers. source_url: html: 'https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps' md: 'https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps.md' --- # Apps in returns 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](https://shopify.dev/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](https://shopify.dev/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`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnProcess) to avoid disruptions and unexpected outcomes. *** ## 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](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-return-management) for merchants. The following diagram shows an example lifecycle of a return: ![A diagram showing the lifecycle of a return](https://shopify.dev/assets/assets/images/apps/fulfillments/return-apps/return-lifecycle-BWgLBKoJ.png) * 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](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-fulfillment-orders) and [reverse deliveries](https://shopify.dev/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: ![A diagram showing the lifecycle of a return](https://shopify.dev/assets/assets/images/apps/fulfillments/return-apps/fulfillment-orders-and-deliveries-BkNWAfeg.png) *** ## Return statuses Each return has a [status](https://shopify.dev/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: ![A diagram showing the transition of return statuses](https://shopify.dev/assets/assets/images/apps/fulfillments/return-apps/return-statuses-BsUmWqdR.png) * The [`returnRequest`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnRequest) mutation changes the return's status to `REQUESTED`. * The [`returnDeclineRequest`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnDeclineRequest) mutation changes the return's status to `DECLINED`. * The [`returnCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnCreate), [`returnApproveRequest`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnApproveRequest), and [`returnReopen`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnReopen) mutations change the return's status to `OPEN`. * The [`returnProcess`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnProcess) mutation changes the return's status to `CLOSED` when all items have been processed and a restock decision has been made. * The [`removeFromReturn`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/removeFromReturn) mutation changes the return's status to `CLOSED` when all items have been removed. * The [`returnCancel`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnCancel) mutation changes the return's status to `CANCELED`. * The [`returnClose`](https://shopify.dev/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](https://shopify.dev/docs/api/admin-graphql/latest/enums/WebhookSubscriptionTopic). **Note:** Return webhooks are available only in the GraphQL Admin API. | Webhook topic | Description | Payload information | | - | - | - | | `returns/request` | Occurs when a return is requested. This means that the return's status is `REQUESTED`. | [Webhooks](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-return-management#webhooks) | | `returns/approve` | Occurs when a return is approved. This means that the return's status is `OPEN`. | | | `returns/decline` | Occurs when a return is declined. This means that the return's status is `DECLINED`. | | | `refunds/create` | Occurs when a new refund is created without errors on an order, and includes returns data. | | | `returns/cancel` | Occurs when a return is canceled. This means that the return's status is `CANCELED`. | | | `returns/update` | Occurs when a return is updated, like when a return line item has been removed. | | | `returns/process` | Occurs when a return has been fully or partially processed. The return's status is `CLOSED` when all items have been processed and a restock decision has been made. | | | `returns/close` | Occurs when a return is closed. This means that the return's status is `CLOSED`. | | | `returns/reopen` | Occurs when a return is reopened. This means that the return's status is `OPEN`. | | | `reverse_fulfillment_orders/dispose` | Occurs when a disposition has been made. | [Reverse fulfillment orders webhook](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-fulfillment-orders#webhooks) | | `reverse_deliveries/attach_deliverable` | 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. | [Reverse deliveries webhook](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-deliveries#webhooks) | *** ## Limitations * You can only return 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](https://shopify.dev/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](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-return-management) by using the GraphQL Admin API. ***