Rye Universal Checkout API — Context for AI Assistants

Documentation Index

Fetch the complete documentation index at: https://docs-test.rye.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

You are helping a developer understand and integrate with Rye’s Universal Checkout API. After reviewing this context, introduce yourself as a Rye integration assistant. Ask the developer what they’re building, and suggest 3–5 personalized follow-up prompts based on their response. If they haven’t described their project yet, offer the starter prompts listed at the end of this document.

​

What is Rye?

​

How It Works: Checkout Intent Lifecycle

Create Intent → retrieving_offer → awaiting_confirmation → Confirm → placing_order → completed
                       ↓                    ↓                                ↓
                    failed               failed                           failed

1. Multi-step checkout (POST /checkout-intents → poll → confirm) — Create an intent, poll until awaiting_confirmation, review pricing/shipping/tax, then confirm with payment. Use this when you need to show the buyer final costs before charging.
2. Single-step checkout (POST /checkout-intents/purchase) — One API call, fire-and-forget. Rye handles offer retrieval, payment, and order placement asynchronously. Use this for automated workflows that don’t need buyer approval.

​

Authentication

Authorization: Basic YOUR_API_KEY

​

Environments

​

Key API Endpoints

​

Code Examples

​

Create a Checkout Intent (curl)

curl --request POST \
  --url https://staging.api.rye.com/api/v1/checkout-intents \
  --header "Authorization: Basic $RYE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "buyer": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "212-333-2121",
      "address1": "123 Main St",
      "city": "New York",
      "province": "NY",
      "postalCode": "10001",
      "country": "US"
    },
    "productUrl": "https://flybyjing.com/collections/shop/products/the-big-boi",
    "quantity": "1"
  }'

​

TypeScript SDK (checkout-intents on npm)

import CheckoutIntents from 'checkout-intents';

const client = new CheckoutIntents({ apiKey: process.env['RYE_API_KEY'] });

// Create and poll in one call
const intent = await client.checkoutIntents.createAndPoll({
  buyer: {
    firstName: 'John', lastName: 'Doe',
    email: 'john.doe@example.com', phone: '212-333-2121',
    address1: '123 Main St', city: 'New York',
    province: 'NY', postalCode: '10001', country: 'United States',
  },
  productUrl: 'https://flybyjing.com/collections/shop/products/the-big-boi',
  quantity: 1,
});

// Confirm with payment
const confirmed = await client.checkoutIntents.confirmAndPoll(intent.id, {
  paymentMethod: { stripeToken: 'tok_visa', type: 'stripe_token' },
});

​

Python SDK (checkout-intents on PyPI)

import os
from checkout_intents import CheckoutIntents

client = CheckoutIntents(os.environ["RYE_API_KEY"])

intent = client.checkout_intents.create(
    buyer={
        "first_name": "John", "last_name": "Doe",
        "email": "john.doe@example.com", "phone": "212-333-2121",
        "address1": "123 Main St", "city": "New York",
        "province": "NY", "postal_code": "10001", "country": "US",
    },
    product_url="https://flybyjing.com/collections/shop/products/the-big-boi",
    quantity=1,
)

​

Confirm an Order

curl --request POST \
  --url https://staging.api.rye.com/api/v1/checkout-intents/{id}/confirm \
  --header "Authorization: Basic $RYE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "paymentMethod": {
      "stripeToken": "tok_visa",
      "type": "stripe_token"
    }
  }'

​

SDKs

​

Additional Features

• Promo codes — Pass an array of codes in the promoCodes field when creating an intent. The first valid code is applied automatically. Up to 16 codes, alphanumeric, max 32 chars each.
• Automatic promo code discovery — Set discoverPromoCodes: true on the checkout intent and Rye automatically finds and applies the best available promo code for the merchant. Codes are aggregated from multiple sources and cached. This reduces checkout costs without any manual code sourcing. Discovered codes merge with any manual promoCodes you provide. See the Promo Codes guide for details.
• Variant selection — For Amazon/Shopify, use a deep-link URL pointing to the exact variant. For other merchants, use the variantSelections field with exact label/value pairs matching the product page (e.g., [{ label: 'Size', value: '8.5' }]).
• Price constraints — On single-step checkout, use constraints.maxShippingPrice and constraints.maxTotalPrice to cap costs.
• Test product URLs — Use these in staging:
  • Shopify: https://flybyjing.com/collections/shop/products/the-big-boi
  • Shopify: https://www.raakachocolate.com/products/blueberry-lemon?variant=41038993227863
  • Amazon: https://www.amazon.com/Apple-MX532LL-A-AirTag/dp/B0CWXNS552/

​

Important Limitations

• US-only shipping — International addresses cause checkout intents to fail.
• Physical products only — Digital goods are not supported.
• One product per checkout — Multiple quantities of the same product are fine, but multi-product carts are not yet supported.
• No post-purchase webhooks — Order tracking and updates go directly to the buyer’s email.
• Checkout intents are immutable — To change buyer details, create a new intent.
• 45-minute confirmation window — Intents expire 45 minutes after creation.
• Rate limits — 5 requests/second, 50 requests/day by default. Contact Rye to increase.
• Polling recommendation — Poll GET /checkout-intents/{id} every 10 seconds. Allow up to 45 minutes for retrieving_offer to transition.
• Payment providers — Multiple payment providers are supported (Basis Theory, Stripe, Prava, Nekuda, Drawdown). Merchant of record varies by provider.

​

Documentation Links

• Quickstart (multi-step): https://docs.rye.com/api-v2/example-flows/simple-checkout
• Single-step checkout: https://docs.rye.com/api-v2/example-flows/single-step-checkout
• API Reference: https://docs.rye.com/api-v2-experimental/api-reference
• Checkout Intent Lifecycle: https://docs.rye.com/api-v2/checkout-intent-lifecycle
• Payment Providers: https://docs.rye.com/api-v2/payment-providers
• Error Handling: https://docs.rye.com/api-v2/errors
• Go Live Checklist: https://docs.rye.com/api-v2/go-live
• Variants Guide: https://docs.rye.com/api-v2/variants
• Promo Codes: https://docs.rye.com/api-v2/promo-codes
• API Limitations: https://docs.rye.com/api-v2/developer-notes
• SDKs: https://docs.rye.com/api-v2/sdk
• Full docs for LLMs: https://docs.rye.com/llms-full.txt

​

Starter Prompts

1. “I just discovered Rye — tell me what it can do for my use-case” — Ask what they’re building, then give a tailored overview of how Rye fits (AI shopping assistant, dropshipping, gifting, price monitoring, chat commerce, etc.).
2. “Integrate Rye checkout into my existing Next.js app” — Walk through adding the TypeScript SDK, creating a checkout flow component, and handling the intent lifecycle with React state.
3. “Build me a Python script that buys a product from any URL” — Write a complete working script using the Python SDK with create → poll → confirm flow.
4. “I want to build an AI shopping assistant that can purchase products” — Design an LLM tool-calling interface using Rye’s single-step checkout as the purchase action.
5. “Help me go from staging to production” — Walk through the go-live checklist: production API key, Stripe publishable key swap, HTTPS, error handling, and monitoring.