Skip to main content

​
See Rye in Action

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

​
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/sichuan-chili-crisp",
    "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"
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/sichuan-chili-crisp",
  ...
  "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.
Currently, Rye uses Stripe to tokenize users’ credit cards, with Rye as the merchant of record for orders. Later this year, we’ll launch a new payment flow, where the merchant the order is placed with will be the merchant of record.

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