> ## Documentation Index
> Fetch the complete documentation index at: https://developers.redo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# returnFlag

> Flag a return for attention, as the return page's Flag action does, and return it once flagged. A return that is already flagged comes back unchanged. Fails with `CLOSED_RETURN` if the return is processed, rejected or reset. Returns null if no return with that id is owned by the caller.

**Required scopes:** [`returns_write`](https://developers.redo.com/docs/api-reference/v3/reference/scopes#scope-returns_write)

**Store must have one of:** `RETURNS`, `PACKAGE_PROTECTION`, `OMS`, `WARRANTIES`, `RECYCLING`, `WITHDRAWALS`

## Arguments

**returnId** `ID!` *required*

The id of the return to flag: a branded Redo id or a 24-char Mongo ObjectId hex.

## Returns

**returnFlag** `[Return](/docs/api-reference/v3/reference/returns/return)`

A return, exchange, claim, or warranty a customer opened on an order.

**fields**

**compensationMethods** `[\[ReturnCompensationMethod!\]!](/docs/api-reference/v3/reference/returns/return-compensation-method)` *required*

How the customer is compensated (e.g. refund, store credit, exchange).

**completeWithNoAction** `Boolean!` *required*

Whether the return was closed without any action taken.

**createdAt** `[DateTime!](/docs/api-reference/v3/reference/common/date-time)` *required*

When the return was created.

**dropoffs** `[\[ReturnDropoff!\]!](/docs/api-reference/v3/reference/returns/return-dropoff)` *required*

Chosen label-free dropoffs for returning items.

**fields**

**provider** `String!` *required*

The merchant-facing dropoff provider name.

**qrCode** `String`

The dropoff QR code, if any.

**qrCodeUrl** `String`

A URL to the dropoff QR code, if any.

**shipmentGroupId** `String!` *required*

The shipment group this dropoff is for.

**exchange** `[ReturnExchange!](/docs/api-reference/v3/reference/returns/return-exchange)` *required*

Exchange details for the return.

**fields**

**itemCount** `Int!` *required*

Total quantity of exchange items.

**items** `[\[ExchangeItem!\]!](/docs/api-reference/v3/reference/returns/exchange-item)` *required*

The items on the exchange order.

**fields**

**id** `String!` *required*

The exchange item id.

**lineItemId** `String`

The exchange order's line item id, if known.

**originalPrice** `[Money!](/docs/api-reference/v3/reference/common/money)` *required*

The item's original price.

**price** `[ExchangeItemPrice!](/docs/api-reference/v3/reference/returns/exchange-item-price)` *required*

The item's price.

**quantity** `Float!` *required*

The exchanged quantity.

**sku** `String`

The item's SKU.

**variant** `[ExternalRef!](/docs/api-reference/v3/reference/returns/external-ref)` *required*

The exchanged-for variant.

**order** `[ExchangeOrder!](/docs/api-reference/v3/reference/returns/exchange-order)` *required*

The exchange/new order.

**fields**

**externalId** `String`

The exchange order's external id.

**provision** `[ReturnProvisionType](/docs/api-reference/v3/reference/returns/return-provision-type)`

How the exchange is provisioned.

**totalTax** `[Money!](/docs/api-reference/v3/reference/common/money)` *required*

Total tax on the exchange order.

**fields**

**amount** `[Decimal!](/docs/api-reference/v3/reference/common/decimal)` *required*

The exact amount as a decimal string (e.g. "19.99").

**currency** `String!` *required*

ISO 4217 currency code (e.g. USD).

**externalReturnIds** `[\[ExternalReturnId!\]!](/docs/api-reference/v3/reference/returns/external-return-id)` *required*

This return's ids in external systems (e.g. Shopify).

**fields**

**provider** `String!` *required*

The external system, e.g. shopify.

**value** `String!` *required*

The id within that system.

**giftCards** `[\[ReturnGiftCard!\]!](/docs/api-reference/v3/reference/returns/return-gift-card)` *required*

Gift cards issued as part of the return.

**fields**

**amount** `[Money](/docs/api-reference/v3/reference/common/money)`

The gift card's value.

**fields**

**amount** `[Decimal!](/docs/api-reference/v3/reference/common/decimal)` *required*

The exact amount as a decimal string (e.g. "19.99").

**currency** `String!` *required*

ISO 4217 currency code (e.g. USD).

**code** `String`

The gift card code.

**externalId** `String`

The gift card's id in the external system.

**id** `ID!` *required*

The id of this return.

**integrations** `[\[ReturnIntegration!\]!](/docs/api-reference/v3/reference/returns/return-integration)` *required*

Links to this return in external integrations.

**fields**

**externalId** `String!` *required*

The id of the record in the external system.

**provider** `String!` *required*

The integration provider.

**type** `String!` *required*

The kind of external record (e.g. rma).

**internalCreatedByName** `String`

The name of the merchant user who created the return, if merchant-created.

**items** `[\[ReturnItem!\]!](/docs/api-reference/v3/reference/returns/return-item)` *required*

The items being returned.

**fields**

**customerComment** `String!` *required*

Free-text comments the customer left for this item.

**exchangeItem** `[ReturnItemExchangeItem](/docs/api-reference/v3/reference/returns/return-item-exchange-item)`

The item exchanged for this one, if an exchange.

**fields**

**product** `[ExternalRef!](/docs/api-reference/v3/reference/returns/external-ref)` *required*

The exchanged-for product.

**quantity** `Int!` *required*

The exchanged quantity.

**variant** `[ExternalRef!](/docs/api-reference/v3/reference/returns/external-ref)` *required*

The exchanged-for variant.

**externalIdentifier** `String`

A merchant-set external identifier for the item.

**externalReturnLineItemId** `String`

The external return line item id, if any.

**grade** `String`

The merchant-assigned grade.

**greenReturn** `Boolean`

Whether the item is a green (keep-it) return.

**id** `ID!` *required*

The return item id.

**multipleChoiceQuestions** `[\[MultipleChoiceQuestion!\]!](/docs/api-reference/v3/reference/returns/multiple-choice-question)` *required*

Multiple-choice question answers for the item.

**fields**

**answer** `String!` *required*

The chosen answer.

**question** `String!` *required*

The question.

**orderLineItemId** `String`

The id of the order line item this return item came from.

**outcome** `String`

The merchant-assigned processing outcome.

**processingImages** `[String!]!` *required*

Merchant-uploaded processing images.

**processingNotes** `String`

Merchant processing notes.

**productAdjustment** `[Money](/docs/api-reference/v3/reference/common/money)`

The item's legacy price adjustment in the shop currency: positive for a bonus, negative for a fee. Does not include all adjustments used to calculate the return value.

**fields**

**amount** `[Decimal!](/docs/api-reference/v3/reference/common/decimal)` *required*

The exact amount as a decimal string (e.g. "19.99").

**currency** `String!` *required*

ISO 4217 currency code (e.g. USD).

**productId** `String`

The item's product id.

**productValue** `[Money!](/docs/api-reference/v3/reference/common/money)` *required*

The item's product value: the per-item price after discounts, before tax and merchant adjustments.

**fields**

**amount** `[Decimal!](/docs/api-reference/v3/reference/common/decimal)` *required*

The exact amount as a decimal string (e.g. "19.99").

**currency** `String!` *required*

ISO 4217 currency code (e.g. USD).

**quantity** `Int!` *required*

The returned quantity.

**reason** `String`

The return reason.

**reasonCode** `String`

The return reason code.

**reasonCodes** `[String!]!` *required*

All return reason codes.

**reasonConversation** `[ReasonConversation](/docs/api-reference/v3/reference/returns/reason-conversation)`

The conversation Redo had with the shopper to find their return reason. Null if the item did not go through the conversational return reason flow.

**fields**

**messages** `[\[ReasonConversationMessage!\]!](/docs/api-reference/v3/reference/returns/reason-conversation-message)` *required*

The messages the shopper saw, in order.

**summary** `String`

Generated summary of the conversation. Null until it has been generated.

**reasons** `[String!]!` *required*

All return reasons.

**refund** `[ItemRefund!](/docs/api-reference/v3/reference/returns/item-refund)` *required*

The refund for this item.

**fields**

**amount** `[Money!](/docs/api-reference/v3/reference/common/money)` *required*

The refunded amount for the item.

**type** `[ReturnItemStrategy](/docs/api-reference/v3/reference/returns/return-item-strategy)`

The compensation strategy (null for exchanges).

**sku** `String`

The item's SKU.

**status** `[ReturnItemStatus](/docs/api-reference/v3/reference/returns/return-item-status)`

The item's processing status.

**tax** `[Money](/docs/api-reference/v3/reference/common/money)`

The tax amount for this item, when available.

**fields**

**amount** `[Decimal!](/docs/api-reference/v3/reference/common/decimal)` *required*

The exact amount as a decimal string (e.g. "19.99").

**currency** `String!` *required*

ISO 4217 currency code (e.g. USD).

**upc** `String`

The item's barcode/UPC.

**variantId** `String`

The item's variant id.

**legacyId** `String!` *required*

The return's legacy Mongo ObjectId (24-char hex), for cross-referencing v2 data.

**notes** `[\[ReturnNote!\]!](/docs/api-reference/v3/reference/returns/return-note)` *required*

Non-system notes on the return's timeline.

**fields**

**image** `String`

A URL of the first image attached to the note, if any.

**message** `String`

The note text.

**orders** `[OrderConnection!](/docs/api-reference/v3/pagination)` *required*

The orders the returned items came from.

**Requires:** [`orders_read`](https://developers.redo.com/docs/api-reference/v3/reference/scopes#scope-orders_read)

**fields**

**Arguments**

**after** `String`

Forward cursor — orders after this `edges[].cursor`.

**before** `String`

Backward cursor — orders before this `edges[].cursor`.

**first** `Int`

Forward pagination: the first N orders (max 100, default 25). Use with `after`.

**last** `Int`

Backward pagination: the last N orders (max 100, default 25). Use with `before`.

**Fields**

**edges** `[\[OrderEdge!\]!](/docs/api-reference/v3/pagination)` *required*

The list of edges (each a node plus its pagination `cursor`).

**fields**

**cursor** `String!` *required*

Opaque cursor for this item; pass to `after`/`before` to page from here.

**node** `[Order!](/docs/api-reference/v3/reference/orders/order)` *required*

The item at this edge.

**nodes** `[\[Order!\]!](/docs/api-reference/v3/reference/orders/order)` *required*

The nodes in this page, without the edge/cursor wrapper — a convenience over `edges`.

**fields**

**createdAt** `[DateTime!](/docs/api-reference/v3/reference/common/date-time)` *required*

When the order was placed (the ecommerce provider's creation time, falling back to Redo's ingestion time).

**currencyCode** `String`

The ISO 4217 currency code the order was placed in.

**customer** `[OrderCustomer](/docs/api-reference/v3/reference/orders/order-customer)`

The customer who placed the order, if known.

**externalId** `String!` *required*

The order's id in the source ecommerce platform.

**fulfillments** `[\[OrderFulfillment!\]!](/docs/api-reference/v3/reference/orders/order-fulfillment)` *required*

The shipments fulfilling this order's items.

**id** `ID!` *required*

The id of this order.

**legacyId** `String!` *required*

The order's legacy Mongo ObjectId (24-char hex) from before the CockroachDB migration.

**lineItems** `[\[OrderLineItem!\]!](/docs/api-reference/v3/reference/orders/order-line-item)` *required*

The items purchased on this order.

**protection** `[OrderProtection!](/docs/api-reference/v3/reference/orders/order-protection)` *required*

The Redo coverage the customer bought on this order.

**shipping** `[OrderShipping](/docs/api-reference/v3/reference/orders/order-shipping)`

The order's shipping method, cost, and destination.

**subtotalPrice** `[Money](/docs/api-reference/v3/reference/common/money)`

The order subtotal, excluding tax and shipping, if known.

**tags** `[String!]!` *required*

Free-form tags applied to the order.

**totalPrice** `[Money](/docs/api-reference/v3/reference/common/money)`

The order total, including tax and shipping, if known.

**totalTax** `[Money](/docs/api-reference/v3/reference/common/money)`

The total tax charged on the order, if known.

**pageInfo** `[PageInfo!](/docs/api-reference/v3/pagination)` *required*

Pagination metadata for the current page.

**fields**

**endCursor** `String`

Cursor of the last edge in this page; pass to `after` to page forward.

**hasNextPage** `Boolean!` *required*

Whether more items exist after this page (drives forward pagination with `first`/`after`).

**hasPreviousPage** `Boolean!` *required*

Whether more items exist before this page (drives backward pagination with `last`/`before`).

**startCursor** `String`

Cursor of the first edge in this page; pass to `before` to page backward.

**protection** `[ReturnProtection!](/docs/api-reference/v3/reference/returns/return-protection)` *required*

The Redo coverage behind this return and who it left paying for the label.

**fields**

**covered** `Boolean!` *required*

Whether any order on the return carried Redo coverage — returns coverage or package protection.

**finalSaleCoverage** `Boolean!` *required*

Whether any order on the return carried Redo final-sale returns coverage.

**labelPayer** `[ReturnLabelPayer](/docs/api-reference/v3/reference/returns/return-label-payer)`

Who pays for the return label. Null before a payer is settled.

**labelPayerReason** `[ReturnLabelPayerReason](/docs/api-reference/v3/reference/returns/return-label-payer-reason)`

Why the label fell to that payer.

**packageProtection** `Boolean!` *required*

Whether any order on the return carried Redo package protection.

**returnsCoverage** `Boolean!` *required*

Whether any order on the return carried Redo returns coverage.

**refunds** `[\[ReturnRefund!\]!](/docs/api-reference/v3/reference/returns/return-refund)` *required*

Refund transactions issued for the return.

**fields**

**amount** `[Money!](/docs/api-reference/v3/reference/common/money)` *required*

The refunded amount.

**fields**

**amount** `[Decimal!](/docs/api-reference/v3/reference/common/decimal)` *required*

The exact amount as a decimal string (e.g. "19.99").

**currency** `String!` *required*

ISO 4217 currency code (e.g. USD).

**externalId** `String`

The refund/transaction id in the external system.

**shipmentGroups** `[\[ReturnShipmentGroup!\]!](/docs/api-reference/v3/reference/returns/return-shipment-group)` *required*

The shipment groups for the return; each carries its destination and shipments.

**fields**

**destination** `[MailingAddress!](/docs/api-reference/v3/reference/common/mailing-address)` *required*

The address the group's items are returned to.

**fields**

**address1** `String`

The first line of the address (street and number).

**address2** `String`

The second line of the address (apartment, suite, unit, etc.).

**city** `String`

The city, town, or village.

**country** `String`

The country.

**postalCode** `String`

The postal or ZIP code.

**province** `String`

The province, state, or region.

**externalLocationId** `String`

The destination external location id, if any.

**id** `ID!` *required*

The id of this shipment group.

**items** `[\[ReturnItem!\]!](/docs/api-reference/v3/reference/returns/return-item)` *required*

The return items assigned to this group's label.

**fields**

**customerComment** `String!` *required*

Free-text comments the customer left for this item.

**exchangeItem** `[ReturnItemExchangeItem](/docs/api-reference/v3/reference/returns/return-item-exchange-item)`

The item exchanged for this one, if an exchange.

**externalIdentifier** `String`

A merchant-set external identifier for the item.

**externalReturnLineItemId** `String`

The external return line item id, if any.

**grade** `String`

The merchant-assigned grade.

**greenReturn** `Boolean`

Whether the item is a green (keep-it) return.

**id** `ID!` *required*

The return item id.

**multipleChoiceQuestions** `[\[MultipleChoiceQuestion!\]!](/docs/api-reference/v3/reference/returns/multiple-choice-question)` *required*

Multiple-choice question answers for the item.

**orderLineItemId** `String`

The id of the order line item this return item came from.

**outcome** `String`

The merchant-assigned processing outcome.

**processingImages** `[String!]!` *required*

Merchant-uploaded processing images.

**processingNotes** `String`

Merchant processing notes.

**productAdjustment** `[Money](/docs/api-reference/v3/reference/common/money)`

The item's legacy price adjustment in the shop currency: positive for a bonus, negative for a fee. Does not include all adjustments used to calculate the return value.

**productId** `String`

The item's product id.

**productValue** `[Money!](/docs/api-reference/v3/reference/common/money)` *required*

The item's product value: the per-item price after discounts, before tax and merchant adjustments.

**quantity** `Int!` *required*

The returned quantity.

**reason** `String`

The return reason.

**reasonCode** `String`

The return reason code.

**reasonCodes** `[String!]!` *required*

All return reason codes.

**reasonConversation** `[ReasonConversation](/docs/api-reference/v3/reference/returns/reason-conversation)`

The conversation Redo had with the shopper to find their return reason. Null if the item did not go through the conversational return reason flow.

**reasons** `[String!]!` *required*

All return reasons.

**refund** `[ItemRefund!](/docs/api-reference/v3/reference/returns/item-refund)` *required*

The refund for this item.

**sku** `String`

The item's SKU.

**status** `[ReturnItemStatus](/docs/api-reference/v3/reference/returns/return-item-status)`

The item's processing status.

**tax** `[Money](/docs/api-reference/v3/reference/common/money)`

The tax amount for this item, when available.

**upc** `String`

The item's barcode/UPC.

**variantId** `String`

The item's variant id.

**shipment** `[ReturnShipment](/docs/api-reference/v3/reference/returns/return-shipment)`

The shipment fulfilling this group, if a label exists.

**Requires:** [`returns_read`](https://developers.redo.com/docs/api-reference/v3/reference/scopes#scope-returns_read)

**fields**

**carrier** `String`

The carrier.

**deliveredAt** `[DateTime](/docs/api-reference/v3/reference/common/date-time)`

When the shipment was delivered, if it has been.

**estimatedDeliveryDate** `[Date](/docs/api-reference/v3/reference/common/date)`

The carrier's estimated delivery date, if any.

**formLabel** `String`

A URL to the customs/return form, if any.

**id** `ID!` *required*

The id of this shipment.

**postageLabel** `String`

A URL to the postage label, if any.

**status** `String`

The tracking status.

**tracker** `String`

The tracking code.

**trackingUrl** `String`

A public tracking URL.

**source** `[ReturnSource!](/docs/api-reference/v3/reference/returns/return-source)` *required*

Who the return is from (the customer).

**fields**

**emailAddress** `String`

The customer's email address.

**mailingAddress** `[MailingAddress](/docs/api-reference/v3/reference/common/mailing-address)`

The customer's shipping address, if known.

**fields**

**address1** `String`

The first line of the address (street and number).

**address2** `String`

The second line of the address (apartment, suite, unit, etc.).

**city** `String`

The city, town, or village.

**country** `String`

The country.

**postalCode** `String`

The postal or ZIP code.

**province** `String`

The province, state, or region.

**name** `[PersonName!](/docs/api-reference/v3/reference/returns/person-name)` *required*

The customer's name.

**fields**

**given** `String!` *required*

The given (first) name.

**surname** `String!` *required*

The family (last) name.

**phoneNumber** `String`

A contact phone number for the customer.

**status** `[ReturnStatus!](/docs/api-reference/v3/reference/returns/return-status)` *required*

The return's current lifecycle status.

**tags** `[String!]!` *required*

Tags applied to the return.

**totals** `[ReturnTotals!](/docs/api-reference/v3/reference/returns/return-totals)` *required*

The monetary totals for the return.

**fields**

**charge** `[Money!](/docs/api-reference/v3/reference/common/money)` *required*

Outstanding balance charged to the customer.

**fields**

**amount** `[Decimal!](/docs/api-reference/v3/reference/common/decimal)` *required*

The exact amount as a decimal string (e.g. "19.99").

**currency** `String!` *required*

ISO 4217 currency code (e.g. USD).

**exchange** `[Money!](/docs/api-reference/v3/reference/common/money)` *required*

Value of the new/exchange order.

**fields**

**amount** `[Decimal!](/docs/api-reference/v3/reference/common/decimal)` *required*

The exact amount as a decimal string (e.g. "19.99").

**currency** `String!` *required*

ISO 4217 currency code (e.g. USD).

**labelCost** `[Money!](/docs/api-reference/v3/reference/common/money)` *required*

Merchant's return-label cost. Not stored on the returns mirror (lives in billing) — returned as 0 here.

**fields**

**amount** `[Decimal!](/docs/api-reference/v3/reference/common/decimal)` *required*

The exact amount as a decimal string (e.g. "19.99").

**currency** `String!` *required*

ISO 4217 currency code (e.g. USD).

**refund** `[Money!](/docs/api-reference/v3/reference/common/money)` *required*

Total refunded to the customer (excluding shipping).

**fields**

**amount** `[Decimal!](/docs/api-reference/v3/reference/common/decimal)` *required*

The exact amount as a decimal string (e.g. "19.99").

**currency** `String!` *required*

ISO 4217 currency code (e.g. USD).

**storeCredit** `[Money!](/docs/api-reference/v3/reference/common/money)` *required*

Total issued as store credit.

**fields**

**amount** `[Decimal!](/docs/api-reference/v3/reference/common/decimal)` *required*

The exact amount as a decimal string (e.g. "19.99").

**currency** `String!` *required*

ISO 4217 currency code (e.g. USD).

**type** `[ReturnType!](/docs/api-reference/v3/reference/returns/return-type)` *required*

What kind of return this is.

**updatedAt** `[DateTime!](/docs/api-reference/v3/reference/common/date-time)` *required*

When the return was last updated.

## Example

```graphql theme={null}
mutation {
  returnFlag(returnId: "...") {
    compensationMethods
    completeWithNoAction
    createdAt
    id
    internalCreatedByName
    legacyId
    orders {
      nodes {
        createdAt
        currencyCode
        externalId
        id
        legacyId
        tags
      }
      pageInfo { hasNextPage endCursor }
    }
    status
    # ...
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.