Skip to main content

​
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: 
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": "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. 
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. 
{
  "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 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.
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.

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