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 for building a customer self-serve returns experience on customer accounts. You can also choose to build an app on your own platform and interact with the GraphQL Admin API.

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.

Learn how to migrate to return processing if you have an existing returns app.

Anchor to How it worksHow 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 for merchants.

The following diagram shows an example lifecycle of a return:

• 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.

Anchor to Reverse fulfillment orders and deliveriesReverse fulfillment orders and deliveries

Apps can manage reverse fulfillment orders and 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:

Anchor to Return statusesReturn statuses

Each return has a status, 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:

• The returnRequest mutation changes the return's status to REQUESTED.
• The returnDeclineRequest mutation changes the return's status to DECLINED.
• The returnCreate, returnApproveRequest, and returnReopen mutations change the return's status to OPEN.
• The returnProcess mutation changes the return's status to CLOSED when all items have been processed and a restock decision has been made.
• The returnLineItemRemoveFromReturn mutation changes the return's status to CLOSED when all items have been removed.
• The returnCancel mutation changes the return's status to CANCELED.
• The returnClose mutation changes the return's status to CLOSED.

Anchor to Use casesUse 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

Anchor to WebhooksWebhooks

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.

Anchor to Limitations and considerationsLimitations and considerations

• You can return only items that have been fulfilled:
  • If you create a return on an archived order, then the order is automatically unarchived.
  • If you need to make changes to an unfulfilled item, then you can edit an order.
• 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 instead.

Anchor to Next stepsNext steps

• Learn how to manage returns by using the GraphQL Admin API.