​
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. 
curl --request POST \
  --url https://staging.api.rye.com/api/v1/checkout-intents \
  --header 'Authorization: Basic ADD_HEADER_FROM_CONSOLE' \
  --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/earl-grey?variant=40131463118935"
  }'

​
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 ADD_HEADER_FROM_CONSOLE'
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: Request and Tokenize Payment

Retrieve a payment token for the credit card you want to use. Follow the steps here.

​
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 ADD_HEADER_FROM_CONSOLE' \
  --header 'Content-Type: application/json' \
  --data '{
  "paymentMethod": {
    "stripeToken": "tok_1RkrWWHGDlstla3f1Fc7ZrhH",
    "type": "stripe_token"
  }
}'

​
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 ADD_HEADER_FROM_CONSOLE'
Example responses: 
{
  "state": "completed"
}
or 
{
  "state": "failed",
  "failureReason": {
    "code": "product_out_of_stock",
    "message": "The item is no longer available."
  }
}

​
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.