> ## 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.

# returnProductCustomsUpdate

> Change the customs details of a product on a return, as the return page's customs edit does, and return the return. The details belong to the product, so the change reaches every return and label for it, not just this return. A field you leave out keeps its value; `null` clears it. When the return is held in customs, the change also restarts its customs correction. Returns null if no return with that id is owned by the caller, or the product is not on that return.

**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

**customsDescription** `String`

What the product is, as declared on customs forms, up to 250 characters. `null` clears it.

**hsCode** `String`

The Harmonized System code, up to 50 characters. `null` clears it.

**materialDescription** `String`

What the product is made of, up to 250 characters. `null` clears it.

**originCountry** `String`

The country the product is made in, as a two-letter uppercase country code. `null` clears it.

**productId** `ID!` *required*

The id of the product, which must be on the return.

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

The id of the return the product is on.

## Returns

**returnProductCustomsUpdate** `[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, oldest first.

**fields**

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

When the note was written.

**edited** `Boolean!` *required*

Whether the note was edited after it was written. The return page marks these notes "(edited)".

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

The note id.

**image** `String`

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

**imageUrls** `[String!]!` *required*

URLs of every image attached to the note, in order.

**message** `String`

The note text.

**teamMember** `[TeamMember](/docs/api-reference/v3/reference/common/team-member)`

The team member who wrote the note. Null when no team member did, such as a note from an integration, or when they've left the team.

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

**fields**

**email** `String`

Email address. Null when the user has none.

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

m\_us\_… id, the same id the app and MCP tools use.

**name** `String`

Display name. Null when the user hasn't set one.

**supportShiftStatus** `[SupportShiftStatus!](/docs/api-reference/v3/reference/support/support-shift-status)` *required*

The agent's live shift status, worked out when the request runs.

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

**supportWorkSchedule** `[SupportWorkSchedule!](/docs/api-reference/v3/reference/support/support-work-schedule)` *required*

The agent's support working hours. An agent with no saved schedule returns enabled false.

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

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

When the note was last changed.

**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 {
  returnProductCustomsUpdate(customsDescription: "...", hsCode: "...", materialDescription: "...", originCountry: "...", productId: "...", 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.