> ## 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.

# Attribution Flow

> How Rako attributes agent-driven commerce.

# Attribution Flow

Rako attributes a conversion when an agent recommendation carries AAP context into the merchant checkout or conversion flow.

The model is deliberately boring infrastructure:

```text theme={null}
search → recommend → checkout → convert → settle
```

## 1. Search

The agent asks Rako for eligible offers that match the user's intent.

```http theme={null}
GET /v1/offers?vertical=sim&data_gb_min=10&contract_months=0
```

Rako returns active offers and a session identifier. Offers include commercial terms and a signed AAP Code that identifies the merchant, offer, price, currency, and commission basis.

```json theme={null}
{
  "sessionId": "01KN6KV0TWMH8VS6TDS3S7V2EJ",
  "offers": [
    {
      "id": "01JQXK1001EXAMPLEOFFER001",
      "provider": "Example Mobile",
      "name": "30GB Rolling Monthly",
      "price": 10,
      "currency": "GBP",
      "aapCode": "aap://rako.sh/v1/..."
    }
  ],
  "expiresAt": "2026-04-03T08:00:00.000Z"
}
```

Sessions are bounded. If the user does not reach checkout during the session window, attribution must be restarted or recovered through a lower-confidence fallback path.

## 2. Recommend

When the agent presents an offer, it records the recommendation.

```http theme={null}
POST /v1/recommend
Content-Type: application/json

{
  "sessionId": "01KN6KV0TWMH8VS6TDS3S7V2EJ",
  "offerId": "01JQXK1001EXAMPLEOFFER001",
  "context": "User wanted a no-contract SIM with at least 10GB of data"
}
```

The response includes a `recommendationId`. This is the attribution handle used at checkout.

```json theme={null}
{
  "recommendationId": "01KN6KWQDZ6Y5HPW8KFSDPKNSQ",
  "fallbackUrl": "https://aap.link/r/01KN6KWQDZ6Y5HPW8KFSDPKNSQ",
  "attributionRecorded": true
}
```

## 3. Checkout

When the user chooses the offer, the agent initiates checkout with the session and recommendation.

```http theme={null}
POST /v1/checkout
Content-Type: application/json

{
  "sessionId": "01KN6KV0TWMH8VS6TDS3S7V2EJ",
  "recommendationId": "01KN6KWQDZ6Y5HPW8KFSDPKNSQ"
}
```

For merchants with hosted checkout configured, Rako creates a backend-owned checkout link and can attach AAP context to the checkout or payment record. The returned URL is a handoff for the buyer; it does not prove payment, conversion, commission, or settlement eligibility.

## 4. Convert

A conversion is recorded when Rako receives platform-side evidence that the payable outcome happened.

For instant checkout, that evidence may be an authenticated payment event from a payment processor plus reconciliation against signed AAP metadata. For longer-cycle verticals, the evidence can be a merchant-reported conversion plus milestones such as `install_scheduled`, `service_activated`, or `first_bill_paid`.

<Warning>
  The hosted payment-verification path is in beta. Do not treat payment-observed conversions as trustless or production-grade until webhook authentication, AAP Code verification on event receipt, payload matching, amount matching, and payment-status checks are deployed and tested.
</Warning>

## 5. Settle

Conversions remain in the ledger through validation, refund, dispute, clawback, and settlement states. Once a conversion is eligible, Rako calculates:

* merchant commission owed
* Rako network fee
* builder payout
* invoice and settlement status

The result is binary attribution: the conversion either flowed through an AAP recommendation that can be reconciled, or it did not.

## Example: agent-recommended SIM checkout

1. A user asks an agent for a cheap UK SIM with no contract and at least 10GB of data.
2. The agent searches Rako and receives an Example Mobile 30GB rolling monthly offer.
3. The agent recommends Example Mobile and records why it made the recommendation.
4. The user says yes; the agent calls checkout and shows the returned checkout URL.
5. The user completes the hosted checkout journey.
6. Rako receives platform-side outcome evidence with the AAP metadata.
7. Rako records a conversion if the evidence validates, then applies validation, refund, dispute, clawback, and settlement rules.