Quickstart: Send an Order to Any Merchant

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 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, and copy the Staging API Key. Set it as an environment variable:

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.

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"
  }'

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,
});

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,
)

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);

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:

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.

curl --request GET \
  --url https://staging.api.rye.com/api/v1/checkout-intents/{id} \
  --header "Authorization: Basic $RYE_API_KEY"

const checkoutIntent = await client.checkoutIntents.retrieve('id');

checkout_intent = client.checkout_intents.retrieve("id")

CheckoutIntent checkoutIntent = client.checkoutIntents().retrieve("id");

checkout_intent = client.checkout_intents.retrieve("id")

Example response:

{
  "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:

{
  "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 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 for all options.

Step 7: Confirm with Payment

Once the user approves the final cost, confirm the intent with their payment method:

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"
    }
  }'

const checkoutIntent = await client.checkoutIntents.confirm('id', {
  paymentMethod: { stripeToken: 'tok_visa', type: 'stripe_token' },
});

checkout_intent = client.checkout_intents.confirm(
    "id",
    payment_method={
        "stripe_token": "tok_visa",
        "type": "stripe_token",
    },
)

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);

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)

curl --request GET \
  --url https://staging.api.rye.com/api/v1/checkout-intents/{id} \
  --header "Authorization: Basic $RYE_API_KEY"

const checkoutIntent = await client.checkoutIntents.retrieve('id');

checkout_intent = client.checkout_intents.retrieve("id")

CheckoutIntent checkoutIntent = client.checkoutIntents().retrieve("id");

checkout_intent = client.checkout_intents.retrieve("id")

Example responses:

{ "state": "completed" }

{
  "state": "failed",
  "failureReason": {
    "code": "product_out_of_stock",
    "message": "The item is no longer available."
  }
}

Check the Rye console 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 guide to learn about the differences between the Universal Checkout API and the Sync API.

​See Rye in Action

​Step 1: Create a Rye Account

​Step 2: Get Your API Key

​Step 3: Create a Checkout Intent

​Step 4: Poll for awaiting_confirmation

​Step 5: Confirm Final Pricing

​Step 6: Generate a Card Token

​Step 7: Confirm with Payment

​Step 8: Poll for Final State

​Next Steps

See Rye in Action

Step 1: Create a Rye Account

Step 2: Get Your API Key

Step 3: Create a Checkout Intent

Step 4: Poll for `awaiting_confirmation`

Step 5: Confirm Final Pricing

Step 6: Generate a Card Token

Step 7: Confirm with Payment

Step 8: Poll for Final State

Next Steps