Returns

The returns flow lets a customer initiate, track and cancel a return for a previously placed order. Eligibility is checked first (per order and per product), then the API generates a return URL that hands off to the returns provider; the resulting returns appear in the customer’s returns history.

Availability is gated by the ORDER_RETURNS site feature. The cancel mutation and most returns history fields require authentication; eligibility checks are available to recognised users.

Checking eligibility for an order

Order.isReturnable validates whether the customer can start a return. With no input it checks every SKU on the order; pass skus to check a subset. The response surfaces both an order-level error (for example SITE_DOES_NOT_SUPPORT_SELF_SERVE) and per-product errors (for example ITEM_EXPIRED or DROPSHIP_ORDER_PRODUCT), so the UI can disable individual items rather than blocking the whole return.

query OrderReturnEligibility {
  customer {
    orders(filter: { orderNumber: "ORD-12345" }, limit: 1) {
      orders {
        orderNumber
        isReturnable(input: { skus: [10000001, 10000002] }) {
          success
          orderError
          productErrors {
            sku
            error
          }
        }
      }
    }
  }
}

Generating a return URL

Once the customer has chosen which items to return, Order.returnUrl produces the URL to send them to. Omit skus to include everything eligible on the order.

query StartReturn {
  customer {
    orders(filter: { orderNumber: "ORD-12345" }, limit: 1) {
      orders {
        returnUrl(input: { skus: [10000001] })
      }
    }
  }
}

Listing the customer’s returns

The paginated returns field replaces the legacy customerReturns array. Each entry exposes the return status, line items, refund value, and the downloadable label when one has been issued.

query CustomerReturns {
  customer {
    returns(offset: 0, limit: 10) {
      total
      hasMore
      customerReturns {
        returnMethod
        trackingLink
        customerReturnInfo {
          returnNumber
          customerReturnStatus
          createdAt
          dispatchedAt
          completedAt
          cancelledAt
          tracking
          totalValue {
            amount
            currency
            displayValue
          }
          refundValue {
            amount
            currency
            displayValue
          }
          shippingPrice {
            amount
            currency
            displayValue
          }
          customerReturnInfoLines {
            product {
              sku
              title
            }
            quantity
          }
        }
        label {
          label {
            url
            mimeType
          }
          deliveryInstructions {
            title {
              value
            }
            generalInstructions {
              value
            }
          }
        }
      }
    }
  }
}

customerReturnStatus progresses through PACKING, IN_TRANSIT, RETURNED, REFUNDING and CANCELLED.

Cancelling a return

Pass the returnNumber from CustomerReturnInfo.

mutation CancelReturn {
  cancelReturn(returnNumber: 98765)
}