Description

n8n-nodes-rye

This is an n8n community node that lets you use the Rye Universal Checkout API in your n8n workflows.

The Rye Universal Checkout API turns any product URL into a completed checkout. Instantly retrieve price, tax, and shipping for any product, and let users buy without ever leaving your native AI experience.

n8n is a fair-code licensed workflow automation platform.

Table of Contents

• Installation
• Operations
• Credentials
• Compatibility
• Usage
• Example Workflows
• Resources
• Support

Installation

Follow the installation guide in the n8n community nodes documentation.

Operations

This node provides the following operations:

Checkout Intent

• Create: Submit a new checkout with a product URL and buyer information
• Get State: Check the state of a checkout intent (with optional automatic polling)
• Confirm: Confirm a checkout intent with a payment method

Brand

• Verify Support: Check if a merchant domain is supported by the Rye API

Credentials

To use this node, you need a Rye API account and access token.

Prerequisites

1. Sign up for a Rye API staging account from the developer console
2. Generate an API access token from your Rye account

For more information, refer to the official Rye Account Registration documentation.

Setting up credentials in n8n

1. In n8n, go to Credentials → New
2. Search for “Rye API”
3. Enter your API URL:
– Staging: https://staging.api.rye.com/api/v1
– Production: https://api.rye.com/api/v1
4. Enter your Access Token (without the HTTP authentication scheme prefix, e.g., “Basic”)
5. Click Save

Compatibility

• Minimum n8n version: 1.0.0
• Tested against: n8n 1.115.3

Usage

Basic Checkout Flow

The typical checkout flow involves these steps:

1. Create a Checkout Intent with a product URL and buyer details
2. Poll for State until the checkout reaches awaiting_confirmation state
3. Confirm the Checkout with a payment token
4. Poll for State again until the checkout reaches completed state

Using the Get State Operation with Polling

The “Get State” operation includes automatic polling functionality to wait for the checkout to reach a terminal state.

#### Polling Parameters

• Enable Polling: When enabled, the node automatically retries checking the state
• Max Attempts: Maximum number of times to check (default: 20). Note: Some merchants may take up to 45 minutes to process.
• Initial Interval (Seconds): Starting wait time (default: 5 seconds)
• Max Interval (Seconds): Maximum wait time between attempts (default: 60 seconds)

#### Checkout States

Terminal States (polling stops automatically):

• awaiting_confirmation – Checkout is ready and awaiting payment confirmation
• completed – Checkout successfully completed
• failed – Checkout failed

Processing States (polling continues):

• retrieving_offer – Initial state after creating a checkout intent; Rye is retrieving the offer from the merchant

> 💡 Tip: If polling times out in the retrieving_offer state, increase the Max Attempts value or handle this state explicitly in your workflow.

#### Polling Behavior

The “Get State” node uses exponential backoff to space out polling attempts, giving you flexibility to manage the Rye API rate limits more effectively.

Wait time starts at initialIntervalSeconds and doubles with each attempt up to maxIntervalSeconds

Example timing: 5s → 10s → 20s → 40s → 60s → 60s…

Note: using the default parameter values (maxAttempts = 20, initialIntervalSeconds = 5, maxIntervalSeconds = 60), the node will poll for up to ~17 minutes

#### Best Practice

After polling completes, use a Switch or IF node to route your workflow based on the final state.

Address Validation

> ⚠️ Important: The Rye API currently only supports US addresses. The node will validate this and throw an error if a non-US country code is provided.

Example Workflows

Complete Checkout with State Routing

Manual Trigger
  ↓
Verify Brand Support (Rye)
  ↓
Create Checkout Intent (Rye)
  ↓
Get State with Polling (Rye)
  ↓
Switch (based on state)
  ├─ awaiting_confirmation → Confirm Checkout (Rye)
  │                            ↓
  │                         Get State with Polling (Rye)
  │                            ↓
  │                         Switch (based on final state)
  │                            ├─ completed → Success notification
  │                            └─ failed → Error notification
  │
  └─ failed → Error notification

Step-by-Step Configuration

#### 1. Verify Brand Support

• Resource: Brand
• Operation: Verify Support
• Domain: amazon.com (or your target merchant domain)

#### 2. Create Checkout Intent

• Resource: Checkout Intent
• Operation: Create
• Product URL: Full URL of the product to purchase
• Buyer Email: Customer’s email address
• Shipping Address: Complete US address details

#### 3. Get State (with Polling) – First Check

• Resource: Checkout Intent
• Operation: Get State
• Checkout Intent ID: {{ $json.id }} (from Create step)
• Enable Polling: true
• Max Attempts: 20
• Initial Interval (Seconds): 5
• Max Interval (Seconds): 60

#### 4. Switch Node – Route Based on Initial State

Configure switch rules:

• Rule 1: {{ $json.state === "awaiting_confirmation" }} → Continue to Confirm
• Rule 2: {{ $json.state === "failed" }} → Error handling

#### 5. Confirm Checkout (if awaiting_confirmation)

• Resource: Checkout Intent
• Operation: Confirm
• Checkout Intent ID: {{ $('Get State').item.json.id }}
• Payment Token: Payment method token from your payment processor (e.g., Stripe)

#### 6. Get State (with Polling) – Final Check

• Resource: Checkout Intent
• Operation: Get State
• Checkout Intent ID: {{ $('Confirm Checkout').item.json.id }}
• Enable Polling: true
• Max Attempts: 20
• Initial Interval (Seconds): 5
• Max Interval (Seconds): 60

#### 7. Switch Node – Route Based on Final State

Configure switch rules:

• Rule 1: {{ $json.state === "completed" }} → Success handling
• Rule 2: {{ $json.state === "failed" }} → Error handling

Resources

• n8n community nodes documentation
• Rye API Documentation
• Rye Universal Checkout Guide

Support

For issues or questions:

• Node Issues: GitHub Issues
• n8n Community: n8n Forum

License

MIT