Why We Built an SDK for a 3-Endpoint API
Arjun Bhargava
Co-founder and CEO @ Rye
6 minutes read
Rye's checkout API is three endpoints. The SDK wraps them with the reliability infrastructure — retries, idempotency, polling — that every production integration needs and nobody wants to build from scratch.
TL;DR / Key Takeaways
Rye's core API is three endpoints. The entire checkout flow — create, poll, confirm — fits in a single code snippet. So why build an SDK?
The SDK handles the things developers consistently miss when integrating directly: automatic retries on transient failures, idempotency keys on every mutating request, and helpers that poll checkout status so you don't have to write your own loop.
We've seen what happens without these. Orders fail silently. Duplicate charges slip through. Polling logic burns API quota or misses state transitions. The SDK exists to make these problems impossible, not just unlikely.
The Core Flow Is Three Calls
Rye's checkout flow is deliberately simple. The entire purchase lifecycle is three calls:
Create a checkout intent with a product URL and buyer details.
Poll until the offer resolves — real-time pricing, shipping, and tax from the merchant.
Confirm with a tokenized payment method.
Product URL in, confirmed order out. If you've read the three API calls from product URL to confirmed order, you've seen the actual integration — that's the whole contract. The SDK even offers a purchase() method that collapses all three into a single call.
The broader API covers product data lookup, shipment tracking, and billing — but the checkout core is what developers interact with most, and it's intentionally small. A tight API surface means less to learn, less to break, and less to maintain. For developers building AI agents that need to buy things, the last thing they want is a sprawling integration. They want to send a URL and get back an order.
The Case for an SDK
A clean API doesn't guarantee a clean integration.
When your agent sends a checkout intent to Rye, we're navigating a live merchant checkout flow on the open web. Networks drop packets. Merchant sites go intermittently unavailable. Checkout flows that worked yesterday break because a retailer pushed a site update at 2 AM. The API abstracts all of that complexity — but the network between your code and our API doesn't get the same treatment. And at production volume, every gap in your HTTP integration becomes a support ticket.
What the SDK Actually Does
The SDK adds three things that developers consistently skip when integrating directly. These are the kind of details that feel like polish during development and turn into production incidents at scale.
Automatic Retries
Transient network errors — timeouts, 502s, connection resets — are a fact of life in production. The SDK retries failed requests twice by default with exponential backoff, automatically distinguishing between retryable errors (connection failures, 408 timeouts, 409 conflicts, 429 rate limits, and 5xx server errors) and permanent failures that shouldn't be retried. You can tune this per-client or per-request with maxRetries.
We've seen this pattern repeatedly in early integrations. A developer's agent completes 99 out of 100 purchases cleanly. The one that fails does so silently — the HTTP call timed out, the agent moved on, and the user never got their order. Adding retry logic after the fact is straightforward, but getting the backoff timing and error classification right takes iteration. The SDK ships with these tuned from production experience.
Idempotency Keys
Every non-GET request the SDK sends automatically includes an Idempotency-Key header — a unique UUID generated per request. This guarantees that if a network failure triggers a retry, the operation executes exactly once, not twice.
This matters most at the confirm step. If your agent sends a confirmation, the network drops the response, and the SDK retries. Without an idempotency key, you've just charged the customer twice for the same order. We've seen this happen. Transaction volume spikes, network conditions degrade, and a retry without idempotency turns one order into two charges.
Raw API integrations can absolutely handle idempotency. Most developers know they should. In practice, it's the thing that gets added to the backlog and shipped after the first duplicate charge incident. The SDK makes it invisible.
Polling Helpers
After creating a checkout intent, the API resolves the offer asynchronously — fetching live pricing, shipping, and tax from the merchant. Your code needs to poll until the intent reaches awaiting_confirmation. Then after confirming, you poll again until the order reaches completed or failed.
The logic gets complicated fast.
Poll too aggressively and you burn API quota. Poll too slowly and your agent sits idle while the user waits. Don't handle the failed state and your agent hangs forever. Don't set a timeout and a slow merchant response blocks your entire purchasing pipeline.
The SDK's polling helpers collapse this into single awaitable calls:
createAndPoll()— creates an intent and polls until the offer is ready or fails.confirmAndPoll()— confirms with payment and polls until the order completes or fails.pollUntilCompleted()andpollUntilAwaitingConfirmation()for more granular control.
All methods support configurable intervals (default 5 seconds) and max attempts (default 120 — roughly 10 minutes). If polling times out, the SDK throws a PollTimeoutError with the intent ID and attempt count so you can decide how to recover. No loops, no timers, no state machine.
What Happens Without These
Every feature in the SDK traces back to a real failure mode we kept seeing in developer integrations:
Silent order failures. A transient network error during checkout confirmation. No retry. The agent tells the user "your order is confirmed" based on the request being sent, not the response being received. The order never went through.
Duplicate charges. A retry without idempotency. The user gets charged twice. The developer's support queue lights up. Trust in the agent, and in the infrastructure underneath it, takes a hit.
Polling bugs. A hand-rolled polling loop that doesn't handle edge cases. The agent checks status every 100ms and hits rate limits. Or it checks every 30 seconds and the user stares at a loading spinner. Or the intent fails and the loop never terminates. The SDK's createAndPoll() and confirmAndPoll() make this entire class of bug disappear — one method call, one awaited result.
Each of these is straightforward to fix once you know it exists. Most developers discover them after production traffic has already exposed the gap. The SDK makes these categories of bugs impossible by default.
What the SDK Is Really For
The value of an SDK scales with the consequences of getting the integration wrong, not the number of endpoints it wraps. A checkout API where failures mean lost orders, duplicate charges, and broken user trust has high consequences, even if the core flow is three calls.
The SDK removes the complexity that lives between your code and ours — the retry logic, the idempotency guarantees, the async state management that every production integration needs but nobody wants to build from scratch. Available in TypeScript, Python, Ruby, and Java — install checkout-intents from your package manager and you're running.
Ecommerce is hard. Even with a clean API, there are sharp edges. The SDK smooths them out.
Frequently Asked Questions
Do I need the SDK to use Rye's API?
No. The API is a standard REST interface — you can integrate with any HTTP client in any language. The SDK is optional. It handles retries, idempotency, and polling out of the box, which saves you from building that infrastructure yourself. But if you prefer raw HTTP calls, the API reference has everything you need.
What languages does the SDK support?
The SDK is available in four languages: TypeScript, Python, Ruby, and Java — all published as checkout-intents on their respective package managers (npm, PyPI, RubyGems, Maven Central). Pick whichever fits your stack.
How does the SDK handle payment security?
The SDK passes tokenized payment methods — from providers like Stripe, Basis Theory, or others — to the API. No raw card data ever touches your code or the SDK. For details on how tokenization keeps PCI scope off your plate, see our tokenization guide.
What's the difference between the SDK and the LLM Quickstart?
The LLM Quickstart helps you integrate Rye using AI coding assistants — copy-paste prompts, agent config files, and MCP support. The SDK is the runtime library your code actually calls in production. Use the LLM Quickstart to build your integration faster. Use the SDK to run it reliably.
Can I use the SDK to access the Product Data API too?
Yes. The SDK includes client.products.lookup() for the Product Data API, plus shipment tracking via client.shipments and billing queries. Same package, same retry and idempotency guarantees across all endpoints.
Start Building
Rye's SDK wraps a deliberately simple API with the reliability infrastructure that production checkout requires. Retries, idempotency, and polling — handled. Your agent focuses on what it's good at. The SDK handles the rest.
Install the SDK in your language of choice — TypeScript, Python, Ruby, or Java — all available as checkout-intents on their respective package managers.
Product
Resources