Rye Products API

openapi: 3.0.0
info:
  title: Universal Checkout Betas Products 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: Products
paths:
  /api/v1/products/lookup:
    get:
      operationId: Lookup
      responses:
        '200':
          description: Product information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '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'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeError'
      description: Lookup a product's information by URL.
      summary: Lookup product
      tags:
      - Products
      security:
      - bearerAuth:
        - products:read
      parameters:
      - in: query
        name: url
        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 product = await client.products.lookup({ url: 'url' });\n\nconsole.log(product.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)\nproduct = client.products.lookup(\n    url=\"url\",\n)\nprint(product.id)"
      - lang: Java
        source: "package com.rye.example;\n\nimport com.rye.client.CheckoutIntentsClient;\nimport com.rye.client.okhttp.CheckoutIntentsOkHttpClient;\nimport com.rye.models.products.Product;\nimport com.rye.models.products.ProductLookupParams;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        CheckoutIntentsClient client = CheckoutIntentsOkHttpClient.fromEnv();\n\n        ProductLookupParams params = ProductLookupParams.builder()\n            .url(\"url\")\n            .build();\n        Product product = client.products().lookup(params);\n    }\n}"
      - lang: cURL
        source: "curl https://staging.api.rye.com/api/v1/products/lookup \\\n    -H \"Authorization: Bearer $CHECKOUT_INTENTS_API_KEY\""
  /api/v1/products/subscriptions:
    get:
      operationId: ListSubscriptions
      responses:
        '200':
          description: Product subscriptions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListProductSubscriptionsResponse'
        '401':
          description: Authentication Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeError'
      description: Retrieve product subscription rules.
      summary: List product subscriptions
      tags:
      - Products
      security:
      - bearerAuth:
        - products:read
      parameters: []
      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.products.listSubscriptions();\n\nconsole.log(response.data);"
      - 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.products.list_subscriptions()\nprint(response.data)"
      - lang: Java
        source: "package com.rye.example;\n\nimport com.rye.client.CheckoutIntentsClient;\nimport com.rye.client.okhttp.CheckoutIntentsOkHttpClient;\nimport com.rye.models.products.ProductListSubscriptionsParams;\nimport com.rye.models.products.ProductListSubscriptionsResponse;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        CheckoutIntentsClient client = CheckoutIntentsOkHttpClient.fromEnv();\n\n        ProductListSubscriptionsResponse response = client.products().listSubscriptions();\n    }\n}"
      - lang: cURL
        source: "curl https://staging.api.rye.com/api/v1/products/subscriptions \\\n    -H \"Authorization: Bearer $CHECKOUT_INTENTS_API_KEY\""
  /api/v1/products/subscribe:
    post:
      operationId: Subscribe
      responses:
        '200':
          description: Product subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductSubscriptionResponse'
        '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'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeError'
      description: Subscribe to product events from a store.
      summary: Subscribe to product events
      tags:
      - Products
      security:
      - bearerAuth:
        - products:write
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductSubscriptionRequest'
      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 productSubscription = await client.products.subscribe({\n  type: 'store',\n  url: 'https://store.com',\n});\n\nconsole.log(productSubscription);"
      - 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)\nproduct_subscription = client.products.subscribe(\n    type=\"store\",\n    url=\"https://store.com\",\n)\nprint(product_subscription)"
      - lang: Java
        source: "package com.rye.example;\n\nimport com.rye.client.CheckoutIntentsClient;\nimport com.rye.client.okhttp.CheckoutIntentsOkHttpClient;\nimport com.rye.models.products.ProductSubscribeParams;\nimport com.rye.models.products.ProductSubscription;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        CheckoutIntentsClient client = CheckoutIntentsOkHttpClient.fromEnv();\n\n        ProductSubscribeParams params = ProductSubscribeParams.builder()\n            .type(ProductSubscribeParams.Type.STORE)\n            .url(\"https://store.com\")\n            .build();\n        ProductSubscription productSubscription = client.products().subscribe(params);\n    }\n}"
      - lang: cURL
        source: "curl https://staging.api.rye.com/api/v1/products/subscribe \\\n    -H 'Content-Type: application/json' \\\n    -H \"Authorization: Bearer $CHECKOUT_INTENTS_API_KEY\" \\\n    -d '{\n          \"type\": \"store\",\n          \"url\": \"https://store.com\"\n        }'"
  /api/v1/products/unsubscribe:
    post:
      operationId: Unsubscribe
      responses:
        '200':
          description: Product subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductSubscriptionResponse'
        '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'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeError'
      description: Unsubscribe from product events from a store.
      summary: Unsubscribe from product events
      tags:
      - Products
      security:
      - bearerAuth:
        - products:write
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductSubscriptionRequest'
      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 productSubscription = await client.products.unsubscribe({\n  type: 'store',\n  url: 'https://store.com',\n});\n\nconsole.log(productSubscription);"
      - 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)\nproduct_subscription = client.products.unsubscribe(\n    type=\"store\",\n    url=\"https://store.com\",\n)\nprint(product_subscription)"
      - lang: Java
        source: "package com.rye.example;\n\nimport com.rye.client.CheckoutIntentsClient;\nimport com.rye.client.okhttp.CheckoutIntentsOkHttpClient;\nimport com.rye.models.products.ProductSubscription;\nimport com.rye.models.products.ProductUnsubscribeParams;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        CheckoutIntentsClient client = CheckoutIntentsOkHttpClient.fromEnv();\n\n        ProductUnsubscribeParams params = ProductUnsubscribeParams.builder()\n            .type(ProductUnsubscribeParams.Type.STORE)\n            .url(\"https://store.com\")\n            .build();\n        ProductSubscription productSubscription = client.products().unsubscribe(params);\n    }\n}"
      - lang: cURL
        source: "curl https://staging.api.rye.com/api/v1/products/unsubscribe \\\n    -H 'Content-Type: application/json' \\\n    -H \"Authorization: Bearer $CHECKOUT_INTENTS_API_KEY\" \\\n    -d '{\n          \"type\": \"store\",\n          \"url\": \"https://store.com\"\n        }'"
components:
  schemas:
    AuthenticationError:
      properties:
        name:
          type: string
        message:
          type: string
        stack:
          type: string
      required:
      - name
      - message
      type: object
      additionalProperties: false
    VariantDimension:
      properties:
        values:
          items:
            type: string
          type: array
        label:
          type: string
      required:
      - values
      - label
      type: object
    ProductVariant:
      properties:
        availability:
          $ref: '#/components/schemas/ProductAvailability'
        images:
          items:
            $ref: '#/components/schemas/ProductImage'
          type: array
        price:
          $ref: '#/components/schemas/Money'
        dimensions:
          items:
            $ref: '#/components/schemas/VariantSelection'
          type: array
        name:
          type: string
          nullable: true
        sku:
          type: string
          nullable: true
        id:
          type: string
          nullable: true
      required:
      - availability
      - images
      - price
      - dimensions
      - name
      - sku
      - id
      type: object
    ProductSubscriptionProductResponse:
      properties:
        type:
          type: string
          enum:
          - product
          nullable: false
          description: Scope of the subscription change.
        id:
          type: string
          description: Product id.
        url:
          type: string
          description: Product subscription URL.
        subscribed:
          type: boolean
          description: Whether the resolved product is subscribed after the mutation.
      required:
      - type
      - id
      - url
      - subscribed
      type: object
      additionalProperties: false
    TooManyRequestsError:
      properties:
        name:
          type: string
        message:
          type: string
        stack:
          type: string
        retryAfter:
          type: string
      required:
      - name
      - message
      type: object
      additionalProperties: false
    ProductImage:
      properties:
        isFeatured:
          type: boolean
          example: true
        url:
          type: string
          example: https://example.com/images/product-123.jpg
      required:
      - isFeatured
      - url
      type: object
    ProductSubscriptionResponse:
      anyOf:
      - $ref: '#/components/schemas/ProductSubscriptionProductResponse'
      - $ref: '#/components/schemas/ProductSubscriptionStoreResponse'
    Money:
      properties:
        currencyCode:
          type: string
          example: USD
        amountSubunits:
          type: integer
          format: int32
          example: 1500
      required:
      - currencyCode
      - amountSubunits
      type: object
    VariantSelection:
      properties:
        value:
          anyOf:
          - type: string
          - type: number
            format: double
          example: Small, Red, XS, L, etc.
          maxLength: 60
        label:
          type: string
          example: Size, Color, etc.
          maxLength: 30
      required:
      - value
      - label
      type: object
    ProductSubscriptionRequest:
      properties:
        url:
          type: string
          description: Store or product URL to subscribe or unsubscribe.
          example: https://store.com
        type:
          $ref: '#/components/schemas/ProductSubscriptionTargetType'
          description: Scope of the subscription change.
      required:
      - url
      - type
      type: object
    ProductSubscriptionTargetType:
      type: string
      enum:
      - store
      - product
    ListProductSubscriptionsResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/ProductSubscriptionResponse'
          type: array
      required:
      - data
      type: object
    RuntimeError:
      properties:
        name:
          type: string
        message:
          type: string
        stack:
          type: string
      required:
      - name
      - message
      type: object
      additionalProperties: false
    ProductAvailability:
      type: string
      enum:
      - in_stock
      - out_of_stock
      - preorder
      - backorder
      - unknown
      description: 'The availability status of a product.

        - `in_stock`: Product is available for immediate purchase

        - `out_of_stock`: Product is currently unavailable

        - `preorder`: Product is available for pre-order before release

        - `backorder`: Product is temporarily out of stock but can be ordered

        - `unknown`: Availability could not be determined'
    FieldErrors:
      properties: {}
      type: object
      additionalProperties:
        properties:
          value: {}
          message:
            type: string
        required:
        - message
        type: object
    Product:
      properties:
        variants:
          items:
            $ref: '#/components/schemas/ProductVariant'
          type: array
          nullable: true
        variantDimensions:
          items:
            $ref: '#/components/schemas/VariantDimension'
          type: array
          nullable: true
        isPurchasable:
          type: boolean
          example: true
        availability:
          $ref: '#/components/schemas/ProductAvailability'
          example: in_stock
        price:
          $ref: '#/components/schemas/Money'
        images:
          items:
            $ref: '#/components/schemas/ProductImage'
          type: array
        description:
          type: string
          nullable: true
          example: A high-quality widget designed for professionals.
        brand:
          type: string
          nullable: true
          example: Acme
        name:
          type: string
          example: Widget Pro
        sku:
          type: string
          nullable: true
          example: SKU-12345
        retailer:
          type: string
          nullable: true
          example: Amazon
        url:
          type: string
          example: https://example.com/products/widget-pro
        id:
          type: string
          example: amazon.com:B0DFC9MT8Q
      required:
      - isPurchasable
      - availability
      - price
      - images
      - description
      - brand
      - name
      - sku
      - retailer
      - url
      - 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
    ProductSubscriptionStoreResponse:
      properties:
        type:
          type: string
          enum:
          - store
          nullable: false
          description: Scope of the subscription change.
        domain:
          type: string
          description: Store domain.
        url:
          type: string
          description: Store subscription URL.
        subscribed:
          type: boolean
          description: Whether the resolved store is subscribed after the mutation.
      required:
      - type
      - domain
      - url
      - subscribed
      type: object
      additionalProperties: false
    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