> ## 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.

Build this with AI

Open a pre-built prompt in your preferred AI tool to generate a complete working integration.

## See Rye in Action

Watch a complete order flow — from product URL to purchase confirmation — all without leaving your app.

> [card]

## 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
)
```

> [!NOTE]
>
> 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/)

> [!WARNING]
>
> 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.

> [!TIP]
>
> 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](https://docs-test.rye.com/docs/api-v2/payment-providers/stripe.md) to build a simple React app that generates tokens with Stripe Elements.

> [!NOTE]
>
> This guide uses Stripe, but Rye supports other payment providers too. See [Payment Providers](https://docs-test.rye.com/docs/api-v2/payment-providers.md) 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.

> [!WARNING]
>
> 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."
  }
}
```

> [!TIP]
>
> 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.

> [!NOTE]
>
> 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](https://docs-test.rye.com/docs/api-v2/api-comparison.md) guide to learn about the differences between the Universal Checkout API and the Sync API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.