Building AI Commerce Agents: Infrastructure Trade-Offs, APIs, and the Checkout Problem

A typical integration with the Universal Checkout API uses a checkout intent pattern. Your AI agent handles discovery and recommendation. When it's time to purchase, the agent creates a checkout intent with a product URL and buyer details. The API resolves live pricing asynchronously. Once the offer is ready, the agent presents costs to the user and confirms with a tokenized payment method.

Creating a Checkout Intent

The flow is three calls: create, poll, confirm. Here's how it looks against the live API:

# Step 1: Create a checkout intent with product URL and buyer details
curl --request POST \\
  --url https://api.rye.com/api/v1/checkout-intents \\
  --header "Authorization: Basic $RYE_API_KEY" \\
  --header "Content-Type: application/json" \\
  --data '{
    "productUrl": "https://flybyjing.com/collections/shop/products/sichuan-chili-crisp",
    "quantity": "1",
    "buyer": {
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane@example.com",
      "phone": "212-333-2121",
      "address1": "123 Main St",
      "address2": "Apt 4",
      "city": "New York",
      "province": "NY",
      "country": "US",
      "postalCode": "10001"
    }
  }'

The API returns a checkout intent with an ID and an initial state. Offer resolution is asynchronous — the API fetches live pricing, shipping, and tax from the merchant in the background. Poll the GET endpoint until the state reaches awaiting_confirmation:

# Step 2: Poll until the offer is resolved
curl --request GET \\
  --url https://api.rye.com/api/v1/checkout-intents/{id} \\
  --header "Authorization: Basic $RYE_API_KEY"

Before confirming, inspect the response to verify shipping options, taxes, total cost, and offer availability. Then confirm with a Stripe token — this is where payment happens:

# Step 3: Confirm the checkout intent with payment
curl --request POST \\
  --url https://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"
    }
  }'

After confirming, poll the GET endpoint again until the intent reaches a terminal state: completed (order placed successfully) or failed (with a failureReason containing error code and message).

Three calls. Product URL in, confirmed order out. Your agent code doesn't need to know anything about the merchant's checkout flow, platform, or integration status.

For a complete working example — including Stripe tokenization and Vercel AI SDK tool-calling — see the AI chat storefront tutorial in the docs. For the full API reference, see the simple checkout quickstart.

A few implementation details worth noting:

Checkout intents cannot be updated once created — if buyer details change, create a new intent. Stripe tokens are single-use, so generate a new one per order. Orders currently ship to U.S. addresses only.

The API also supports automatic promo code discovery and price constraints — set discoverPromoCodes to true and the system scans for and applies valid codes at checkout, and use the constraints object to set maximum total or shipping price thresholds so orders are only placed within budget.

The Stripe payment flow is marked for deprecation in favor of a Basis Theory integration — check the payment flow setup guide for the latest supported tokenization method. In staging, use the test token tok_visa to place orders without charging a real card.

Multi-Item Orders

The checkout intent pattern above handles single-product purchases. For agents that need to build multi-item orders across multiple merchants — say, buying a complete outfit or restocking a supply list — you'd create a separate checkout intent per product URL and manage them in parallel. Each intent resolves independently against its respective merchant, so your agent can present a consolidated offer to the user and confirm all intents once approved.

Where This Fits in the Stack

Most AI agent architectures separate the reasoning layer from the action layer. The reasoning layer — your LLM, your prompt chain, your retrieval pipeline — decides what to buy. The action layer executes the transaction. AI commerce infrastructure sits entirely in the action layer.

This separation matters because it means you're not locked into a specific AI model or framework. Whether you're building with OpenAI's Agents SDK, Anthropic's Claude, an open-source model, or a custom pipeline, the checkout API works the same way. You send a URL and a payment token. You get back an order.

It also means the commerce layer can evolve independently. When a merchant redesigns their checkout flow or a new e-commerce platform gains market share, the infrastructure adapts — your agent code doesn't need to change. This is the same principle that made Stripe successful for web payments: abstract the complexity behind a stable API surface so developers can focus on their product, not on payment plumbing.

In practice, this separation also simplifies testing. You can mock the checkout API response in your development environment and test your agent's purchasing logic end-to-end without hitting live merchant sites. Your staging environment calls the sandbox API. Your production environment calls the live API. The agent code is identical across environments — only the API key changes. For a working reference implementation that shows this pattern with Vercel AI SDK and Stripe, see the AI chat storefront tutorial.

The Protocol Interoperability Question

One question developers are increasingly asking: should I adopt ACP, UCP, or both? The honest answer is that the protocol landscape is still consolidating. ACP and UCP are designed to be complementary rather than competing — UCP explicitly supports interoperability with MCP and A2A — but the practical reality is that each protocol has different merchant coverage, and no single standard covers the full market today.

A universal checkout API sidesteps this fragmentation. Because it operates at the browser level rather than the protocol level, it works regardless of which standard (if any) a merchant has adopted. For developers who want to ship today and support every merchant, this is the pragmatic path. For developers who need deep merchant integration — returns processing, loyalty program access, structured product feeds — protocol-based approaches offer capabilities that browser automation can't replicate.