Rye Returns API

openapi: 3.0.0
info:
  title: Universal Checkout Betas Returns 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
tags:
- name: Returns
paths:
  /api/v1/returns:
    post:
      operationId: RequestReturn
      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'
      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.'
      summary: Create return
      tags:
      - Returns
      security:
      - bearerAuth:
        - checkout_intents:write
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReturnPostParams'
      x-codeSamples:
      - lang: JavaScript
        source: "import CheckoutIntents from 'checkout-intents';\n\nconst client = new CheckoutIntents({\n  apiKey: process.env['CHECKOUT_INTENTS_API_KEY'], // This is the default and can be omitted\n});\n\nconst _return = await client.returns.create({ orderId: 'orderId', reason: 'defective' });\n\nconsole.log(_return.id);"
      - lang: Python
        source: "import os\nfrom checkout_intents import CheckoutIntents\n\nclient = CheckoutIntents(\n    api_key=os.environ.get(\"CHECKOUT_INTENTS_API_KEY\"),  # This is the default and can be omitted\n)\nreturn_ = client.returns.create(\n    order_id=\"orderId\",\n    reason=\"defective\",\n)\nprint(return_.id)"
      - lang: Java
        source: "package com.rye.example;\n\nimport com.rye.client.CheckoutIntentsClient;\nimport com.rye.client.okhttp.CheckoutIntentsOkHttpClient;\nimport com.rye.models.returns.Return;\nimport com.rye.models.returns.ReturnCreateParams;\nimport com.rye.models.returns.ReturnReason;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        CheckoutIntentsClient client = CheckoutIntentsOkHttpClient.fromEnv();\n\n        ReturnCreateParams params = ReturnCreateParams.builder()\n            .orderId(\"orderId\")\n            .reason(ReturnReason.DEFECTIVE)\n            .build();\n        Return return_ = client.returns().create(params);\n    }\n}"
      - lang: cURL
        source: "curl https://staging.api.rye.com/api/v1/returns \\\n    -H 'Content-Type: application/json' \\\n    -H \"Authorization: Bearer $CHECKOUT_INTENTS_API_KEY\" \\\n    -d '{\n          \"orderId\": \"orderId\",\n          \"reason\": \"defective\"\n        }'"
  /api/v1/returns/{returnId}:
    get:
      operationId: GetReturn
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnResponse'
        '401':
          description: Authentication Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeError'
      description: Fetch a Return by id. Tenancy is scoped to the authenticated developer.
      summary: Get return
      tags:
      - Returns
      security:
      - bearerAuth:
        - checkout_intents:read
      parameters:
      - in: path
        name: returnId
        required: true
        schema:
          type: string
      x-codeSamples:
      - lang: JavaScript
        source: "import CheckoutIntents from 'checkout-intents';\n\nconst client = new CheckoutIntents({\n  apiKey: process.env['CHECKOUT_INTENTS_API_KEY'], // This is the default and can be omitted\n});\n\nconst _return = await client.returns.retrieve('returnId');\n\nconsole.log(_return.id);"
      - lang: Python
        source: "import os\nfrom checkout_intents import CheckoutIntents\n\nclient = CheckoutIntents(\n    api_key=os.environ.get(\"CHECKOUT_INTENTS_API_KEY\"),  # This is the default and can be omitted\n)\nreturn_ = client.returns.retrieve(\n    \"returnId\",\n)\nprint(return_.id)"
      - lang: Java
        source: "package com.rye.example;\n\nimport com.rye.client.CheckoutIntentsClient;\nimport com.rye.client.okhttp.CheckoutIntentsOkHttpClient;\nimport com.rye.models.returns.Return;\nimport com.rye.models.returns.ReturnRetrieveParams;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        CheckoutIntentsClient client = CheckoutIntentsOkHttpClient.fromEnv();\n\n        Return return_ = client.returns().retrieve(\"returnId\");\n    }\n}"
      - lang: cURL
        source: "curl https://staging.api.rye.com/api/v1/returns/$RETURN_ID \\\n    -H \"Authorization: Bearer $CHECKOUT_INTENTS_API_KEY\""
components:
  schemas:
    AuthenticationError:
      properties:
        name:
          type: string
        message:
          type: string
        stack:
          type: string
      required:
      - name
      - message
      type: object
      additionalProperties: false
    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).'
    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.'
    Money:
      properties:
        currencyCode:
          type: string
          example: USD
        amountSubunits:
          type: integer
          format: int32
          example: 1500
      required:
      - currencyCode
      - amountSubunits
      type: object
    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}).'
    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`.'
    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.
    ReturnState:
      type: string
      enum:
      - requested
      - requires_action
      - processing
      - refunded
      - denied
      - failed
      description: "Lifecycle state of a Return:\n\n- `requested` — submitted to the merchant, awaiting approval.\n- `requires_action` — approved; the shopper must ship the items back.\n- `processing` — approved and in flight (items shipped, or no shipping\n  required), awaiting the refund.\n- `refunded` — terminal; the refund has been issued and reconciled.\n- `denied` — terminal; the merchant declined the return.\n- `failed` — terminal; the return could not be completed."
    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).'
    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.
    RuntimeError:
      properties:
        name:
          type: string
        message:
          type: string
        stack:
          type: string
      required:
      - name
      - message
      type: object
      additionalProperties: false
    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.
    FieldErrors:
      properties: {}
      type: object
      additionalProperties:
        properties:
          value: {}
          message:
            type: string
        required:
        - message
        type: object
    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`).'
    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
    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.'
    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.
    ReturnFailureCode:
      type: string
      enum:
      - drawdown_credit_failed
      - merchant_unreachable
      - other
      description: "Discriminator for the `failure` sub-object on a `failed` Return:\n\n- `drawdown_credit_failed` — the merchant refund succeeded but Rye could not\n  credit it back; the refund still reached the shopper.\n- `merchant_unreachable` — the marketplace did not respond before the\n  processing deadline.\n- `other` — an uncategorized failure; see `message` for detail.\n\nSwitch on this exhaustively to handle every failure mode."
    NotFoundError:
      properties:
        name:
          type: string
        message:
          type: string
        stack:
          type: string
      required:
      - name
      - message
      type: object
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Rye API key