> ## Documentation Index > Fetch the complete documentation index at: https://docs-test.rye.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create return > 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. ## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/checkout-intents/openapi.documented.yml post /api/v1/returns openapi: 3.0.0 info: title: Universal Checkout API version: 1.0.5 description: >- Turn any product URL into a completed checkout. Instantly retrieve price, tax, and shipping for any product, and let users buy without ever leaving your native AI experience. View the [Rye API docs](https://docs.rye.com). termsOfService: https://rye.com/terms-of-service license: name: UNLICENSED contact: name: Rye email: dev@rye.com url: https://docs.rye.com servers: - url: https://staging.api.rye.com security: [] paths: /api/v1/returns: post: tags: - Returns summary: Create return description: |- 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. operationId: RequestReturn parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ReturnPostParams' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/ReturnResponse' '401': description: Authentication Failed content: application/json: schema: $ref: '#/components/schemas/AuthenticationError' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/ValidateError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/RuntimeError' security: - bearerAuth: - checkout_intents:write x-codeSamples: - lang: JavaScript source: >- import CheckoutIntents from 'checkout-intents'; const client = new CheckoutIntents({ apiKey: process.env['CHECKOUT_INTENTS_API_KEY'], // This is the default and can be omitted }); const _return = await client.returns.create({ orderId: 'orderId', reason: 'defective' }); console.log(_return.id); - lang: Python source: |- import os from checkout_intents import CheckoutIntents client = CheckoutIntents( api_key=os.environ.get("CHECKOUT_INTENTS_API_KEY"), # This is the default and can be omitted ) return_ = client.returns.create( order_id="orderId", reason="defective", ) print(return_.id) - lang: Java source: |- package com.rye.example; import com.rye.client.CheckoutIntentsClient; import com.rye.client.okhttp.CheckoutIntentsOkHttpClient; import com.rye.models.returns.Return; import com.rye.models.returns.ReturnCreateParams; import com.rye.models.returns.ReturnReason; public final class Main { private Main() {} public static void main(String[] args) { CheckoutIntentsClient client = CheckoutIntentsOkHttpClient.fromEnv(); ReturnCreateParams params = ReturnCreateParams.builder() .orderId("orderId") .reason(ReturnReason.DEFECTIVE) .build(); Return return_ = client.returns().create(params); } } - lang: cURL source: |- curl https://staging.api.rye.com/api/v1/returns \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $CHECKOUT_INTENTS_API_KEY" \ -d '{ "orderId": "orderId", "reason": "defective" }' components: schemas: ReturnPostParams: properties: reason: $ref: '#/components/schemas/ReturnReason' description: Reason for the return. orderId: type: string description: Rye order id (`order_<32 hex>`) of the order being returned. required: - reason - orderId type: object description: |- Request body for `POST /api/v1/returns`. Whole-order returns only — server enumerates the order's line items at create time. ReturnResponse: properties: updatedAt: type: string format: date-time description: When the Return record was last updated. createdAt: type: string format: date-time description: When the Return record was created. refunds: items: $ref: '#/components/schemas/RefundResponse' type: array description: Issued refunds. Present only on `refunded`. failure: $ref: '#/components/schemas/ReturnFailureResponse' description: What went wrong. Present only on `failed`. denial: $ref: '#/components/schemas/ReturnDenialResponse' description: Why the merchant declined the return. Present only on `denied`. nextAction: $ref: '#/components/schemas/NextActionResponse' description: >- What the shopper must do next (e.g. ship the items back). Present once the return is approved — i.e. on `requires_action`, `processing`, and `refunded` — and may be present on `denied` / `failed` if they were approved before terminating. Absent on `requested`. timeline: $ref: '#/components/schemas/ReturnTimeline' description: >- Per-transition timestamps; later stamps fill in as the Return advances. reason: $ref: '#/components/schemas/ReturnReason' description: Reason the return was requested, echoed back from the create call. checkoutIntentId: type: string description: Rye checkout intent id that produced the order being returned. orderId: type: string description: Rye order id (`order_<32 hex>`) this Return was opened against. state: $ref: '#/components/schemas/ReturnState' description: >- Lifecycle state; the discriminator for the optional sub-objects below. id: type: string description: Rye return id (`ret_<32 hex>`). required: - updatedAt - createdAt - timeline - reason - checkoutIntentId - orderId - state - id type: object description: >- 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}). AuthenticationError: properties: name: type: string message: type: string stack: type: string required: - name - message type: object additionalProperties: false ValidateError: properties: name: type: string message: type: string stack: type: string status: type: number format: double fields: $ref: '#/components/schemas/FieldErrors' required: - name - message - status - fields type: object additionalProperties: false RuntimeError: properties: name: type: string message: type: string stack: type: string required: - name - message type: object additionalProperties: false ReturnReason: type: string enum: - defective - wrong_item - unwanted - color - not_as_described - size_too_large - size_too_small - style - other description: >- 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). RefundResponse: properties: shopperRefundTotal: $ref: '#/components/schemas/Money' description: >- Amount returned to the shopper, in the shopper's presentment currency. refundedAt: type: string format: date-time description: When this refund was reconciled. id: type: string description: Rye refund id. required: - shopperRefundTotal - refundedAt - id type: object description: A single refund issued against a `refunded` Return. ReturnFailureResponse: properties: message: type: string description: Human-readable, stable summary of the failure. code: $ref: '#/components/schemas/ReturnFailureCode' description: Machine-readable failure code; switch on this. required: - message - code type: object description: Details of a failed return. ReturnDenialResponse: properties: note: type: string description: Optional human-readable detail from the merchant. reason: $ref: '#/components/schemas/ReturnDeclineReason' description: Machine-readable decline reason. required: - reason type: object description: Why a return was declined by the merchant. NextActionResponse: properties: shipItemsToMerchant: properties: label: $ref: '#/components/schemas/ShippingLabel' required: - label type: object description: >- Prepaid return label. Present only when `type` is `ship_items_to_merchant`. type: $ref: '#/components/schemas/NextActionType' description: Discriminator for the action the shopper must take. required: - type type: object description: >- 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`. ReturnTimeline: properties: failedAt: type: string format: date-time description: When the return failed. Present only on `failed`. deniedAt: type: string format: date-time description: When the return was denied. Present only on `denied`. refundedAt: type: string format: date-time description: >- When the refund was fully reconciled and the Return reached `refunded`. refundIssuedAt: type: string format: date-time description: When the merchant issued the refund on its side. returnApprovedAt: type: string format: date-time description: When the merchant approved the return. requestedAt: type: string format: date-time description: When the return was requested. Always present. required: - requestedAt type: object description: >- 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`). ReturnState: type: string enum: - requested - requires_action - processing - refunded - denied - failed description: |- 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. FieldErrors: properties: {} type: object additionalProperties: properties: value: {} message: type: string required: - message type: object Money: properties: currencyCode: type: string example: USD amountSubunits: type: integer format: int32 example: 1500 required: - currencyCode - amountSubunits type: object ReturnFailureCode: type: string enum: - drawdown_credit_failed - merchant_unreachable - other description: >- 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. ReturnDeclineReason: type: string enum: - final_sale - return_period_ended - other description: |- 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. ShippingLabel: properties: url: type: string description: URL to the downloadable/printable label. required: - url type: object description: A prepaid return shipping label the shopper uses to send items back. NextActionType: type: string enum: - ship_items_to_merchant - no_action_required description: >- 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). securitySchemes: bearerAuth: type: apiKey in: header name: Authorization description: Rye API key ````