--- title: Return - GraphQL Admin description: |- The `Return` object 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. A return is associated with an [order](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order) and can include multiple return [line items](https://shopify.dev/docs/api/admin-graphql/latest/objects/LineItem). Each return has a [status](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps#return-statuses), which indicates the state of the return. Use the `Return` object to capture the financial, logistical, and business intent of a return. For example, you can identify eligible items for a return and issue customers a refund for returned items on behalf of the merchant. Learn more about providing a [return management workflow](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-return-management) for merchants. You can also manage [exchanges](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-exchanges), [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. api_version: 2025-10 api_name: admin type: object api_type: graphql source_url: html: https://shopify.dev/docs/api/admin-graphql/latest/objects/return md: https://shopify.dev/docs/api/admin-graphql/latest/objects/return.md --- # Return object Requires `read_returns` access scope or `read_marketplace_returns` access scope. The `Return` object 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. A return is associated with an [order](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order) and can include multiple return [line items](https://shopify.dev/docs/api/admin-graphql/latest/objects/LineItem). Each return has a [status](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps#return-statuses), which indicates the state of the return. Use the `Return` object to capture the financial, logistical, and business intent of a return. For example, you can identify eligible items for a return and issue customers a refund for returned items on behalf of the merchant. Learn more about providing a [return management workflow](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-return-management) for merchants. You can also manage [exchanges](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-exchanges), [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. ## Fields * closed​At [Date​Time](https://shopify.dev/docs/api/admin-graphql/latest/scalars/DateTime) The date and time when the return was closed. * created​At [Date​Time!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/DateTime) non-null The date and time when the return was created. * decline [Return​Decline](https://shopify.dev/docs/api/admin-graphql/latest/objects/ReturnDecline) Additional information about the declined return. * exchange​Line​Items [Exchange​Line​Item​Connection!](https://shopify.dev/docs/api/admin-graphql/latest/connections/ExchangeLineItemConnection) non-null The exchange line items attached to the return. * id [ID!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID) non-null A globally-unique ID. * name [String!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) non-null The name of the return. * order [Order!](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order) non-null The order that the return belongs to. * refunds [Refund​Connection!](https://shopify.dev/docs/api/admin-graphql/latest/connections/RefundConnection) non-null The list of refunds associated with the return. * request​Approved​At [Date​Time](https://shopify.dev/docs/api/admin-graphql/latest/scalars/DateTime) The date and time when the return was approved. * return​Line​Items [Return​Line​Item​Type​Connection!](https://shopify.dev/docs/api/admin-graphql/latest/connections/ReturnLineItemTypeConnection) non-null The return line items attached to the return. * return​Shipping​Fees [\[Return​Shipping​Fee!\]!](https://shopify.dev/docs/api/admin-graphql/latest/objects/ReturnShippingFee) non-null The return shipping fees for the return. * reverse​Fulfillment​Orders [Reverse​Fulfillment​Order​Connection!](https://shopify.dev/docs/api/admin-graphql/latest/connections/ReverseFulfillmentOrderConnection) non-null The list of reverse fulfillment orders for the return. * status [Return​Status!](https://shopify.dev/docs/api/admin-graphql/latest/enums/ReturnStatus) non-null The status of the return. * suggested​Financial​Outcome [Suggested​Return​Financial​Outcome](https://shopify.dev/docs/api/admin-graphql/latest/objects/SuggestedReturnFinancialOutcome) A suggested financial outcome for the return. * total​Quantity [Int!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) non-null The sum of all return line item quantities for the return. * suggested​Refund [Suggested​Return​Refund](https://shopify.dev/docs/api/admin-graphql/latest/objects/SuggestedReturnRefund) Deprecated *** ## Map ### Fields and connections with this object * {}[Order.returns](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order#field-Order.fields.returns) * {}[Refund.return](https://shopify.dev/docs/api/admin-graphql/latest/objects/Refund#field-Refund.fields.return) * {}[ReturnAgreement.return](https://shopify.dev/docs/api/admin-graphql/latest/objects/ReturnAgreement#field-ReturnAgreement.fields.return) * <->[ReturnConnection.nodes](https://shopify.dev/docs/api/admin-graphql/latest/connections/ReturnConnection#returns-nodes) * {}[ReturnEdge.node](https://shopify.dev/docs/api/admin-graphql/latest/objects/ReturnEdge#field-ReturnEdge.fields.node) *** ## Queries * [return](https://shopify.dev/docs/api/admin-graphql/latest/queries/return) query Retrieves a return by its ID. 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. Use the `return` query to retrieve information associated with the following workflows: * [Managing returns](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-return-management) * [Processing exchanges](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-exchanges) * [Tracking reverse fulfillment orders](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-fulfillment-orders) A return is associated with an [order](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order) and can include multiple return [line items](https://shopify.dev/docs/api/admin-graphql/latest/objects/LineItem). Each return has a [status](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps#return-statuses), which indicates the state of the return. *** ## \Return Queries ### Queried by * \[return](https://shopify.dev/docs/api/admin-graphql/latest/queries/return) *** ## Mutations * [remove​From​Return](https://shopify.dev/docs/api/admin-graphql/latest/mutations/removeFromReturn) mutation Removes return and/or exchange lines from a return. * [return​Approve​Request](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnApproveRequest) mutation Approves a customer's return request. If this mutation is successful, then the `Return.status` field of the approved return is set to `OPEN`. * [return​Cancel](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnCancel) mutation Cancels a return and restores the items back to being fulfilled. Canceling a return is only available before any work has been done on the return (such as an inspection or refund). * [return​Close](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnClose) mutation Indicates a return is complete, either when a refund has been made and items restocked, or simply when it has been marked as returned in the system. * [return​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnCreate) mutation Creates a return from an existing order that has at least one fulfilled [line item](https://shopify.dev/docs/api/admin-graphql/latest/objects/LineItem) that hasn't yet been refunded. If you create a return on an archived order, then the order is automatically unarchived. Use the `returnCreate` mutation when your workflow involves [approving](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnApproveRequest) or [declining](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnDeclineRequest) requested returns outside of the Shopify platform. The `returnCreate` mutation performs the following actions: * Creates a return in the `OPEN` state, and assumes that the return request from the customer has already been approved * Creates a [reverse fulfillment order](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-fulfillment-orders), and enables you to create a [reverse delivery](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-deliveries) for the reverse fulfillment order * Creates a sales agreement with a `RETURN` reason, which links to all sales created for the return or exchange * Generates sales records that reverse the sales records for the items being returned * Generates sales records for any exchange line items After you've created a return, use the [`return`](https://shopify.dev/docs/api/admin-graphql/latest/queries/return) query to retrieve the return by its ID. Learn more about providing a [return management workflow](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-return-management) for merchants. * [return​Decline​Request](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnDeclineRequest) mutation Declines a return on an order. When a return is declined, each `ReturnLineItem.fulfillmentLineItem` can be associated to a new return. Use the `ReturnCreate` or `ReturnRequest` mutation to initiate a new return. * [return​Process](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnProcess) mutation Process a return. * [return​Reopen](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnReopen) mutation Reopens a closed return. * [return​Request](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnRequest) mutation A customer's return request that hasn't been approved or declined. This mutation sets the value of the `Return.status` field to `REQUESTED`. To create a return that has the `Return.status` field set to `OPEN`, use the `returnCreate` mutation. * [return​Line​Item​Remove​From​Return](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnLineItemRemoveFromReturn) mutation Deprecated *** ## <\~> Return Mutations ### Mutated by * <\~>[remove​From​Return](https://shopify.dev/docs/api/admin-graphql/latest/mutations/removeFromReturn) * <\~>[return​Approve​Request](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnApproveRequest) * <\~>[return​Cancel](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnCancel) * <\~>[return​Close](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnClose) * <\~>[return​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnCreate) * <\~>[return​Decline​Request](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnDeclineRequest) * <\~>[return​Process](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnProcess) * <\~>[return​Reopen](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnReopen) * <\~>[return​Request](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnRequest) *** ## Interfaces * [Node](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/Node) interface *** ## ||-Return Implements ### Implements * ||-[Node](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/Node)