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

# Checkout

> Checkout endpoint expectations and AAP metadata.

# Checkout

Checkout is a server-side handoff that preserves recommendation context without treating the browser as the authority for attribution or conversion state. Rako keeps the AAP conversion ledger authoritative.

The high-level path is:

```text theme={null}
Agent or website → Rako API → hosted checkout handoff → outcome evidence → AAP conversion ledger
```

Rako is not the merchant of record and does not hold buyer funds. Checkout starts the buyer journey; conversion requires later platform-side outcome evidence such as a payment event, merchant report, or configured milestone.

## Endpoint

```http theme={null}
POST /v1/checkout
Authorization: Bearer <agent-api-key>
Content-Type: application/json
```

```json theme={null}
{
  "sessionId": "01KN6KV0TWMH8VS6TDS3S7V2EJ",
  "recommendationId": "01KN6KWQDZ6Y5HPW8KFSDPKNSQ",
  "userDetails": {}
}
```

| Field              | Required | Description                                                       |
| ------------------ | -------- | ----------------------------------------------------------------- |
| `sessionId`        | Yes      | Session from the offer search that produced the recommendation.   |
| `recommendationId` | Yes      | Recommendation recorded with `POST /v1/recommend`.                |
| `userDetails`      | No       | Reserved for vertical-specific details collected before checkout. |

## Expected behaviour

Rako validates that:

* the session exists and has not expired
* the recommendation exists
* the recommendation's offer still exists
* the merchant exists
* the merchant has checkout configured when hosted checkout is enabled

If validation succeeds, Rako creates a checkout object or hosted checkout link and marks the session as `checkout`. The returned URL is a handoff, not proof of payment, conversion, commission, or settlement eligibility.

```json theme={null}
{
  "transactionId": "01K...",
  "paymentId": "pay_...",
  "checkoutUrl": "https://...",
  "status": "awaiting_payment",
  "backend": "orchestrated",
  "mode": "checkout",
  "amount": 10,
  "currency": "GBP",
  "merchant": { "id": "01J...", "name": "Example Merchant" },
  "offer": { "id": "01J...", "name": "30GB Rolling Monthly", "provider": "Example Mobile" },
  "session": { "id": "01KN6KV0TWMH8VS6TDS3S7V2EJ", "status": "checkout" }
}
```

## AAP metadata

Rako sets attribution metadata when it creates the checkout handoff. Agents, browsers, and client-side code should not construct or mutate attribution, source, conversion, or settlement fields.

```json theme={null}
{
  "metadata": {
    "aap_code": "aap://rako.sh/v1/...",
    "aap_recommendation_id": "01KN6KWQDZ6Y5HPW8KFSDPKNSQ",
    "aap_session_id": "01KN6KV0TWMH8VS6TDS3S7V2EJ",
    "aap_offer_id": "01JQXK1001EXAMPLEOFFER001",
    "aap_merchant_id": "01JQXK0001EXAMPLEMERCH001",
    "aap_agent_id": "agent_..."
  }
}
```

The metadata can be stored with the checkout or payment record and returned with platform-side outcome evidence. This creates the join key between the later outcome event and the AAP recommendation ledger.

<Warning>
  Metadata joining is not, by itself, production-grade verification. A payment-observed conversion should only be called verified after Rako authenticates the event source and checks the signed AAP Code, recommendation payload, payment amount, and successful payment status. The hosted implementation is still closing this full gate.
</Warning>

## Failure responses

Common failure cases:

| Status | Error                                         | Meaning                                                                        |
| ------ | --------------------------------------------- | ------------------------------------------------------------------------------ |
| `400`  | `sessionId and recommendationId are required` | Required identifiers were not provided.                                        |
| `404`  | `Session not found`                           | The checkout does not refer to a known session.                                |
| `404`  | `Recommendation not found`                    | The checkout does not refer to a recorded recommendation.                      |
| `410`  | `Session expired`                             | The recommendation window has expired.                                         |
| `503`  | `Merchant has no connected payment processor` | The merchant has not configured a payment processor for hosted checkout.       |
| `502`  | `Could not create checkout`                   | The checkout or payment-processing layer rejected the hosted checkout request. |

## Relationship to `/v1/purchase`

Some SDK and MCP integrations may use `/v1/purchase` for a related infrastructure path. It accepts a `recommendationId` and can create either:

* a user checkout link; or
* an autonomous payment attempt when a legitimate stored payment method is supplied.

For most developer integrations, start with `/v1/checkout`: record the recommendation, request a hosted checkout URL, and let later platform-side evidence determine whether a conversion occurred.