> ## Documentation Index
> Fetch the complete documentation index at: https://docs-test.rye.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout Intent Lifecycle

> Understand the states a Checkout Intent progresses through, from creation and offer retrieval to order placement and completion.

A Checkout Intent represents the end‑to‑end process of purchasing a product through Rye. Each intent progresses through a series of states, from initial creation to final order placement. Understanding these states helps you design robust checkout flows and handle errors gracefully.

## States

* `retrieving_offer` - When a Checkout Intent is first created, Rye fetches live pricing, availability, taxes, and shipping options from the merchant for the provided `productUrl`.
* `awaiting_confirmation` - An offer is ready and includes pricing and availability details. Your app can collect payment details from the buyer.
* `placing_order` - A payment method was provided and Rye is executing the checkout on the merchant site.
* `completed` - The order was successfully placed and confirmed by the merchant.
* `failed` - The checkout could not be completed (e.g., out of stock, unsupported merchant, declined payment).

```mermaid theme={null}
stateDiagram-v2
    [*] --> retrieving_offer: Create Checkout Intent

    retrieving_offer --> awaiting_confirmation
    retrieving_offer --> failed

    awaiting_confirmation --> placing_order: Confirm Checkout Intent
    awaiting_confirmation --> failed

    placing_order --> completed
    placing_order --> failed

    completed --> [*]
    failed --> [*]
```

## Sequence

The diagram below shows the typical happy path (Create -> Confirm -> Fulfill) plus common branches.

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor User
    participant Your App
    participant Rye API

    Note over Your App,Rye API: 1. Create an intent with buyer and product URL
    Your App->>Rye API: POST /api/v1/checkout-intents { buyer, productUrl, quantity }
    Rye API-->>Your App: 201 Created { id, state: "retrieving_offer" }

    Note over Rye API: Fetch live offer (price, tax, shipping)
    Rye API-->>Your App: 200 OK { id, state: "awaiting_confirmation", offer: {...} }

    Note over User,Your App: 2. Collect payment method
    User->>Your App: Enters card details
    Your App->>Rye API: POST /api/v1/checkout-intents/{id}/confirm { paymentMethod: {...} }
    Rye API-->>Your App: 200 OK { id, state: "placing_order" }

    Note over Rye API: Execute merchant checkout with confirmed funds
    Rye API-->>Your App: 200 OK { id, state: "completed", order: {...} }

    alt Failure cases
      Rye API-->>Your App: 4xx/5xx { id, state: "failed", error: {...} }
    end
```

## Notes

* **Polling Duration:** Developers should poll for up to 45 minutes during the `retrieving_offer state`, as the checkout intent may take that long to transition to the `awaiting_confirmation` state.
* **Checkout Intent Window:** Developers have 45 minutes to confirm a checkout intent. The timer starts as soon as the checkout intent is created in our system. After that time, the checkout intent will be expired and in a `failed` state, and any confirmation requests for the checkout intent will return a `checkout_intent_expired` as the failure reason.