Skip to main content
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.
Coming soon, we will add an optional maxPurchasePrice field, allowing you to set the maximum amount the shopper is willing to pay for an order. If the total exceeds this value, the order will not be processed.

​
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. 
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": "[email protected]",
            "firstName": "John",
            "lastName": "Doe",
            "phone": "1234567890",
            "postalCode": "10001",
            "province": "NY"
          },
          "paymentMethod": {
            "stripeToken": "tok_visa",
            "type": "stripe_token"
          },
          "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 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"
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.