---
title: Build self-serve returns using the Customer Account API
description: Learn how to use the Customer Account API to create self serve returns.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-self-serve-returns
  md: >-
    https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-self-serve-returns.md
api_name: customer
---

# Build self-serve returns using the Customer Account API

Using the Customer Account API, third-party (3P) developers can seamlessly build return apps on new customer accounts without needing additional app authorizations. Partners can query existing returns, create new return requests, and customize the experience for customers.

Additionally, these APIs provide Partners with visibility into an order line item's return eligibility, which incorporates [Shopify's Return rules](https://help.shopify.com/en/manual/fulfillment/managing-orders/returns/return-rules) for merchants with this feature enabled. Partners can determine which items can be returned and the expected refund amount, as well as why items are not returnable.

This guide shows you how to use the [`order`](https://shopify.dev/docs/api/customer/latest/queries/order) query to get the information you need regarding returns and how to request returns on behalf of customers using the Customer API.

***

## Requirements

* Your app can make [authenticated requests](https://shopify.dev/docs/api/customer#authentication) to the Customer Account API.
* Your store has existing [orders](https://shopify.dev/docs/api/customer/latest/objects/Order) that have been fulfilled. You can return only items that have been fulfilled. 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're using the `2025-04` version of the Customer API or higher.

- You've met Shopify's [protected customer data requirements](https://shopify.dev/docs/apps/launch/protected-customer-data).

***

## Step 1: Query for the return eligibility of an order

If an [`Order`](https://shopify.dev/docs/api/customer/latest/objects/Order) doesn't contain any items eligible for return, then the [`nonReturnableSummary`](https://shopify.dev/docs/api/customer/latest/objects/OrderReturnInformation#field-nonreturnablesummary) field on the [`returnInformation`](https://shopify.dev/docs/api/customer/latest/objects/Order#field-returninformation) will specify the reason for ineligibility. If the order is eligible for return, then this field will be `null`.

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL query

```graphql
query Order($id: ID!) {
  order(id: $id) {
    id
    returnInformation {
      nonReturnableSummary {
        nonReturnableReasons
      }
    }
  }
}
```

## GraphQL input

```json
{
  "id": "gid://shopify/Order/1"
}
```

## JSON response

```json
{
  "data": {
    "order": {
      "id": "gid://shopify/Order/1",
      "returnInformation": {
        "nonReturnableReasons": [
          "UNFULFILLED"
        ]
      }
    }
  }
}
```

***

## Step 2: Get the returnable and non-returnable line items of an order

You can use the [`returnInformation`](https://shopify.dev/docs/api/customer/latest/objects/Order#field-returninformation) field of an [`Order`](https://shopify.dev/docs/api/customer/latest/objects/Order) to get both the [`returnableLineItems`](https://shopify.dev/docs/api/customer/latest/objects/OrderReturnInformation#connection-returnablelineitems) and the [`nonReturnableLineItems`](https://shopify.dev/docs/api/customer/latest/objects/OrderReturnInformation#connection-nonreturnablelineitems).

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL query

```graphql
query Order($id: ID!, $first: Int!, $after: String) {
  order(id: $id) {
    returnInformation {
      returnableLineItems(first: $first, after: $after) {
        edges {
          node {
            lineItem {
              id
              presentmentTitle
              currentTotalPrice {
                amount
                currencyCode
              }
            }
            quantity
          }
        }
        pageInfo {
          endCursor
          hasNextPage
        }
      }
      nonReturnableLineItems(first: $first, after: $after) {
        edges {
          node {
            lineItem {
              id
              presentmentTitle
              currentTotalPrice {
                amount
                currencyCode
              }
            }
            quantity
          }
        }
        pageInfo {
          endCursor
          hasNextPage
        }
      }
    }
  }
}
```

## GraphQL input

```json
{
  "id": "gid://shopify/Order/1",
  "first": 250
}
```

## JSON response

```json
{
  "data": {
    "order": {
      "returnInformation": {
        "returnableLineItems": {
          "edges": [
            {
              "node": {
                "lineItem": {
                  "id": "gid://shopify/LineItem/1",
                  "presentmentTitle": "",
                  "currentTotalPrice": {
                    "amount": "1.26",
                    "currencyCode": "CAD"
                  }
                },
                "quantity": 1
              }
            }
          ],
          "pageInfo": {
            "endCursor": "1",
            "hasNextPage": false
          }
        },
        "nonReturnableLineItems": {
          "edges": [
            {
              "node": {
                "lineItem": {
                  "id": "gid://shopify/LineItem/2",
                  "presentmentTitle": "",
                  "currentTotalPrice": {
                    "amount": "1.0",
                    "currencyCode": "CAD"
                  }
                },
                "quantity": 1
              }
            }
          ],
          "pageInfo": {
            "endCursor": "2",
            "hasNextPage": false
          }
        }
      }
    }
  }
}
```

***

## Step 3: Get the calculated return amount

Use the [`returnCalculate`](https://shopify.dev/docs/api/customer/latest/queries/returnCalculate) query to calculate financial outcome of a return based on the line items requested for return. It includes a detailed [`ReturnFinancialSummary`](https://shopify.dev/docs/api/customer/latest/objects/ReturnFinancialSummary) that breaks down the [restocking](https://shopify.dev/docs/api/customer/latest/objects/ReturnFinancialSummary#field-restockingfeesubtotalset) and [`shipping fees`](https://shopify.dev/docs/api/customer/latest/objects/ReturnFinancialSummary#field-returnshippingfeesubtotalset), [`return subtotal`](https://shopify.dev/docs/api/customer/latest/objects/ReturnFinancialSummary#field-returnsubtotalset), [`subtotal with cart discounts`](https://shopify.dev/docs/api/customer/latest/objects/ReturnFinancialSummary#field-returnsubtotalwithcartdiscountset), [`total return amount`](https://shopify.dev/docs/api/customer/latest/objects/ReturnFinancialSummary#field-returntotalset), and [`total tax`](https://shopify.dev/docs/api/customer/latest/objects/ReturnFinancialSummary#field-returntotaltaxset), all presented in both customer-facing ([`presentmentMoney`](https://shopify.dev/docs/api/customer/latest/objects/MoneyBag#field-presentmentmoney)) and internal shop ([`shopMoney`](https://shopify.dev/docs/api/customer/latest/objects/MoneyBag#field-shopmoney)) currency formats. Additionally, the query retrieves detailed information about each [`return line item`](https://shopify.dev/docs/api/customer/latest/objects/CalculatedReturn#connection-returnlineitems), including current total price, quantity, and associated financial details like subtotal and total tax.

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL mutation

```graphql
query CalculatedReturn($orderId: ID!, $returnLineItems: [CalculateReturnLineItemInput!]!, $first: Int) {
  returnCalculate(input: {orderId: $orderId, returnLineItems: $returnLineItems}) {
    financialSummary {
      restockingFeeSubtotalSet {
        presentmentMoney {
          amount
          currencyCode
        }
        shopMoney {
          amount
          currencyCode
        }
      }
      returnShippingFeeSubtotalSet {
        presentmentMoney {
          amount
          currencyCode
        }
        shopMoney {
          amount
          currencyCode
        }
      }
      returnSubtotalSet {
        presentmentMoney {
          amount
          currencyCode
        }
        shopMoney {
          amount
          currencyCode
        }
      }
      returnSubtotalWithCartDiscountSet {
        presentmentMoney {
          amount
          currencyCode
        }
        shopMoney {
          amount
          currencyCode
        }
      }
      returnTotalSet {
        presentmentMoney {
          amount
          currencyCode
        }
        shopMoney {
          amount
          currencyCode
        }
      }
      returnTotalTaxSet {
        presentmentMoney {
          amount
          currencyCode
        }
        shopMoney {
          amount
          currencyCode
        }
      }
    }
    returnLineItems(first: $first) {
      edges {
        node {
          lineItem {
            id
            presentmentTitle
            currentTotalPrice {
              amount
              currencyCode
            }
          }
          quantity
          subtotalSet {
            presentmentMoney {
              amount
              currencyCode
            }
            shopMoney {
              amount
              currencyCode
            }
          }
          totalTaxSet {
            presentmentMoney {
              amount
              currencyCode
            }
            shopMoney {
              amount
              currencyCode
            }
          }
        }
      }
    }
  }
}
```

## GraphQL input

```json
{
  "orderId": "gid://shopify/Order/1",
  "returnLineItems": [
    {
      "lineItemId": "gid://shopify/LineItem/1",
      "quantity": 1
    }
  ],
  "first": 250
}
```

## JSON response

```json
{
  "data": {
    "returnCalculate": {
      "financialSummary": {
        "restockingFeeSubtotalSet": {
          "presentmentMoney": {
            "amount": "0.0",
            "currencyCode": "CAD"
          },
          "shopMoney": {
            "amount": "0.0",
            "currencyCode": "CAD"
          }
        },
        "returnShippingFeeSubtotalSet": {
          "presentmentMoney": {
            "amount": "0.0",
            "currencyCode": "CAD"
          },
          "shopMoney": {
            "amount": "0.0",
            "currencyCode": "CAD"
          }
        },
        "returnSubtotalSet": {
          "presentmentMoney": {
            "amount": "-82.99",
            "currencyCode": "CAD"
          },
          "shopMoney": {
            "amount": "-82.99",
            "currencyCode": "CAD"
          }
        },
        "returnSubtotalWithCartDiscountSet": {
          "presentmentMoney": {
            "amount": "-82.99",
            "currencyCode": "CAD"
          },
          "shopMoney": {
            "amount": "-82.99",
            "currencyCode": "CAD"
          }
        },
        "returnTotalSet": {
          "presentmentMoney": {
            "amount": "-82.99",
            "currencyCode": "CAD"
          },
          "shopMoney": {
            "amount": "-82.99",
            "currencyCode": "CAD"
          }
        },
        "returnTotalTaxSet": {
          "presentmentMoney": {
            "amount": "0.0",
            "currencyCode": "CAD"
          },
          "shopMoney": {
            "amount": "0.0",
            "currencyCode": "CAD"
          }
        }
      },
      "returnLineItems": {
        "edges": [
          {
            "node": {
              "lineItem": {
                "id": "gid://shopify/LineItem/46",
                "presentmentTitle": "Practical Linen Keyboard",
                "currentTotalPrice": {
                  "amount": "331.96",
                  "currencyCode": "CAD"
                }
              },
              "quantity": 1,
              "subtotalSet": {
                "presentmentMoney": {
                  "amount": "-82.99",
                  "currencyCode": "CAD"
                },
                "shopMoney": {
                  "amount": "-82.99",
                  "currencyCode": "CAD"
                }
              },
              "totalTaxSet": {
                "presentmentMoney": {
                  "amount": "0.0",
                  "currencyCode": "CAD"
                },
                "shopMoney": {
                  "amount": "0.0",
                  "currencyCode": "CAD"
                }
              }
            }
          }
        ]
      }
    }
  }
}
```

***

## Step 4: Create the return request

Use the [`orderRequestReturn`](https://shopify.dev/docs/api/customer/latest/mutations/orderRequestReturn) mutation to send a return request to the merchant. As the name implies, this mutation doesn't directly create a return. Instead, it submits a request that the merchant can approve or reject.

## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json

## GraphQL mutation

```graphql
mutation OrderRequestReturn($id: ID!, $requestedLineItems: [RequestedLineItemInput!]!) {
  orderRequestReturn(orderId: $id, requestedLineItems: $requestedLineItems) {
    return {
        id
      }
    userErrors {
      message
      code
    }
  }
}
```

## GraphQL input

```json
{
  "id": "gid://shopify/Order/1",
  "requestedLineItems": [
    {
      "lineItemId": "gid://shopify/LineItem/1",
      "quantity": 1,
      "returnReason": "SIZE_TOO_SMALL",
      "customerNote": null
    }
  ]
}
```

## JSON response

```json
{
  "data": {
    "orderRequestReturn": {
      "return": {
        "id": "gid://shopify/Return/1"
      },
      "userErrors": []
    }
  }
}
```

***

## Next steps

Using the GraphQL Admin API, you can lean how to do the following:

* [Manage exchanges](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-exchanges)
* [Preview and refund duties](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/view-and-refund-duties)
* [Manage reverse fulfillment orders](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-fulfillment-orders)
* [Manage reverse deliveries](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-deliveries)

***