openapi: 3.0.0
info:
  title: Universal Checkout Betas Orders 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: Orders
paths:
  /api/v1/orders:
    get:
      operationId: ListOrders
      responses:
        '200':
          description: Paginated list of orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrdersListResponse'
        '401':
          description: Authentication Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateError'
      description: List orders for the authenticated developer with cursor-based pagination.
      summary: List orders
      tags:
      - Orders
      security:
      - bearerAuth:
        - checkout_intents:read
      parameters:
      - description: Maximum number of results to return (default 100)
        in: query
        name: limit
        required: false
        schema:
          format: int32
          type: integer
          minimum: 1
          maximum: 100
        example: 20
      - in: query
        name: after
        required: false
        schema:
          type: string
      - in: query
        name: before
        required: false
        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\n// Automatically fetches more pages as needed.\nfor await (const order of client.orders.list()) {\n  console.log(order.id);\n}"
      - 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)\npage = client.orders.list()\npage = page.data[0]\nprint(page.id)"
      - lang: Java
        source: "package com.rye.example;\n\nimport com.rye.client.CheckoutIntentsClient;\nimport com.rye.client.okhttp.CheckoutIntentsOkHttpClient;\nimport com.rye.models.orders.OrderListPage;\nimport com.rye.models.orders.OrderListParams;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        CheckoutIntentsClient client = CheckoutIntentsOkHttpClient.fromEnv();\n\n        OrderListPage page = client.orders().list();\n    }\n}"
      - lang: cURL
        source: "curl https://staging.api.rye.com/api/v1/orders \\\n    -H \"Authorization: Bearer $CHECKOUT_INTENTS_API_KEY\""
  /api/v1/orders/{id}:
    get:
      operationId: GetOrder
      responses:
        '200':
          description: The order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '401':
          description: Authentication Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
      description: Retrieve an order by id.
      summary: Get order
      tags:
      - Orders
      security:
      - bearerAuth:
        - checkout_intents:read
      parameters:
      - description: The order id
        in: path
        name: id
        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 order = await client.orders.retrieve('id');\n\nconsole.log(order.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)\norder = client.orders.retrieve(\n    \"id\",\n)\nprint(order.id)"
      - lang: Java
        source: "package com.rye.example;\n\nimport com.rye.client.CheckoutIntentsClient;\nimport com.rye.client.okhttp.CheckoutIntentsOkHttpClient;\nimport com.rye.models.orders.Order;\nimport com.rye.models.orders.OrderRetrieveParams;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        CheckoutIntentsClient client = CheckoutIntentsOkHttpClient.fromEnv();\n\n        Order order = client.orders().retrieve(\"id\");\n    }\n}"
      - lang: cURL
        source: "curl https://staging.api.rye.com/api/v1/orders/$ID \\\n    -H \"Authorization: Bearer $CHECKOUT_INTENTS_API_KEY\""
  /api/v1/orders/{id}/cancel:
    post:
      operationId: CancelOrder
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cancellation'
        '401':
          description: Authentication Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancellationNotApplicableError'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateError'
      description: 'Request cancellation of an order.


        Order cancellations are subject to each merchant''s cancellation policy.'
      summary: Cancel order
      tags:
      - Orders
      security:
      - bearerAuth:
        - checkout_intents:write
      parameters:
      - description: The order id
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        description: The cancellation reason (code + optional note)
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCancelParams'
              description: ''
      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 cancellation = await client.orders.cancel('id', {\n  reason: { code: 'requested_by_customer' },\n});\n\nconsole.log(cancellation);"
      - 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)\ncancellation = client.orders.cancel(\n    id=\"id\",\n    reason={\n        \"code\": \"requested_by_customer\"\n    },\n)\nprint(cancellation)"
      - lang: Java
        source: "package com.rye.example;\n\nimport com.rye.client.CheckoutIntentsClient;\nimport com.rye.client.okhttp.CheckoutIntentsOkHttpClient;\nimport com.rye.models.orders.Cancellation;\nimport com.rye.models.orders.OrderCancelParams;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        CheckoutIntentsClient client = CheckoutIntentsOkHttpClient.fromEnv();\n\n        OrderCancelParams params = OrderCancelParams.builder()\n            .id(\"id\")\n            .reason(OrderCancelParams.Reason.builder()\n                .code(OrderCancelParams.Reason.Code.REQUESTED_BY_CUSTOMER)\n                .build())\n            .build();\n        Cancellation cancellation = client.orders().cancel(params);\n    }\n}"
      - lang: cURL
        source: "curl https://staging.api.rye.com/api/v1/orders/$ID/cancel \\\n    -H 'Content-Type: application/json' \\\n    -H \"Authorization: Bearer $CHECKOUT_INTENTS_API_KEY\" \\\n    -d '{\n          \"reason\": {\n            \"code\": \"requested_by_customer\"\n          }\n        }'"
components:
  schemas:
    AuthenticationError:
      properties:
        name:
          type: string
        message:
          type: string
        stack:
          type: string
      required:
      - name
      - message
      type: object
      additionalProperties: false
    CompletedCancellation:
      allOf:
      - $ref: '#/components/schemas/BaseCancellation'
      - properties:
          state:
            type: string
            enum:
            - completed
            nullable: false
        required:
        - state
        type: object
    EnumValues_typeofCancellationRejectionCode_:
      type: string
      enum:
      - cancellation_window_expired
      - cancellation_disabled
      - order_already_cancelled
      - order_already_fulfilled
      - order_value_above_limit
      description: The value-union of a {@link stringEnum} — e.g. `'red' | 'blue'`.
    CancellationReasonCode:
      type: string
      enum:
      - requested_by_customer
      - fraud
      - inventory
      - payment_issue
      - staff_error
      - other
    RequestedCancellation:
      allOf:
      - $ref: '#/components/schemas/BaseCancellation'
      - properties:
          state:
            type: string
            enum:
            - requested
            nullable: false
        required:
        - state
        type: object
    CancellationDenialReasonCode:
      type: string
      enum:
      - other
      - already_shipped
      - non_cancellable_item
      - cancellation_window_expired
    CancellationNotApplicableError:
      description: 'The order cannot be programmatically cancelled — the store has no active

        integration, or the store''s cancellation policy disallows it (disabled,

        outside the allowed window, already cancelled/fulfilled, over the value

        limit). Surfaced as a 409 carrying a machine-readable `code`; no cancellation

        record is written.'
      properties:
        name:
          type: string
        message:
          type: string
        stack:
          type: string
        code:
          $ref: '#/components/schemas/CancellationNotApplicableCode'
      required:
      - name
      - message
      - code
      type: object
      additionalProperties: false
    Cancellation:
      anyOf:
      - $ref: '#/components/schemas/RequestedCancellation'
      - $ref: '#/components/schemas/CompletedCancellation'
      - $ref: '#/components/schemas/DeniedCancellation'
    CancellationReason:
      properties:
        message:
          type: string
          description: 'Optional free-text note explaining the cancellation, forwarded to the

            merchant when possible.'
          maxLength: 256
        code:
          $ref: '#/components/schemas/CancellationReasonCode'
      required:
      - code
      type: object
    OrderCancelParams:
      properties:
        reason:
          $ref: '#/components/schemas/CancellationReason'
      required:
      - reason
      type: object
      description: 'Body for `POST /orders/{id}/cancel`. The order id comes from the URL, so the

        caller only supplies the cancellation reason (code + optional note).'
    FieldErrors:
      properties: {}
      type: object
      additionalProperties:
        properties:
          value: {}
          message:
            type: string
        required:
        - message
        type: object
    OrdersListResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/OrderResponse'
          type: array
        pageInfo:
          properties:
            endCursor:
              type: string
            startCursor:
              type: string
            hasPreviousPage:
              type: boolean
            hasNextPage:
              type: boolean
          required:
          - hasPreviousPage
          - hasNextPage
          type: object
      required:
      - data
      - pageInfo
      type: object
      additionalProperties: false
    CancellationNotApplicableCode:
      anyOf:
      - $ref: '#/components/schemas/CancellationRejectionCode'
      - type: string
        enum:
        - store_not_integrated
      description: 'Why a programmatic cancellation was rejected. `store_not_integrated` is our

        own pre-policy gate (not a Shopify store, or no active integration); the

        remaining codes come straight from the store cancellation policy evaluation

        in `@rye-com/rye-data-layer` (disabled, window expired, already

        cancelled/fulfilled, order value above limit).'
    BaseCancellation:
      properties:
        reason:
          $ref: '#/components/schemas/CancellationReason'
        marketplaceOrderId:
          type: string
        checkoutIntentId:
          type: string
        createdAt:
          type: string
          format: date-time
        id:
          type: string
      required:
      - reason
      - marketplaceOrderId
      - checkoutIntentId
      - createdAt
      - id
      type: object
    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
    DeniedCancellation:
      allOf:
      - $ref: '#/components/schemas/BaseCancellation'
      - properties:
          denialReason:
            $ref: '#/components/schemas/CancellationDenialReason'
          state:
            type: string
            enum:
            - denied
            nullable: false
        required:
        - denialReason
        - state
        type: object
    OrderResponse:
      description: 'Represents a completed order. Orders are created after a checkout intent reaches

        the `completed` state.'
      properties:
        id:
          type: string
        checkoutIntentId:
          type: string
          description: ID of the checkout intent that was responsible for creating this order.
          example: ci_aaa8af5c5aae4c0e8ef0172c26c65c13
        createdAt:
          type: string
          description: Timestamp the order was persisted to Rye.
          example: '2026-03-25T00:00:00Z'
        updatedAt:
          type: string
          description: Timestamp the order was last updated at
          example: '2026-03-27T00:00:00Z'
        referenceId:
          type: string
          description: 'The `referenceId` you supplied on the checkout intent, echoed back so you

            can reconcile this order against your own records. Absent when none was

            supplied.'
          example: order-1234
        cancellation:
          allOf:
          - $ref: '#/components/schemas/Cancellation'
          nullable: true
          description: 'The cancellation for this order, or `null` if none has been requested.

            Populated by joining the separate cancellations collection on the order''s

            marketplace order id.'
      required:
      - id
      - checkoutIntentId
      - createdAt
      - updatedAt
      - cancellation
      type: object
      additionalProperties: false
    CancellationRejectionCode:
      $ref: '#/components/schemas/EnumValues_typeofCancellationRejectionCode_'
      description: "Reason code for why automatic cancellation is not available/allowed for an order.\n\nNaming convention — `<subject>_<state>`, two namespaces:\n  - `cancellation_*` — about the cancellation policy/feature itself.\n  - `order_*`        — about the order's own state or attributes."
    CancellationDenialReason:
      properties:
        code:
          $ref: '#/components/schemas/CancellationDenialReasonCode'
        message:
          type: string
      required:
      - code
      - message
      type: object
    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