​
Step 1: Create a Rye Account

Create a Rye staging account here, which will allow you to get an API key and submit a test order.

​
Step 2: Get Your API Key

Go to the Accounts tab in your Rye staging account, and get the API key within the Staging API Key headers section.

​
Step 3: Create a Checkout Intent

To initiate a new checkout, send a POST request to /api/v1/checkout-intents with the product URL and buyer identity. 
export RYE_API_KEY="YOUR_API_KEY"

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://www.raakachocolate.com/products/blueberry-lemon?variant=41038993227863",
    "quantity": "1"
  }'
You can send orders to Amazon, non-Shopify stores, and other merchants by simply changing the product URL in the request. Here are some example URLs you can use for testing: Note: Orders are only supported for US shipping addresses and a quantity of 1.

​
Step 4: Poll for awaiting_confirmation

After creating the intent, poll the /api/v1/checkout-intents/{id} enpdoint with a GET request until it reaches the awaiting_confirmation state. Use the value of the id field returned in step 3. 
curl --request GET \
  --url https://staging.api.rye.com/api/v1/checkout-intents/{id} \
  --header "Authorization: Basic $RYE_API_KEY"
Repeat the request every few seconds until you receive: 
{
  "state": "awaiting_confirmation"
}
This reflects completion of background processing (offers, shipping, costs).
For additional context:
  • All processing is asynchronous. Always poll the GET endpoint after each major step.
  • Once in a terminal state (completed or failed), the intent is complete.
  • Use failureReason to display helpful error messages to users.

​
Step 5: Confirm Final Pricing

Before proceeding to payment confirmation, inspect the latest checkout intent response from step 4 to confirm:
  • Shipping options and pricing
  • Taxes
  • Total cost
  • Selected offer availability
Ensure your UI reflects the full final cost to the user and allows for selection or changes if applicable. You can extract this information from the GET /api/v1/checkout-intents/{id} response payload.

​
Step 6: Generate a Card Token

You can use tok_visa as the card token in staging to place a test order. Alternatively, you can use the steps here to create a simple React app to generate the card token.
Note: With the current integration, Rye uses Stripe to tokenize users’ credit cards. This makes Rye the merchant of record for orders.

​
Step 7: Confirm with Payment

Once the user has reviewed the final cost and approved, confirm the intent with their payment card information with POST /api/v1/checkout-intents/{id}/confirm. Replace the stripeToken value with the token generated in step 6. 
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"
  }
}'
Checkout intents cannot be updated once created. To change buyer details such as the shipping address, you must create a new checkout intent with the updated information.

​
Step 8: Poll for Final State

After confirmation, poll the GET endpoint again until you reach one of the terminal states:
  • completed: Order was 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"
}
or 
{
  "state": "failed",
  "failureReason": {
    "code": "product_out_of_stock",
    "message": "The item is no longer available."
  }
}
For API V2, the order won’t show up in the Rye console, but you can confirm it was submitted through the API. Note: Rye does not provide post-purchase tracking or webhooks (except for Amazon). Tracking and order updates are sent directly to the buyer via their email address.

​
Next Steps

Congrats, you just submitted your first Rye order! As a next step, read this guide to learn how to get your application production-ready.