--- 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 --- ExpandOn this page * [Requirements](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-self-serve-returns.md#requirements) * [Step 1: Query for the return eligibility of an order](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-self-serve-returns.md#step-1-query-for-the-return-eligibility-of-an-order) * [Step 2: Get the returnable and non-returnable line items of an order](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-self-serve-returns.md#step-2-get-the-returnable-and-non-returnable-line-items-of-an-order) * [Step 3: Get the calculated return amount](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-self-serve-returns.md#step-3-get-the-calculated-return-amount) * [Step 4: Create the return request](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-self-serve-returns.md#step-4-create-the-return-request) * [Next steps](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-self-serve-returns.md#next-steps) # 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) *** * [Requirements](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-self-serve-returns.md#requirements) * [Step 1: Query for the return eligibility of an order](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-self-serve-returns.md#step-1-query-for-the-return-eligibility-of-an-order) * [Step 2: Get the returnable and non-returnable line items of an order](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-self-serve-returns.md#step-2-get-the-returnable-and-non-returnable-line-items-of-an-order) * [Step 3: Get the calculated return amount](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-self-serve-returns.md#step-3-get-the-calculated-return-amount) * [Step 4: Create the return request](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-self-serve-returns.md#step-4-create-the-return-request) * [Next steps](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-self-serve-returns.md#next-steps)