Rye Shipments API

openapi: 3.0.0
info:
  title: Universal Checkout Betas Shipments 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: Shipments
paths:
  /api/v1/shipments:
    get:
      operationId: ListShipments
      responses:
        '200':
          description: Paginated shipments response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentsListResponse'
        '401':
          description: Authentication Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateError'
      description: 'Retrieve a paginated list of shipments


        Enables developers to query shipments associated with their account, with filters and cursor-based pagination.'
      summary: List shipments
      tags:
      - Shipments
      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
      - in: query
        name: ids
        required: false
        schema:
          default: []
          type: array
          items:
            type: string
      - in: query
        name: status
        required: false
        schema:
          default: []
          type: array
          items:
            $ref: '#/components/schemas/ShipmentStatus'
      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 shipment of client.shipments.list()) {\n  console.log(shipment);\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.shipments.list()\npage = page.data[0]\nprint(page)"
      - lang: Java
        source: "package com.rye.example;\n\nimport com.rye.client.CheckoutIntentsClient;\nimport com.rye.client.okhttp.CheckoutIntentsOkHttpClient;\nimport com.rye.models.shipments.ShipmentListPage;\nimport com.rye.models.shipments.ShipmentListParams;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        CheckoutIntentsClient client = CheckoutIntentsOkHttpClient.fromEnv();\n\n        ShipmentListPage page = client.shipments().list();\n    }\n}"
      - lang: cURL
        source: "curl https://staging.api.rye.com/api/v1/shipments \\\n    -H \"Authorization: Bearer $CHECKOUT_INTENTS_API_KEY\""
  /api/v1/shipments/{id}:
    get:
      operationId: GetShipment
      responses:
        '200':
          description: Shipment information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
        '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 a shipment by id


        Returns shipment information if the lookup succeeds.'
      summary: Retrieve shipment by id
      tags:
      - Shipments
      security:
      - bearerAuth:
        - checkout_intents:read
      parameters:
      - description: The id of the shipment to look up
        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 shipment = await client.shipments.retrieve('id');\n\nconsole.log(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)\nshipment = client.shipments.retrieve(\n    \"id\",\n)\nprint(shipment)"
      - lang: Java
        source: "package com.rye.example;\n\nimport com.rye.client.CheckoutIntentsClient;\nimport com.rye.client.okhttp.CheckoutIntentsOkHttpClient;\nimport com.rye.models.shipments.Shipment;\nimport com.rye.models.shipments.ShipmentRetrieveParams;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        CheckoutIntentsClient client = CheckoutIntentsOkHttpClient.fromEnv();\n\n        Shipment shipment = client.shipments().retrieve(\"id\");\n    }\n}"
      - lang: cURL
        source: "curl https://staging.api.rye.com/api/v1/shipments/$ID \\\n    -H \"Authorization: Bearer $CHECKOUT_INTENTS_API_KEY\""
components:
  schemas:
    Shipment:
      $ref: '#/components/schemas/ShipmentUnion'
    AuthenticationError:
      properties:
        name:
          type: string
        message:
          type: string
        stack:
          type: string
      required:
      - name
      - message
      type: object
      additionalProperties: false
    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
    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
    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
    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
    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'
    WithStatus_BaseShipmentWithTracking.delayed_:
      allOf:
      - $ref: '#/components/schemas/BaseShipmentWithTracking'
      - properties:
          status:
            type: string
            enum:
            - delayed
            nullable: false
        required:
        - status
        type: object
    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
    ShipmentWithoutTrackingUnion:
      anyOf:
      - $ref: '#/components/schemas/OrderedShipment'
      - $ref: '#/components/schemas/CanceledShipment'
      description: Shipments without tracking information
      title: Without Tracking
    OutForDeliveryShipment:
      $ref: '#/components/schemas/WithStatus_BaseShipmentWithTracking.out_for_delivery_'
      title: Out for Delivery
    OrderedShipment:
      $ref: '#/components/schemas/WithStatus_BaseShipment.ordered_'
      title: Ordered
    FieldErrors:
      properties: {}
      type: object
      additionalProperties:
        properties:
          value: {}
          message:
            type: string
        required:
        - message
        type: object
    BaseShipmentWithTracking:
      allOf:
      - $ref: '#/components/schemas/BaseShipment'
      - $ref: '#/components/schemas/ShippingDetails'
    ShipmentsListResponse:
      properties:
        pageInfo:
          properties:
            endCursor:
              type: string
            startCursor:
              type: string
            hasPreviousPage:
              type: boolean
            hasNextPage:
              type: boolean
          required:
          - hasPreviousPage
          - hasNextPage
          type: object
        data:
          items:
            $ref: '#/components/schemas/Shipment'
          type: array
      required:
      - pageInfo
      - data
      type: object
    EventLocation:
      properties:
        country:
          type: string
          nullable: true
        province:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
      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
    WithStatus_BaseShipmentWithTracking.delivered_:
      allOf:
      - $ref: '#/components/schemas/BaseShipmentWithTracking'
      - properties:
          status:
            type: string
            enum:
            - delivered
            nullable: false
        required:
        - status
        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:
        - deliveredAt
        type: object
      title: Delivered
    NotFoundError:
      properties:
        name:
          type: string
        message:
          type: string
        stack:
          type: string
      required:
      - name
      - message
      type: object
      additionalProperties: false
    WithStatus_BaseShipment.canceled_:
      allOf:
      - $ref: '#/components/schemas/BaseShipment'
      - properties:
          status:
            type: string
            enum:
            - canceled
            nullable: false
        required:
        - status
        type: object
    DeliveryDate:
      properties:
        estimated:
          type: string
          format: date-time
      required:
      - estimated
      type: object
  securitySchemes:
    bearerAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Rye API key