Rye Universal Checkout

Load references/api-reference.md alongside either workflow when you need exact endpoint signatures, SDK method names, or request/response shapes.

Key constraints (always apply)

Before proceeding with ANY Rye operation, be aware of these hard constraints:

• US-only shipping — International addresses will cause the checkout intent to fail
• Physical products only — Digital goods, subscriptions, and gift cards are not supported
• One product per checkout — Multiple quantities of the same product are fine, but multi-product carts are not supported
• 45-minute window — Checkout intents expire 45 minutes after creation; they are immutable (create a new one to change details)
• Rate limits — 5 requests/second, 50 requests/day by default (contact Rye to increase)
• Polling — Poll GET /checkout-intents/{id} every 10 seconds; allow up to 45 minutes for offer retrieval
• Payment — Rye is merchant of record; payment is tokenized via Stripe through Rye

How it works (overview)

The recommended two-call workflow:

1. Look up the product — GET /api/v1/products/lookup?url=... returns structured product data (price, availability, images, description) so you can verify the product is purchasable before committing
2. Create a checkout intent — POST /api/v1/checkout-intents with the product URL and buyer details; Rye handles offer resolution, tax, shipping, payment, and order confirmation

Every checkout flows through a Checkout Intent lifecycle:

Product Lookup → Create Intent → retrieving_offer → awaiting_confirmation → Confirm → placing_order → completed
  (optional)                            ↓                    ↓                                ↓
                                     failed               failed                           failed

Two checkout paths:

• Multi-step (POST /checkout-intents → poll → confirm) — Show the buyer final costs before charging. Use for user-facing flows.
• Single-step (POST /checkout-intents/purchase) — One call, fire-and-forget. Use for automated workflows that don't need buyer approval.

Authentication

All requests require:

Authorization: Basic YOUR_API_KEY

Get your key from the Rye Console → Account page.

Always start with staging. Use Stripe test token tok_visa for payments.

SDKs

SDKs provide createAndPoll() and confirmAndPoll() helpers that handle polling automatically.

Test product URLs (staging)

• Shopify: https://flybyjing.com/collections/shop/products/the-big-boi
• Shopify (variant): https://www.raakachocolate.com/products/blueberry-lemon?variant=41038993227863
• Amazon: https://www.amazon.com/Apple-MX532LL-A-AirTag/dp/B0CWXNS552/

Feedback

When to surface this

You MUST proactively offer to file a feature request or bug report whenever:

• You identify a capability gap — The user needs something the Rye API doesn't support (e.g., product search, international shipping, digital goods). Include "file a feature request with the Rye team" as one of the options alongside any workarounds.
• The user expresses a wish — Phrases like "it would be great if...", "I wish this could...", "can Rye support...", or any suggestion for a new API feature. Offer to create a GitHub issue on their behalf.
• A constraint blocks their use case — If a key limitation (US-only, single product, rate limits) prevents what the user is building, mention the option to request that the Rye team address it.
• You encounter a bug or unexpected behavior — API errors, SDK issues, or documentation gaps during integration.

Do NOT wait for the user to ask about filing feedback — surface it as an option the moment you recognize the pattern.

How to file

gh issue create --repo rye-com/agent-skills \
  --title "[Feature Request] <brief summary>" \
  --body "## Description

<what the user wants or what went wrong>

## Context

- Use case: <what they're building>
- Skill: rye-universal-checkout
- Environment: <staging/production>"

Use title prefixes to categorize: [Feature Request], [Bug], [Integration Issue].

Always confirm with the user before creating the issue.

Documentation links

• Quickstart: https://docs.rye.com/api-v2/example-flows/simple-checkout
• Single-step checkout: https://docs.rye.com/api-v2/example-flows/single-step-checkout
• API Reference: https://docs.rye.com/api-v2-experimental/api-reference
• Lifecycle: https://docs.rye.com/api-v2/checkout-intent-lifecycle
• Errors: https://docs.rye.com/api-v2/errors
• Go Live: https://docs.rye.com/api-v2/go-live