OpenAPI Specification
openapi: 3.0.0
info:
title: Universal Checkout Betas 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: Betas
paths:
/api/v1/betas/checkout-sessions:
post:
operationId: Create
responses:
'200':
description: Checkout session
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutSession'
'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 new checkout session.
Checkout sessions are hosted checkout forms your shoppers can use to complete their purchases.'
summary: Create checkout session
tags:
- Betas
security:
- bearerAuth:
- checkout_intents:write
parameters: []
requestBody:
description: The request body containing the checkout session parameters
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutSessionPostParams'
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 checkoutSession = await client.betas.checkoutSessions.create({\n productUrl: 'https://www.amazon.com/dp/B0DFC9MT8Q',\n quantity: 1,\n});\n\nconsole.log(checkoutSession.url);"
- 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)\ncheckout_session = client.betas.checkout_sessions.create(\n product_url=\"https://www.amazon.com/dp/B0DFC9MT8Q\",\n quantity=1,\n)\nprint(checkout_session.url)"
- lang: Java
source: "package com.rye.example;\n\nimport com.rye.client.CheckoutIntentsClient;\nimport com.rye.client.okhttp.CheckoutIntentsOkHttpClient;\nimport com.rye.models.betas.CheckoutSession;\nimport com.rye.models.betas.checkoutsessions.CheckoutSessionCreateParams;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n CheckoutIntentsClient client = CheckoutIntentsOkHttpClient.fromEnv();\n\n CheckoutSessionCreateParams params = CheckoutSessionCreateParams.builder()\n .productUrl(\"https://www.amazon.com/dp/B0DFC9MT8Q\")\n .quantity(1)\n .build();\n CheckoutSession checkoutSession = client.betas().checkoutSessions().create(params);\n }\n}"
- lang: cURL
source: "curl https://staging.api.rye.com/api/v1/betas/checkout-sessions \\\n -H 'Content-Type: application/json' \\\n -H \"Authorization: Bearer $CHECKOUT_INTENTS_API_KEY\" \\\n -d '{\n \"productUrl\": \"https://www.amazon.com/dp/B0DFC9MT8Q\",\n \"quantity\": 1,\n \"referenceId\": \"order-1234\"\n }'"
components:
schemas:
CheckoutSession:
properties:
url:
type: string
description: URL to send your user to for checkout. This URL is valid for 4 hours.
required:
- url
type: object
description: 'A checkout session represents a hosted checkout form that shoppers can use to complete their purchases.
Checkout sessions provide a pre-built UI for collecting payment and shipping information, allowing you to quickly integrate checkout functionality without building your own forms.'
Omit_CheckoutIntentPostParams.buyer_:
$ref: '#/components/schemas/Pick_CheckoutIntentPostParams.Exclude_keyofCheckoutIntentPostParams.buyer__'
description: Construct a type with the properties of T except for those in type K.
AuthenticationError:
properties:
name:
type: string
message:
type: string
stack:
type: string
required:
- name
- message
type: object
additionalProperties: false
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
CheckoutSessionPostParams:
allOf:
- $ref: '#/components/schemas/Omit_CheckoutIntentPostParams.buyer_'
- properties:
layout:
type: string
enum:
- default
- wizard
description: Optional layout for the checkout UI (e.g. "wizard"). Defaults to the standard layout.
buyer:
$ref: '#/components/schemas/Partial_Buyer_'
description: Optional buyer information, used to pre-fill the checkout form with the buyer's information.
type: object
description: Post body for creating a checkout session.
RuntimeError:
properties:
name:
type: string
message:
type: string
stack:
type: string
required:
- name
- message
type: object
additionalProperties: false
CheckoutConstraints:
properties:
offerRetrievalEffort:
$ref: '#/components/schemas/OfferRetrievalEffort'
example: max
maxShippingPrice:
type: integer
format: int32
example: 500
minimum: 0
maxTotalPrice:
type: integer
format: int32
example: 100000
minimum: 0
type: object
FieldErrors:
properties: {}
type: object
additionalProperties:
properties:
value: {}
message:
type: string
required:
- message
type: object
OfferRetrievalEffort:
type: string
enum:
- max
- low
description: 'Controls how much effort the system should spend retrieving an offer.
- ''max'': Full effort including AI agent fallback (slower, higher success rate)
- ''low'': Fast API-only retrieval, fails if API unavailable (faster, lower success rate)
Default: ''max'''
Pick_CheckoutIntentPostParams.Exclude_keyofCheckoutIntentPostParams.buyer__:
properties:
productUrl:
type: string
example: https://www.amazon.com/dp/B0DFC9MT8Q
quantity:
type: integer
format: int32
example: 1
minimum: 0
variantSelections:
items:
$ref: '#/components/schemas/VariantSelection'
type: array
promoCodes:
items:
type: string
type: array
maxItems: 16
constraints:
$ref: '#/components/schemas/CheckoutConstraints'
discoverPromoCodes:
type: boolean
referenceId:
type: string
example: order-1234
maxLength: 255
required:
- productUrl
- quantity
type: object
description: From T, pick a set of properties whose keys are in the union K
Partial_Buyer_:
properties:
firstName:
type: string
example: John
maxLength: 255
lastName:
type: string
example: Doe
maxLength: 255
email:
type: string
example: john.doe@example.com
phone:
type: string
example: '1234567890'
address1:
type: string
example: 123 Main St
maxLength: 255
address2:
type: string
example: Apt 1
maxLength: 255
city:
type: string
example: New York
maxLength: 255
province:
type: string
example: NY
maxLength: 255
country:
type: string
example: US
postalCode:
type: string
example: '10001'
maxLength: 255
type: object
description: Make all properties in T optional
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
securitySchemes:
bearerAuth:
type: apiKey
in: header
name: Authorization
description: Rye API key