Rye Test Helpers API

openapi: 3.0.0
info:
  title: Universal Checkout Betas Test Helpers 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: Test Helpers
paths:
  /api/v1/test-helpers/checkout-intents/{checkoutIntentId}/shipments/advance:
    post:
      operationId: AdvanceShipment
      responses:
        '200':
          description: The advanced simulated shipment state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvanceShipmentResponse'
      description: 'Advance the simulated shipment for a checkout intent. To trigger delayed or

        canceled shipping scenarios, create the checkout intent with a matching

        shipping and delivery test product:

        https://rye.com/docs/api-v2/testing/test-products#shipping-&-delivery'
      summary: Advance simulated shipment
      tags:
      - Test Helpers
      security:
      - bearerAuth:
        - test_helpers:write
      parameters:
      - in: path
        name: checkoutIntentId
        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 response = await client.testHelpers.shipments.advance('checkoutIntentId');\n\nconsole.log(response.shipment);"
      - 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)\nresponse = client.test_helpers.shipments.advance(\n    \"checkoutIntentId\",\n)\nprint(response.shipment)"
      - lang: Java
        source: "package com.rye.example;\n\nimport com.rye.client.CheckoutIntentsClient;\nimport com.rye.client.okhttp.CheckoutIntentsOkHttpClient;\nimport com.rye.models.testhelpers.shipments.ShipmentAdvanceParams;\nimport com.rye.models.testhelpers.shipments.ShipmentAdvanceResponse;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        CheckoutIntentsClient client = CheckoutIntentsOkHttpClient.fromEnv();\n\n        ShipmentAdvanceResponse response = client.testHelpers().shipments().advance(\"checkoutIntentId\");\n    }\n}"
      - lang: cURL
        source: "curl https://staging.api.rye.com/api/v1/test-helpers/checkout-intents/$CHECKOUT_INTENT_ID/shipments/advance \\\n    -X POST \\\n    -H \"Authorization: Bearer $CHECKOUT_INTENTS_API_KEY\""
  /api/v1/test-helpers/returns:
    post:
      operationId: CreateSimulatedReturn
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnResponse'
      description: 'Create a simulated return for an order, then drive it through its lifecycle

        with the approve/deny/refund/fail helpers below.'
      summary: Create simulated return
      tags:
      - Test Helpers
      security:
      - bearerAuth:
        - test_helpers:write
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSimulatedReturnRequest'
      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.testHelpers.returns.create({ orderId: 'orderId' });\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.test_helpers.returns.create(\n    order_id=\"orderId\",\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.testhelpers.returns.ReturnCreateParams;\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            .build();\n        Return return_ = client.testHelpers().returns().create(params);\n    }\n}"
      - lang: cURL
        source: "curl https://staging.api.rye.com/api/v1/test-helpers/returns \\\n    -H 'Content-Type: application/json' \\\n    -H \"Authorization: Bearer $CHECKOUT_INTENTS_API_KEY\" \\\n    -d '{\n          \"orderId\": \"orderId\"\n        }'"
  /api/v1/test-helpers/returns/{returnId}/approve:
    post:
      operationId: ApproveReturn
      responses:
        '200':
          description: The approved simulated return
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnResponse'
      description: Approve a simulated return.
      summary: Approve simulated return
      tags:
      - Test Helpers
      security:
      - bearerAuth:
        - test_helpers:write
      parameters:
      - in: path
        name: returnId
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApproveReturnRequest'
      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.testHelpers.returns.approve('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.test_helpers.returns.approve(\n    return_id=\"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.testhelpers.returns.ReturnApproveParams;\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.testHelpers().returns().approve(\"returnId\");\n    }\n}"
      - lang: cURL
        source: "curl https://staging.api.rye.com/api/v1/test-helpers/returns/$RETURN_ID/approve \\\n    -H 'Content-Type: application/json' \\\n    -H \"Authorization: Bearer $CHECKOUT_INTENTS_API_KEY\" \\\n    -d '{}'"
  /api/v1/test-helpers/returns/{returnId}/deny:
    post:
      operationId: DenyReturn
      responses:
        '200':
          description: The denied simulated return
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnResponse'
      description: Deny a simulated return.
      summary: Deny simulated return
      tags:
      - Test Helpers
      security:
      - bearerAuth:
        - test_helpers:write
      parameters:
      - in: path
        name: returnId
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DenyReturnRequest'
      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.testHelpers.returns.deny('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.test_helpers.returns.deny(\n    return_id=\"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.testhelpers.returns.ReturnDenyParams;\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.testHelpers().returns().deny(\"returnId\");\n    }\n}"
      - lang: cURL
        source: "curl https://staging.api.rye.com/api/v1/test-helpers/returns/$RETURN_ID/deny \\\n    -H 'Content-Type: application/json' \\\n    -H \"Authorization: Bearer $CHECKOUT_INTENTS_API_KEY\" \\\n    -d '{}'"
  /api/v1/test-helpers/returns/{returnId}/refund:
    post:
      operationId: RefundReturn
      responses:
        '200':
          description: The refunded simulated return
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnResponse'
      description: 'Refund a simulated return using the order total as the simulated refund

        amount.'
      summary: Refund simulated return
      tags:
      - Test Helpers
      security:
      - bearerAuth:
        - test_helpers:write
      parameters:
      - in: path
        name: returnId
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundReturnRequest'
      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.testHelpers.returns.refund('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.test_helpers.returns.refund(\n    return_id=\"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.testhelpers.returns.ReturnRefundParams;\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.testHelpers().returns().refund(\"returnId\");\n    }\n}"
      - lang: cURL
        source: "curl https://staging.api.rye.com/api/v1/test-helpers/returns/$RETURN_ID/refund \\\n    -H 'Content-Type: application/json' \\\n    -H \"Authorization: Bearer $CHECKOUT_INTENTS_API_KEY\" \\\n    -d '{}'"
  /api/v1/test-helpers/returns/{returnId}/fail:
    post:
      operationId: FailReturn
      responses:
        '200':
          description: The failed simulated return
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnResponse'
      description: Mark a simulated return as failed.
      summary: Fail simulated return
      tags:
      - Test Helpers
      security:
      - bearerAuth:
        - test_helpers:write
      parameters:
      - in: path
        name: returnId
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FailReturnRequest'
      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.testHelpers.returns.fail('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.test_helpers.returns.fail(\n    return_id=\"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.testhelpers.returns.ReturnFailParams;\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.testHelpers().returns().fail(\"returnId\");\n    }\n}"
      - lang: cURL
        source: "curl https://staging.api.rye.com/api/v1/test-helpers/returns/$RETURN_ID/fail \\\n    -H 'Content-Type: application/json' \\\n    -H \"Authorization: Bearer $CHECKOUT_INTENTS_API_KEY\" \\\n    -d '{}'"
components:
  schemas:
    Shipment:
      $ref: '#/components/schemas/ShipmentUnion'
    ShipmentWithTrackingUnion:
      anyOf:
      - $ref: '#/components/schemas/ShippedShipment'
      - $ref: '#/components/schemas/DeliveredShipment'
      - $ref: '#/components/schemas/DelayedShipment'
      - $ref: '#/components/schemas/OutForDeliveryShipment'
      description: Shipments that have tracking information (shipped, delayed, or delivered states)
      title: With Tracking
    ShipmentTracking:
      properties:
        carrierName:
          type: string
          nullable: true
        number:
          type: string
          nullable: true
        deliveryDate:
          allOf:
          - $ref: '#/components/schemas/DeliveryDate'
          nullable: true
        url:
          type: string
          nullable: true
      required:
      - number
      type: object
    CreateSimulatedReturnRequest:
      properties:
        lineItems:
          items:
            $ref: '#/components/schemas/SimulatedReturnLineItem'
          type: array
          description: Subset of order line items to return. Defaults to every order item at full quantity.
        reason:
          $ref: '#/components/schemas/ReturnReason'
          description: Defaults to `other` when omitted.
        orderId:
          type: string
          description: Rye order id (`oi_<hex>` / `order_<hex>`) to open the simulated return against.
      required:
      - orderId
      type: object
    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.'
    SimulatedReturnLineItem:
      properties:
        quantity:
          type: integer
          format: int32
          description: Units of this line item to return.
          minimum: 1
        orderLineItemId:
          type: string
          description: Order line item id (`oi_<hex>`) to return.
      required:
      - quantity
      - orderLineItemId
      type: object
    Money:
      properties:
        currencyCode:
          type: string
          example: USD
        amountSubunits:
          type: integer
          format: int32
          example: 1500
      required:
      - currencyCode
      - amountSubunits
      type: object
    WithStatus_BaseShipment.ordered_:
      allOf:
      - $ref: '#/components/schemas/BaseShipment'
      - properties:
          status:
            type: string
            enum:
            - ordered
            nullable: false
        required:
        - status
        type: object
    ShipmentStatus:
      type: string
      enum:
      - out_for_delivery
      - delivered
      - shipped
      - canceled
      - delayed
      - ordered
    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.
    ShippedShipment:
      $ref: '#/components/schemas/WithStatus_BaseShipmentWithTracking.shipped_'
      title: Shipped
    DelayedShipment:
      $ref: '#/components/schemas/WithStatus_BaseShipmentWithTracking.delayed_'
      title: Delayed
    WithStatus_BaseShipmentWithTracking.shipped_:
      allOf:
      - $ref: '#/components/schemas/BaseShipmentWithTracking'
      - properties:
          status:
            type: string
            enum:
            - shipped
            nullable: false
        required:
        - status
        type: object
    AdvanceShipmentResponse:
      properties:
        shipment:
          $ref: '#/components/schemas/Shipment'
      required:
      - shipment
      type: object
    TrackingEvent:
      properties:
        status:
          $ref: '#/components/schemas/ShipmentStatus'
        location:
          $ref: '#/components/schemas/EventLocation'
        timestamp:
          allOf:
          - $ref: '#/components/schemas/TrackingEventTimestamp'
          nullable: true
        description:
          type: string
          nullable: true
      required:
      - status
      - location
      - timestamp
      - description
      type: object
    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."
    TrackingEventTimestamp:
      properties:
        local:
          type: string
          description: ISO 8601 string with timezone offset, e.g. "2025-02-05T17:02:00.000-05:00"
        utc:
          type: string
          format: date-time
          description: UTC timestamp
      required:
      - local
      - utc
      type: object
    CanceledShipment:
      $ref: '#/components/schemas/WithStatus_BaseShipment.canceled_'
      title: Canceled
    ShippingDetails:
      properties:
        trackingEvents:
          items:
            $ref: '#/components/schemas/TrackingEvent'
          type: array
        shippedAt:
          type: string
          format: date-time
        tracking:
          $ref: '#/components/schemas/ShipmentTracking'
        externalId:
          type: string
          description: The external ID is provided by the marketplace and matches the shipment to their system.
      required:
      - trackingEvents
      - shippedAt
      - tracking
      - externalId
      type: object
    ShipmentUnion:
      anyOf:
      - $ref: '#/components/schemas/ShipmentWithTrackingUnion'
      - $ref: '#/components/schemas/ShipmentWithoutTrackingUnion'
    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).'
    WithStatus_BaseShipmentWithTracking.delayed_:
      allOf:
      - $ref: '#/components/schemas/BaseShipmentWithTracking'
      - properties:
          status:
            type: string
            enum:
            - delayed
            nullable: false
        required:
        - status
        type: object
    ShipmentWithoutTrackingUnion:
      anyOf:
      - $ref: '#/components/schemas/OrderedShipment'
      - $ref: '#/components/schemas/CanceledShipment'
      description: Shipments without tracking information
      title: Without Tracking
    BaseShipment:
      properties:
        updatedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        marketplaceOrderId:
          type: string
        checkoutIntentId:
          type: string
        id:
          type: string
      required:
      - updatedAt
      - createdAt
      - marketplaceOrderId
      - checkoutIntentId
      - id
      type: object
    RefundReturnRequest:
      properties:
        costBearer:
          $ref: '#/components/schemas/CostBearer'
          description: Defaults to `shopper`.
      type: object
    OutForDeliveryShipment:
      $ref: '#/components/schemas/WithStatus_BaseShipmentWithTracking.out_for_delivery_'
      title: Out for Delivery
    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.
    DenyReturnRequest:
      properties:
        note:
          type: string
        reason:
          $ref: '#/components/schemas/ReturnDeclineReason'
          description: Defaults to `other`.
      type: object
    OrderedShipment:
      $ref: '#/components/schemas/WithStatus_BaseShipment.ordered_'
      title: Ordered
    FailReturnRequest:
      properties:
        note:
          type: string
      type: object
    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.
    BaseShipmentWithTracking:
      allOf:
      - $ref: '#/components/schemas/BaseShipment'
      - $ref: '#/components/schemas/ShippingDetails'
    EventLocation:
      properties:
        country:
          type: string
          nullable: true
        province:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
      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`).'
    CostBearer:
      type: string
      enum:
      - shopper
      - developer
      - rye
      description: "Who absorbs the merchant-retained shortfall `S` on a return — the gap\nbetween what the merchant was charged and what it refunded (restocking fees,\nreturn shipping, partials). Selected per-developer via the\n`refundCostBearingStrategy` flag and resolved into this enum by the\ndurable-workers cost-policy adapter.\n\n- `shopper` (default): the shopper eats `S`. Both anchors reconstruct from\n  the merchant refund, so a short merchant refund shrinks the shopper refund\n  and developer credit in lockstep.\n- `developer`: the shopper is made whole at the original charge `C`; the\n  developer's deposit is credited only what Rye recovered (the merchant\n  anchor), so the developer absorbs `S`.\n- `rye`: the shopper is made whole at `C` and the developer's full drawdown\n  debit `D` is restored, so Rye absorbs `S`."
    WithStatus_BaseShipmentWithTracking.delivered_:
      allOf:
      - $ref: '#/components/schemas/BaseShipmentWithTracking'
      - properties:
          status:
            type: string
            enum:
            - delivered
            nullable: false
        required:
        - status
        type: object
    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."
    ApproveReturnRequest:
      properties:
        nextAction:
          $ref: '#/components/schemas/NextActionType'
          description: '`ship_items_to_merchant` lands the return in `requires_action` with a stub

            shipping label; `no_action_required` lands it directly in `processing`.

            Defaults to `ship_items_to_merchant`.'
      type: object
    WithStatus_BaseShipmentWithTracking.out_for_delivery_:
      allOf:
      - $ref: '#/components/schemas/BaseShipmentWithTracking'
      - properties:
          status:
            type: string
            enum:
            - out_for_delivery
            nullable: false
        required:
        - status
        type: object
    DeliveredShipment:
      allOf:
      - $ref: '#/components/schemas/WithStatus_BaseShipmentWithTracking.delivered_'
      - properties:
          deliveredAt:
            type: string
            format: date-time
        required:
        

# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/rye/refs/heads/main/openapi/rye-test-helpers-api-openapi.yml