> ## 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.
# Quickstart: Send an Order to Any Merchant
> Learn how to integrate the Rye API, from setting up your account to submitting your first order. The example uses Shopify, but the same process works with Amazon, non-Shopify stores, and other merchants.
export const OpenWithLLM = ({prompt, tools}) => {
const handleClick = (tool, e) => {
const btn = e.currentTarget;
const labelSpan = btn.querySelector('[data-label]');
const copiedLabel = btn.getAttribute('data-copied');
if (tool === 'claude') {
window.open(`https://claude.ai/new?q=${encodeURIComponent(prompt)}`, '_blank');
return;
}
if (tool === 'lovable') {
window.open(`https://lovable.dev/?autosubmit=true#prompt=${encodeURIComponent(prompt)}`, '_blank');
return;
}
navigator.clipboard.writeText(prompt);
if (labelSpan && copiedLabel) {
const original = labelSpan.textContent;
labelSpan.textContent = copiedLabel;
setTimeout(() => {
labelSpan.textContent = original;
}, 2500);
}
if (tool === 'chatgpt') {
window.open('https://chatgpt.com/', '_blank');
}
};
const show = tool => !tools || tools.includes(tool);
const buttonBase = "inline-flex items-center gap-2 px-4 py-2.5 rounded-lg text-sm font-medium transition-all duration-200 border cursor-pointer";
return
Build this with AI
Open a pre-built prompt in your preferred AI tool to generate a complete working integration.
;
};
export const llmPrompt = `Build a complete, runnable Next.js application that integrates Rye's Universal Checkout API to let users purchase any product by URL from Amazon, Shopify, or other merchants. Use the official Rye TypeScript SDK (checkout-intents) for all API calls.
## What Rye Does
Rye is a commerce API that lets you sell products from any merchant (Amazon, Shopify, etc.) in your app. You provide a product URL and buyer details, Rye fetches pricing/shipping from the merchant, and then you confirm with a payment token to place the order.
## Architecture
IMPORTANT: All Rye SDK calls MUST happen server-side. Never import or use the checkout-intents SDK in client components — the API key must stay on the server.
- Frontend (client components): Form UI, status display. Calls internal Next.js API routes via fetch.
- Backend (Next.js Route Handlers in app/api/): Uses the checkout-intents SDK to talk to Rye. The API key never leaves the server.
## SDK Setup (server-side only)
Install: npm install checkout-intents
Environment variables (server-side, not prefixed with NEXT_PUBLIC_):
CHECKOUT_INTENTS_API_KEY — the SDK reads this by default
CHECKOUT_INTENTS_BASE_URL=https://staging.api.rye.com (for staging)
In a server-side file (e.g. lib/rye.ts or an API route):
import CheckoutIntents from 'checkout-intents';
const client = new CheckoutIntents(); // reads CHECKOUT_INTENTS_API_KEY from env
## API Route Structure
app/api/checkout/create-intent/route.ts — POST: receives buyer + productUrl from frontend, calls SDK, returns intent
app/api/checkout/get-intent/route.ts — GET: receives intent id, calls SDK, returns current state
app/api/checkout/confirm-intent/route.ts — POST: receives intent id + stripeToken, calls SDK, returns result
## Checkout Flow Using SDK (Two-Phase, server-side)
### Phase 1: Create intent and wait for offer (in API route)
const intent = await client.checkoutIntents.createAndPoll({
buyer: {
firstName: 'John', lastName: 'Doe',
email: 'john.doe@example.com', phone: '212-333-2121',
address1: '123 Main St', address2: 'Apt 1',
city: 'New York', province: 'NY',
postalCode: '10001', country: 'US',
},
productUrl: 'https://flybyjing.com/collections/shop/products/sichuan-chili-crisp',
quantity: 1,
});
// createAndPoll() automatically polls until state is "awaiting_confirmation" or "failed"
// intent.offer.cost has: subtotal, tax, total (each with amountSubunits and currencyCode)
// intent.offer.shipping has: availableOptions (id, cost), selectedOptionId
### Phase 2: Confirm with payment and wait for completion (in API route)
const completed = await client.checkoutIntents.confirmAndPoll(intent.id, {
paymentMethod: { stripeToken: 'tok_visa', type: 'stripe_token' },
});
// confirmAndPoll() automatically polls until state is "completed" or "failed"
// completed.state === 'completed' means order placed successfully
### Other useful SDK methods
- client.checkoutIntents.create(params) — create without polling
- client.checkoutIntents.retrieve(id) — get current state
- client.checkoutIntents.confirm(id, params) — confirm without polling
- client.checkoutIntents.pollUntilAwaitingConfirmation(id) — poll an existing intent
- client.checkoutIntents.pollUntilCompleted(id) — poll after confirm
- client.products.lookup({ url }) — look up product details by URL
### Error handling
import CheckoutIntents, { PollTimeoutError } from 'checkout-intents';
try { ... } catch (error) {
if (error instanceof PollTimeoutError) { /* polling timed out */ }
if (error instanceof CheckoutIntents.APIError) { /* API error with status, message */ }
}
If intent.state === 'failed', check intent.failureReason.code and intent.failureReason.message.
## Important Notes
- Test payment token: tok_visa (Stripe test token, works in staging)
- US shipping addresses only
- Polling helpers accept options: { pollIntervalMs: 5000, maxAttempts: 120 }
## App Requirements
- Next.js App Router with TypeScript and Tailwind CSS
- Use the checkout-intents SDK for ALL Rye API calls (do not use raw fetch)
- ALL SDK usage must be in server-side code (Route Handlers or Server Actions) — never in client components
- CHECKOUT_INTENTS_API_KEY must never be exposed to the browser
- Frontend client components call internal /api/ routes, which use the SDK server-side
- A form for: product URL, buyer details (name, email, phone, address), quantity
- Show real-time order status: creating → retrieving offer → awaiting confirmation (show pricing) → confirming → completed/failed
- Display offer details (subtotal, shipping, tax, total) before the user confirms
- Handle error states and show failureReason if the order fails
- Environment variables (server-side): CHECKOUT_INTENTS_API_KEY, CHECKOUT_INTENTS_BASE_URL
- Include a README with setup instructions
Generate all files needed to run the app. Make sure the .gitignore includes .env and .env.* so secrets are never committed to version control. After generating the code, ask the user for their Rye API key so you can update the .env or .env.local file with the actual CHECKOUT_INTENTS_API_KEY value. Also confirm which environment they want to use (staging or production) so you can set CHECKOUT_INTENTS_BASE_URL accordingly.`;
## See Rye in Action
Watch a complete order flow — from product URL to purchase confirmation — all without leaving your app.
## Step 1: Create a Rye Account
Create a [Rye staging account](https://staging.console.rye.com/register) to get an API key and submit a test order.
## Step 2: Get Your API Key
Go to the [Account tab in your Rye staging account](https://staging.console.rye.com/account), and copy the **Staging API Key**.
Set it as an environment variable:
```bash theme={null}
export RYE_API_KEY="YOUR_API_KEY"
```
## Step 3: Create a Checkout Intent
Send a `POST` request to `/api/v1/checkout-intents` with the product URL and buyer identity.
```bash curl 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": {
"postalCode": "10001",
"country": "US",
"province": "NY",
"city": "New York",
"address2": "Apt 1",
"address1": "123 Main St",
"phone": "212-333-2121",
"email": "john.doe@example.com",
"lastName": "Doe",
"firstName": "John"
},
"productUrl": "https://flybyjing.com/collections/shop/products/the-big-boi",
"quantity": "1"
}'
```
```javascript TypeScript SDK theme={null}
import CheckoutIntents from 'checkout-intents';
const client = new CheckoutIntents({
apiKey: process.env['RYE_API_KEY'],
});
const checkoutIntent = await client.checkoutIntents.create({
buyer: {
address1: '123 Main St',
city: 'New York',
country: 'United States',
email: 'john.doe@example.com',
firstName: 'John',
lastName: 'Doe',
phone: '212-333-2121',
postalCode: '10001',
province: 'NY',
},
productUrl: 'https://flybyjing.com/collections/shop/products/the-big-boi',
quantity: 1,
});
```
```python Python SDK theme={null}
import os
from checkout_intents import CheckoutIntents
api_key = os.environ["RYE_API_KEY"]
client = CheckoutIntents(api_key)
checkout_intent = client.checkout_intents.create(
buyer={
"address1": "123 Main St",
"city": "New York",
"country": "US",
"email": "john.doe@example.com",
"first_name": "John",
"last_name": "Doe",
"phone": "212-333-2121",
"postal_code": "10001",
"province": "NY",
},
product_url="https://flybyjing.com/collections/shop/products/the-big-boi",
quantity=1,
)
```
```java Java SDK theme={null}
import com.rye.client.CheckoutIntentsClient;
import com.rye.client.okhttp.CheckoutIntentsOkHttpClient;
import com.rye.models.checkoutintents.Buyer;
import com.rye.models.checkoutintents.CheckoutIntent;
import com.rye.models.checkoutintents.CheckoutIntentCreateParams;
CheckoutIntentsClient client = CheckoutIntentsOkHttpClient.fromEnv();
CheckoutIntentCreateParams params = CheckoutIntentCreateParams.builder()
.buyer(Buyer.builder()
.address1("123 Main St")
.city("New York")
.country("US")
.email("john.doe@example.com")
.firstName("John")
.lastName("Doe")
.phone("212-333-2121")
.postalCode("10001")
.province("NY")
.build())
.productUrl("https://flybyjing.com/collections/shop/products/the-big-boi")
.quantity(1)
.build();
CheckoutIntent checkoutIntent = client.checkoutIntents().create(params);
```
```ruby Ruby SDK theme={null}
require "checkout_intents"
client = CheckoutIntents::Client.new(
api_key: ENV["RYE_API_KEY"]
)
checkout_intent = client.checkout_intents.create(
buyer: {
address1: "123 Main St",
city: "New York",
country: "US",
email: "john.doe@example.com",
firstName: "John",
lastName: "Doe",
phone: "212-333-2121",
postalCode: "10001",
province: "NY"
},
product_url: "https://flybyjing.com/collections/shop/products/the-big-boi",
quantity: 1
)
```
You can send orders to Amazon, Shopify, or other merchants by simply changing the product URL. Example test URLs:
* [https://www.raakachocolate.com/products/blueberry-lemon?variant=41038993227863](https://www.raakachocolate.com/products/blueberry-lemon?variant=41038993227863)
* [https://www.amazon.com/Apple-MX532LL-A-AirTag/dp/B0CWXNS552/](https://www.amazon.com/Apple-MX532LL-A-AirTag/dp/B0CWXNS552/)
Orders can only be shipped to **U.S. addresses**. International shipping is not yet supported. Using a non-US address will cause the checkout intent to fail.
## Step 4: Poll for `awaiting_confirmation`
After creating the intent, poll the `/api/v1/checkout-intents/{id}` endpoint with a `GET` request until the state is `awaiting_confirmation`. Use the `id` from the previous step.
```bash curl theme={null}
curl --request GET \
--url https://staging.api.rye.com/api/v1/checkout-intents/{id} \
--header "Authorization: Basic $RYE_API_KEY"
```
```javascript TypeScript SDK theme={null}
const checkoutIntent = await client.checkoutIntents.retrieve('id');
```
```python Python SDK theme={null}
checkout_intent = client.checkout_intents.retrieve("id")
```
```java Java SDK theme={null}
CheckoutIntent checkoutIntent = client.checkoutIntents().retrieve("id");
```
```ruby Ruby SDK theme={null}
checkout_intent = client.checkout_intents.retrieve("id")
```
Example response:
```json theme={null}
{
"state": "awaiting_confirmation"
}
```
Fetching an offer from the merchant is asynchronous. Always poll the `GET` endpoint for the latest state of the intent.
Use the `failureReason` field to display helpful error messages to users.
Use the SDK’s `createAndPoll()` helper method to complete steps 3 and 4 in a single call.
## Step 5: Confirm Final Pricing
Before proceeding to payment, inspect the latest checkout intent response to confirm:
* Shipping options and costs
* Taxes
* Total cost
* Offer availability
Example response:
```bash theme={null}
{
"id": "ci_4197e51f48290517639402856173049",
"createdAt": "2025-10-14T21:38:52.062Z",
"productUrl": "https://flybyjing.com/collections/shop/products/the-big-boi",
...
"quantity": 1,
"variantSelections": null,
"state": "awaiting_confirmation",
"offer": {
"cost": {
"subtotal": {
"amountSubunits": 1500,
"currencyCode": "USD"
},
"tax": {
"amountSubunits": 0,
"currencyCode": "USD"
},
"total": {
"amountSubunits": 2300,
"currencyCode": "USD"
}
},
"shipping": {
"availableOptions": [
{
"id": "8-Flat Rate Shipping",
"cost": {
"amountSubunits": 800,
"currencyCode": "USD"
}
}
],
"selectedOptionId": "8-Flat Rate Shipping"
}
}
}
```
Ensure your UI reflects the full cost to the user and allows them to confirm or adjust details if needed.
## Step 6: Generate a Card Token
In staging, you can use the test token `tok_visa` to place an order.
Alternatively, follow [these steps](/api-v2/payment-providers/stripe) to build a simple React app that generates tokens with Stripe Elements.
This guide uses Stripe, but Rye supports other payment providers too. See [Payment Providers](/api-v2/payment-providers) for all options.
## Step 7: Confirm with Payment
Once the user approves the final cost, confirm the intent with their payment method:
```bash curl 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"
}
}'
```
```javascript TypeScript SDK theme={null}
const checkoutIntent = await client.checkoutIntents.confirm('id', {
paymentMethod: { stripeToken: 'tok_visa', type: 'stripe_token' },
});
```
```python Python SDK theme={null}
checkout_intent = client.checkout_intents.confirm(
"id",
payment_method={
"stripe_token": "tok_visa",
"type": "stripe_token",
},
)
```
```java Java SDK theme={null}
import com.rye.models.checkoutintents.CheckoutIntentConfirmParams;
import com.rye.models.checkoutintents.PaymentMethod;
CheckoutIntentConfirmParams confirmParams = CheckoutIntentConfirmParams.builder()
.paymentMethod(PaymentMethod.StripeTokenPaymentMethod.builder()
.stripeToken("tok_visa")
.type(PaymentMethod.StripeTokenPaymentMethod.Type.STRIPE_TOKEN)
.build())
.build();
CheckoutIntent checkoutIntent = client.checkoutIntents().confirm("id", confirmParams);
```
```ruby Ruby SDK theme={null}
checkout_intent = client.checkout_intents.confirm(
"id",
payment_method: { stripe_token: "tok_visa", type: "stripe_token" }
)
```
Placing an order is asynchronous. Always poll the `GET` endpoint after confirming to check the state of the intent.
Once in a terminal state (`completed` or `failed`), the intent is finished.
Checkout intents cannot be updated once created. If buyer details (e.g. shipping address) change, create a new checkout intent.
## Step 8: Poll for Final State
After confirming, poll the `GET` endpoint again until the intent reaches a terminal state:
* `completed`: order placed successfully
* `failed`: something went wrong (e.g. out of stock, expired)
```bash curl theme={null}
curl --request GET \
--url https://staging.api.rye.com/api/v1/checkout-intents/{id} \
--header "Authorization: Basic $RYE_API_KEY"
```
```javascript TypeScript SDK theme={null}
const checkoutIntent = await client.checkoutIntents.retrieve('id');
```
```python Python SDK theme={null}
checkout_intent = client.checkout_intents.retrieve("id")
```
```java Java SDK theme={null}
CheckoutIntent checkoutIntent = client.checkoutIntents().retrieve("id");
```
```ruby Ruby SDK theme={null}
checkout_intent = client.checkout_intents.retrieve("id")
```
Example responses:
```json theme={null}
{ "state": "completed" }
```
```json theme={null}
{
"state": "failed",
"failureReason": {
"code": "product_out_of_stock",
"message": "The item is no longer available."
}
}
```
Check the [Rye console](https://staging.console.rye.com/checkout-intents) to view test orders.
Use the SDK’s `confirmAndPoll()` helper method to complete steps 7 and 8 in a single call.
Rye does not provide post-purchase tracking or webhooks. Tracking and order updates are sent directly to the buyer's email address.
## Next Steps
Congrats — you just submitted your first Rye order!
Next, check out the [API Comparison](/api-v2/api-comparison) guide to learn about the differences between the Universal Checkout API and the Sync API.