Skip to main content

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

Rako attributes a conversion when an agent recommendation carries AAP context into the merchant checkout or conversion flow. The production model is deliberately boring infrastructure: 
search → recommend → checkout → convert → settle
The agent asks Rako for eligible offers that match the user’s intent. 
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. 
{
  "sessionId": "01KN6KV0TWMH8VS6TDS3S7V2EJ",
  "offers": [
    {
      "id": "01JQXK1001SMARTY1GB000001",
      "provider": "SMARTY",
      "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. 
POST /v1/recommend
Content-Type: application/json

{
  "sessionId": "01KN6KV0TWMH8VS6TDS3S7V2EJ",
  "offerId": "01JQXK1001SMARTY1GB000001",
  "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. 
{
  "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. 
POST /v1/checkout
Content-Type: application/json

{
  "sessionId": "01KN6KV0TWMH8VS6TDS3S7V2EJ",
  "recommendationId": "01KN6KWQDZ6Y5HPW8KFSDPKNSQ"
}
For merchants with a connected payment processor, Rako creates a hosted checkout link and embeds AAP metadata into the payment object. The user pays on the merchant’s PSP-hosted checkout. Rako does not hold funds or replace the merchant’s processor.

​
4. Convert

A conversion is recorded when Rako receives trustworthy evidence that the payable outcome happened. For instant checkout, that evidence is normally a payment webhook from the merchant’s payment processor. For longer-cycle verticals, the evidence can be a merchant-reported conversion plus milestones such as install_scheduled, service_activated, or first_bill_paid.

​
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.
  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 a SMARTY 30GB rolling monthly offer.
  3. The agent recommends SMARTY 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 pays on the PSP-hosted page.
  6. Rako receives a payment succeeded webhook from the merchant’s PSP with the AAP metadata.
  7. Rako records a verified conversion, calculates the commission split, and starts the validation period.