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.
Conversions
A conversion is the ledger record that connects an agent recommendation to a merchant outcome.
Conversions are not created by the agent. They are created when Rako can reconcile the recommendation with payment, merchant, or milestone evidence.
Conversion sources
| Source | Typical path | Verification level |
|---|
| Payment webhook | PSP confirms a successful payment and returns AAP metadata. | Verified checkout conversion. |
| Merchant conversion report | Merchant reports sessionId, orderReference, and transaction value. | Pending validation. |
| Milestone update | Merchant reports progress after an initial conversion, such as install or activation. | Depends on configured flow. |
| Refund or dispute webhook | PSP reports refund, chargeback, or dispute lifecycle events. | Used for clawback/reconciliation. |
Verified checkout conversions
For instant checkout, Rako expects a payment event from the merchant’s PSP. Rako receives the payment event, reads AAP metadata, and records a verified conversion.
Handled successful payment event names include:
payment_intent.payment_succeededpayment_intent.succeededpayment_succeeded
Rako reads the payment metadata, looks up the recorded recommendation, computes commission, and inserts a conversion with conversionPath: "verified_payment".
{
"received": true,
"status": "conversion_recorded",
"conversionId": "01K...",
"verification": "verified"
}
pending while validation, refund, dispute, and settlement windows remain open.
Merchant-reported conversions
Merchants can report a completed sale or payable action with:
POST /v1/conversions
Authorization: Bearer <merchant-api-key>
Content-Type: application/json
{
"sessionId": "01KN6KV0TWMH8VS6TDS3S7V2EJ",
"orderReference": "ORD-100045",
"transactionValue": 10
}
| Field | Description |
|---|
sessionId | The AAP session that led to the recommendation. |
orderReference | Merchant-side order, application, policy, or payment reference. |
transactionValue | Gross value used to calculate percentage or hybrid commission. |
{
"conversionId": "01K...",
"sessionId": "01KN6KV0TWMH8VS6TDS3S7V2EJ",
"orderReference": "ORD-100045",
"transactionValue": 10,
"commission": {
"amount": 8,
"networkFee": 1.6,
"builderPayout": 6.4,
"type": "cpa"
},
"status": "pending",
"validationPeriodDays": 30
}
Conversion flows and milestones
Some products require multiple events before a commission should settle. Rako supports merchant-configured conversion flows such as:
| Flow type | Example milestones |
|---|
instant_checkout | payment_received, order_confirmed |
quote_application | quote_requested, application_submitted, application_approved, payment_received |
install_activation | order_placed, install_scheduled, install_completed, service_activated |
policy_start | quote_requested, policy_issued, cooling_off_complete, first_bill_paid |
POST /v1/conversions/{conversionId}/milestones
Authorization: Bearer <merchant-api-key>
Content-Type: application/json
{
"step": "service_activated",
"status": "completed",
"metadata": {
"activatedAt": "2026-04-15T10:30:00Z",
"serviceReference": "BB-88391"
}
}
Refunds, disputes, and clawbacks
Payment webhook handling also reconciles negative lifecycle events:
refund.succeeded or charge.refunded marks the conversion clawed_backdispute.opened or charge.dispute.created marks the conversion disputeddispute.closed resolves the dispute according to the configured policy
This keeps the AAP ledger aligned with the merchant’s payment reality instead of relying on agent self-reporting.
Settlement fields
Each conversion stores the values Rako needs for invoicing and payouts:
transactionValuecommissionAmountnetworkFeebuilderPayoutconversionPathstatusorderReferencerecommendationId, sessionId, merchantId, and agentId
For registered builders, the standard split is 80% builder payout and 20% Rako network fee. Anonymous agent traffic can still be attributed, but builder payout is zero until the builder is registered.
