;
};
export const llmPrompt = `Build a complete, runnable Next.js application that integrates Rye's Universal Checkout API using the single-step Purchase endpoint — a fire-and-forget API call that creates and confirms an order in one request. 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. The Purchase endpoint combines creating and confirming an order in a single call, with Rye handling offer retrieval, payment authorization, and order placement asynchronously.
## 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/purchase/route.ts — POST: receives buyer + productUrl + paymentMethod from frontend, calls SDK purchase, returns intent
app/api/checkout/get-intent/route.ts — GET: receives intent id, calls SDK, returns current state
## Single-Step Checkout Using SDK (server-side)
### Submit order (fire-and-forget, in API route)
const intent = await client.checkoutIntents.purchase({
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',
},
paymentMethod: { stripeToken: 'tok_visa', type: 'stripe_token' },
productUrl: 'https://flybyjing.com/collections/shop/products/sichuan-chili-crisp',
quantity: 1,
// Optional price constraints:
// constraints: {
// maxShippingPrice: { amountSubunits: 1000, currencyCode: 'USD' },
// maxTotalPrice: { amountSubunits: 5000, currencyCode: 'USD' },
// },
});
### Poll for final state (in API route)
const completed = await client.checkoutIntents.pollUntilCompleted(intent.id);
// completed.state === 'completed' means order placed successfully
// completed.state === 'failed' means something went wrong
### 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
- Optional fields for max shipping price and max total price constraints
- Show real-time order status: submitting → processing → completed/failed
- Use SDK polling helpers (pollUntilCompleted) to check intent state after submission
- Handle error states and display 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.`;
This quickstart shows you how to submit an order in a single API call through our [Purchase endpoint](https://docs.rye.com/api-v2-experimental/api-reference/post-purchase--single-step-checkout).
It’s a fire-and-forget endpoint that combines creating and confirming an order in a single API call, letting our system handle offer retrieval, payment authorization, and order placement asynchronously. This simplifies your workflow and reduces integration complexity.
It’s ideal for automating routine purchases, processing high-volume asynchronous orders, or integrating into workflows that don’t require synchronous user approval.
## 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: Submit an Order
Send a `POST` request to `/api/v1/checkout-intents/purchase` with the product URL, buyer identity, and [payment method](https://docs.rye.com/api-v2/payment-providers).
This guide uses Stripe, but Rye supports other payment providers too. See [Payment Providers](/api-v2/payment-providers) for all options.
```bash curl theme={null}
curl https://staging.api.rye.com/api/v1/checkout-intents/purchase \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $CHECKOUT_INTENTS_API_KEY" \
-d '{
"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"
},
"paymentMethod": {
"stripeToken": "tok_visa",
"type": "stripe_token"
},
"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['CHECKOUT_INTENTS_API_KEY'],
});
const checkoutIntent = await client.checkoutIntents.purchase({
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',
},
paymentMethod: { stripeToken: 'tok_visa', type: 'stripe_token' },
productUrl: 'https://flybyjing.com/collections/shop/products/the-big-boi',
quantity: 1,
});
console.log(checkoutIntent);
```
```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,
)
```
```ruby Ruby SDK theme={null}
require "checkout_intents"
checkout_intents = CheckoutIntents::Client.new(
api_key: ENV["CHECKOUT_INTENTS_API_KEY"],
environment: "staging"
)
checkout_intent = checkout_intents.checkout_intents.purchase(
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"
},
payment_method: {stripeToken: "tok_visa", type: "stripe_token"},
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.CheckoutIntentPurchaseParams;
import com.rye.models.checkoutintents.PaymentMethod;
CheckoutIntentsClient client = CheckoutIntentsOkHttpClient.fromEnv();
CheckoutIntentPurchaseParams params = CheckoutIntentPurchaseParams.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())
.paymentMethod(PaymentMethod.StripeTokenPaymentMethod.builder()
.stripeToken("tok_visa")
.type(PaymentMethod.StripeTokenPaymentMethod.Type.STRIPE_TOKEN)
.build())
.productUrl("https://flybyjing.com/collections/shop/products/the-big-boi")
.quantity(1)
.build();
CheckoutIntent checkoutIntent = client.checkoutIntents().purchase(params);
```
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/)
The optional fields `constraints.maxShippingPrice` and `constraints.maxTotalPrice` let you set the maximum shipping cost and total amount the shopper is willing to pay. If either exceeds the specified values, the order won’t be processed. More details are [available here](https://docs.rye.com/api-v2-experimental/api-reference/post-purchase--single-step-checkout#body-constraints-max-shipping-price).
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 Final State
Poll the `GET` endpoint until the checkout 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 = checkout_intents.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."
}
}
```
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!
If you want to check shipping options, taxes, total cost, and product availability before submitting an order, please [review this guide for the steps](https://docs.rye.com/api-v2/example-flows/simple-checkout).
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.