---
title: "Create return"
method: POST
path: "/api/v1/returns"
tags: ["Returns"]
---

# Create return

`POST /api/v1/returns`

Create a return for a completed order. Whole-order returns only — the
order's line items are enumerated for you. The return is submitted for
approval and then progresses asynchronously toward the refund; poll the
returned return id (or listen for webhooks) to follow its state.

## Request body

- ReturnPostParams — Request body for `POST /api/v1/returns`. Whole-order returns only — server enumerates the order's line items at create time.
  - `reason` 'defective' | 'wrong_item' | 'unwanted' | 'color' | 'not_as_described' | 'size_too_large' | 'size_too_small' | 'style' | 'other', required — Reason a shopper is returning an order, supplied on the create-return call: `defective` (arrived damaged or faulty), `wrong_item` (not what was ordered), `unwanted` (changed their mind), `color` / `size_too_large` / `size_too_small` / `style` (wrong color, size, or style), `not_as_described` (differs from the listing), and `other` (anything else).
  - `orderId` string, required — Rye order id (`order_<32 hex>`) of the order being returned.

## Response `201`

Created

- ReturnResponse — A single Return record. The `state` discriminator tells you which of `denial`, `failure`, and `refunds` is populated; `nextAction` is set once the Return is approved (see {@link NextActionResponse}).
  - `updatedAt` string, date-time, required — When the Return record was last updated.
  - `createdAt` string, date-time, required — When the Return record was created.
  - `refunds` RefundResponse[] — Issued refunds. Present only on `refunded`.
    - `shopperRefundTotal` Money, required
      - `currencyCode` string, required
      - `amountSubunits` integer, required
    - `refundedAt` string, date-time, required — When this refund was reconciled.
    - `id` string, required — Rye refund id.
  - `failure` ReturnFailureResponse — Details of a failed return.
    - `message` string, required — Human-readable, stable summary of the failure.
    - `code` 'drawdown_credit_failed' | 'merchant_unreachable' | 'other', required — Discriminator for the `failure` sub-object on a `failed` Return: - `drawdown_credit_failed` — the merchant refund succeeded but Rye could not credit it back; the refund still reached the shopper. - `merchant_unreachable` — the marketplace did not respond before the processing deadline. - `other` — an uncategorized failure; see `message` for detail. Switch on this exhaustively to handle every failure mode.
  - `denial` ReturnDenialResponse — Why a return was declined by the merchant.
    - `note` string — Optional human-readable detail from the merchant.
    - `reason` 'final_sale' | 'return_period_ended' | 'other', required — Why a merchant declined a return: - `final_sale` — the item was sold as final sale and is not returnable. - `return_period_ended` — the return window had already closed. - `other` — declined for another reason; see the accompanying note.
  - `nextAction` NextActionResponse — What the shopper has to do next to complete the return. Present once the Return is approved. `type` is the discriminator: `ship_items_to_merchant` carries the matching `shipItemsToMerchant` payload (a prepaid label); `no_action_required` means the merchant approved a keep-the-item / no-ship return and the shopper just waits for the refund (no payload). The `requires_action` state is reached only for `ship_items_to_merchant`; a `no_action_required` approval skips straight to `processing`.
    - `shipItemsToMerchant` object — Prepaid return label. Present only when `type` is `ship_items_to_merchant`.
      - `label` ShippingLabel, required — A prepaid return shipping label the shopper uses to send items back.
        - `url` string, required — URL to the downloadable/printable label.
    - `type` 'ship_items_to_merchant' | 'no_action_required', required — Discriminator for {@link NextActionResponse }: `ship_items_to_merchant` (the shopper must return the items with the provided label) or `no_action_required` (a keep-the-item / no-ship approval — the shopper just waits for the refund).
  - `timeline` ReturnTimeline, required — Per-transition timestamps for a Return. `requestedAt` is always set; the rest fill in as the Return advances and reflect the path it actually took (a `denied` Return has `deniedAt` but never `refundedAt`).
    - `failedAt` string, date-time — When the return failed. Present only on `failed`.
    - `deniedAt` string, date-time — When the return was denied. Present only on `denied`.
    - `refundedAt` string, date-time — When the refund was fully reconciled and the Return reached `refunded`.
    - `refundIssuedAt` string, date-time — When the merchant issued the refund on its side.
    - `returnApprovedAt` string, date-time — When the merchant approved the return.
    - `requestedAt` string, date-time, required — When the return was requested. Always present.
  - `reason` 'defective' | 'wrong_item' | 'unwanted' | 'color' | 'not_as_described' | 'size_too_large' | 'size_too_small' | 'style' | 'other', required — Reason a shopper is returning an order, supplied on the create-return call: `defective` (arrived damaged or faulty), `wrong_item` (not what was ordered), `unwanted` (changed their mind), `color` / `size_too_large` / `size_too_small` / `style` (wrong color, size, or style), `not_as_described` (differs from the listing), and `other` (anything else).
  - `checkoutIntentId` string, required — Rye checkout intent id that produced the order being returned.
  - `orderId` string, required — Rye order id (`order_<32 hex>`) this Return was opened against.
  - `state` 'requested' | 'requires_action' | 'processing' | 'refunded' | 'denied' | 'failed', required — Lifecycle state of a Return: - `requested` — submitted to the merchant, awaiting approval. - `requires_action` — approved; the shopper must ship the items back. - `processing` — approved and in flight (items shipped, or no shipping required), awaiting the refund. - `refunded` — terminal; the refund has been issued and reconciled. - `denied` — terminal; the merchant declined the return. - `failed` — terminal; the return could not be completed.
  - `id` string, required — Rye return id (`ret_<32 hex>`).

## Other responses

- `401` — Authentication Failed
- `409` — Conflict
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.dev/rye-com/apis/universal-checkout-api.md) · [All operations](https://skmtc.dev/rye-com/apis/universal-checkout-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/rye-com/universal-checkout-api/revisions/175c7f9e090e/schema)