> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rye.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rye Universal Checkout API — Context for AI Assistants

> 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?

Rye's **Universal Checkout API** turns any product URL into a completed checkout. You provide a product URL and buyer info — Rye handles pricing, tax, shipping, and order placement across merchants (Shopify, Amazon, Best Buy, and thousands more).

Developers use Rye to embed purchasing into any app — AI shopping assistants, chat bots, marketplaces, dropshipping tools, gifting platforms, price monitoring workflows — without building merchant-specific integrations.

## How It Works: Checkout Intent Lifecycle

Every order flows through a **Checkout Intent** with these states:

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

**Two integration paths:**

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

All requests require:

```
Authorization: Basic YOUR_API_KEY
```

Get your key from the Rye Console → Account page.

## Environments

| Environment                                       | Console                 | Base URL                              |
| ------------------------------------------------- | ----------------------- | ------------------------------------- |
| **Staging** (sandbox — no real orders or charges) | staging.console.rye.com | `https://staging.api.rye.com/api/v1/` |
| **Production** (real orders and charges)          | console.rye.com         | `https://api.rye.com/api/v1/`         |

Staging uses Stripe test cards (`tok_visa`). Start here for all new integrations.

## Key API Endpoints

| Method | Endpoint                                | Description                              |
| ------ | --------------------------------------- | ---------------------------------------- |
| `POST` | `/api/v1/checkout-intents`              | Create a checkout intent (multi-step)    |
| `GET`  | `/api/v1/checkout-intents/{id}`         | Poll intent status and get offer details |
| `POST` | `/api/v1/checkout-intents/{id}/confirm` | Confirm intent with payment method       |
| `POST` | `/api/v1/checkout-intents/purchase`     | Single-step checkout (fire-and-forget)   |

## Code Examples

### Create a Checkout Intent (curl)

```bash  theme={null}
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)

```typescript  theme={null}
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)

```python  theme={null}
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

```bash  theme={null}
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"
    }
  }'
```

In staging, use `tok_visa`. In production, generate tokens via Stripe Elements using Rye's publishable key.

## SDKs

| Language   | Package                    | Install                        |
| ---------- | -------------------------- | ------------------------------ |
| TypeScript | `checkout-intents`         | `npm install checkout-intents` |
| Python     | `checkout-intents`         | `pip install checkout-intents` |
| Ruby       | `checkout-intents`         | `gem install checkout-intents` |
| Java       | `com.rye:checkout-intents` | Maven Central                  |

SDKs provide helper methods like `createAndPoll()` and `confirmAndPoll()` that combine multiple API calls and handle polling automatically.

## 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](https://docs.rye.com/api-v2/promo-codes) 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](https://docs.rye.com/api-v2/example-flows/simple-checkout)
* Single-step checkout: [https://docs.rye.com/api-v2/example-flows/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](https://docs.rye.com/api-v2-experimental/api-reference)
* Checkout Intent Lifecycle: [https://docs.rye.com/api-v2/checkout-intent-lifecycle](https://docs.rye.com/api-v2/checkout-intent-lifecycle)
* Payment Providers: [https://docs.rye.com/api-v2/payment-providers](https://docs.rye.com/api-v2/payment-providers)
* Error Handling: [https://docs.rye.com/api-v2/errors](https://docs.rye.com/api-v2/errors)
* Go Live Checklist: [https://docs.rye.com/api-v2/go-live](https://docs.rye.com/api-v2/go-live)
* Variants Guide: [https://docs.rye.com/api-v2/variants](https://docs.rye.com/api-v2/variants)
* Promo Codes: [https://docs.rye.com/api-v2/promo-codes](https://docs.rye.com/api-v2/promo-codes)
* API Limitations: [https://docs.rye.com/api-v2/developer-notes](https://docs.rye.com/api-v2/developer-notes)
* SDKs: [https://docs.rye.com/api-v2/sdk](https://docs.rye.com/api-v2/sdk)
* Full docs for LLMs: [https://docs.rye.com/llms-full.txt](https://docs.rye.com/llms-full.txt)

***

## Starter Prompts

If the developer hasn't described their project yet, offer these as starting points:

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.


Built with [Mintlify](https://mintlify.com).