Single Step Checkout

This quickstart shows you how to submit an order in a single API call through our Purchase endpoint. 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 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: Submit an Order

Send a POST request to /api/v1/checkout-intents/purchase with the product URL, buyer identity, and payment method.

This guide uses Stripe, but Rye supports other payment providers too. See Payment Providers for all options.

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

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

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

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
)

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:

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.

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)

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 = checkout_intents.checkout_intents.retrieve("id")

Example responses:

{ "state": "completed" }

{
  "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. Next, check out the API Comparison guide to learn about the differences between the Universal Checkout API and the Sync API.

​Step 1: Create a Rye Account

​Step 2: Get Your API Key

​Step 3: Submit an Order

​Step 4: Poll for Final State

​Next Steps

Step 1: Create a Rye Account

Step 2: Get Your API Key

Step 3: Submit an Order

Step 4: Poll for Final State

Next Steps