> ## Documentation Index
> Fetch the complete documentation index at: https://redo-44af351d-docs-v3-graphql-api-reference.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Return
> A return, exchange, claim, or warranty a customer opened on an order.
**Required scopes:**
[`returns_read`](/docs/api-reference/v3/reference/scopes#scope-returns_read),
[`returns_write`](/docs/api-reference/v3/reference/scopes#scope-returns_write)
[ReturnCompensationMethod!]!} required>
How the customer is compensated (e.g. refund, store credit, exchange).
Whether the return was closed without any action taken.
DateTime!} required>
When the return was created.
ReturnDestination!} required>
Where the returned items are sent (the merchant).
MailingAddress!} required>
The merchant's return address.
The first line of the address (street and number).
The second line of the address (apartment, suite, unit, etc.).
The city, town, or village.
The country.
The postal or ZIP code.
The province, state, or region.
A contact phone number for the destination.
[ReturnDropoff!]!} required>
Chosen label-free dropoffs for returning items.
The merchant-facing dropoff provider name.
The dropoff QR code, if any.
A URL to the dropoff QR code, if any.
The shipment group this dropoff is for.
ReturnExchange!} required>
Exchange details for the return.
Total quantity of exchange items.
[ExchangeItem!]!} required>
The items on the exchange order.
The exchange item id.
The exchange order's line item id, if known.
Money!} required>
The item's original price.
ExchangeItemPrice!} required>
The item's price.
The exchanged quantity.
The item's SKU.
ExternalRef!} required>
The exchanged-for variant.
ExchangeOrder!} required>
The exchange/new order.
The exchange order's external id.
ReturnProvisionType}>
How the exchange is provisioned.
Money!} required>
Total tax on the exchange order.
Decimal!} required>
The exact amount as a decimal string (e.g. "19.99").
ISO 4217 currency code (e.g. USD).
[ExternalReturnId!]!} required>
This return's ids in external systems (e.g. Shopify).
The external system, e.g. shopify.
The id within that system.
[ReturnGiftCard!]!} required>
Gift cards issued as part of the return.
Money}>
The gift card's value.
Decimal!} required>
The exact amount as a decimal string (e.g. "19.99").
ISO 4217 currency code (e.g. USD).
The gift card code.
The gift card's id in the external system.
The id of this return.
[ReturnIntegration!]!} required>
Links to this return in external integrations.
The id of the record in the external system.
The integration provider.
The kind of external record (e.g. rma).
The name of the merchant user who created the return, if merchant-created.
[ReturnItem!]!} required>
The items being returned.
[Assessment!]}>
Merchant assessments recorded for the item, if any.
AssessmentUser!} required>
The user who performed the assessment.
[AssessmentResponse!]!} required>
The assessment responses.
Free-text comments the customer left for this item.
ReturnItemExchangeItem}>
The item exchanged for this one, if an exchange.
ExternalRef!} required>
The exchanged-for product.
The exchanged quantity.
ExternalRef!} required>
The exchanged-for variant.
A merchant-set external identifier for the item.
The external return line item id, if any.
The merchant-assigned grade.
Whether the item is a green (keep-it) return.
The return item id.
[MultipleChoiceQuestion!]!} required>
Multiple-choice question answers for the item.
The chosen answer.
The question.
The id of the order line item this return item came from.
The merchant-assigned processing outcome.
Merchant-uploaded processing images.
Merchant processing notes.
The merchant price adjustment for the item.
The item's product id.
ReturnAmount!} required>
The item's product value excluding tax and adjustments.
Money!} required>
The amount.
The returned quantity.
The return reason.
The return reason code.
All return reason codes.
All return reasons.
ItemRefund!} required>
The refund for this item.
Money!} required>
The refunded amount for the item.
ReturnItemStrategy}>
The compensation strategy (null for exchanges).
Shipment groups this item belongs to.
The item's SKU.
ReturnItemStatus}>
The item's processing status.
The item's barcode/UPC.
The item's variant id.
The return's legacy Mongo ObjectId (24-char hex), for cross-referencing v2 data.
[ReturnNote!]!} required>
Non-system notes on the return's timeline.
A URL of the first image attached to the note, if any.
The note text.
ReturnOrder}>
The order this return was created against.
The order's legacy Mongo ObjectId (24-char hex). Use `orders` for the modeled Order relationship.
The order's display name, e.g. #1001.
OrderConnection!} required>
The orders the returned items came from.
**Requires:**
[`orders_read`](/docs/api-reference/v3/reference/scopes#scope-orders_read)
**Arguments**
Forward cursor — orders after this `edges[].cursor`.
Backward cursor — orders before this `edges[].cursor`.
Forward pagination: the first N orders (max 100, default 25). Use with `after`.
Backward pagination: the last N orders (max 100, default 25). Use with `before`.
**Fields**
[OrderEdge!]!} required>
The list of edges (each a node plus its pagination `cursor`).
Opaque cursor for this item; pass to `after`/`before` to page from here.
Order!} required>
The item at this edge.
[Order!]!} required>
The nodes in this page, without the edge/cursor wrapper — a convenience over `edges`.
DateTime!} required>
When the order was placed (the ecommerce provider's creation time, falling back to Redo's ingestion time).
The ISO 4217 currency code the order was placed in.
OrderCustomer}>
The customer who placed the order, if known.
The order's id in the source ecommerce platform.
[OrderFulfillment!]!} required>
The shipments fulfilling this order's items.
The id of this order.
The order's legacy Mongo ObjectId (24-char hex) from before the CockroachDB migration.
[OrderLineItem!]!} required>
The items purchased on this order.
OrderShipping}>
The order's shipping method, cost, and destination.
Money}>
The order subtotal, excluding tax and shipping, if known.
Free-form tags applied to the order.
Money}>
The order total, including tax and shipping, if known.
Money}>
The total tax charged on the order, if known.
PageInfo!} required>
Pagination metadata for the current page.
Cursor of the last edge in this page; pass to `after` to page forward.
Whether more items exist after this page (drives forward pagination with `first`/`after`).
Whether more items exist before this page (drives backward pagination with `last`/`before`).
Cursor of the first edge in this page; pass to `before` to page backward.
[ReturnRefund!]!} required>
Refund transactions issued for the return.
Money!} required>
The refunded amount.
Decimal!} required>
The exact amount as a decimal string (e.g. "19.99").
ISO 4217 currency code (e.g. USD).
The refund/transaction id in the external system.
ReturnShipment}>
The return's primary shipment, if any.
The carrier.
DateTime}>
When the shipment was delivered, if it has been.
Date}>
The carrier's estimated delivery date, if any.
The destination external location id, if any.
A URL to the customs/return form, if any.
Ids of the return items in this shipment.
A URL to the postage label, if any.
The shipment group this shipment belongs to.
The tracking status.
The tracking code.
A public tracking URL.
[ReturnShipment!]!} required>
All shipments for the return.
The carrier.
DateTime}>
When the shipment was delivered, if it has been.
Date}>
The carrier's estimated delivery date, if any.
The destination external location id, if any.
A URL to the customs/return form, if any.
Ids of the return items in this shipment.
A URL to the postage label, if any.
The shipment group this shipment belongs to.
The tracking status.
The tracking code.
A public tracking URL.
ReturnSource!} required>
Who the return is from (the customer).
The customer's email address.
MailingAddress}>
The customer's shipping address, if known.
The first line of the address (street and number).
The second line of the address (apartment, suite, unit, etc.).
The city, town, or village.
The country.
The postal or ZIP code.
The province, state, or region.
PersonName!} required>
The customer's name.
The given (first) name.
The family (last) name.
A contact phone number for the customer.
ReturnStatus!} required>
The return's current lifecycle status.
[ReturnTag!]!} required>
Tags applied to the return.
The tag's name.
What applied the tag (e.g. merchant, automation).
ReturnTotals!} required>
The monetary totals for the return.
ReturnAmount!} required>
Outstanding balance charged to the customer.
Money!} required>
The amount.
ReturnAmount!} required>
Value of the new/exchange order.
Money!} required>
The amount.
ReturnAmount!} required>
Merchant's return-label cost. Not stored on the returns mirror (lives in billing) — returned as 0 here.
Money!} required>
The amount.
ReturnAmount!} required>
Total refunded to the customer (excluding shipping).
Money!} required>
The amount.
ReturnAmount!} required>
Total issued as store credit.
Money!} required>
The amount.
ReturnType!} required>
What kind of return this is.
DateTime!} required>
When the return was last updated.