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

> Conversion events, webhooks, reconciliation, and payable milestones.

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

<Warning>
  Rako's hosted payment-verification path is still being hardened. Public docs use "verified" to describe the intended conversion state after authenticated payment events and reconciliation checks pass. Until webhook authentication, AAP Code verification on webhook receipt, payload matching, amount matching, and payment-status checks are deployed and tested, treat payment-observed conversions as beta evidence rather than a trustless production guarantee.
</Warning>

## Conversion sources

| Source                     | Typical path                                                                          | Verification level                                                                     |
| -------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Payment webhook            | Merchant payment processor confirms a successful payment and returns AAP metadata.    | Verified checkout conversion only after authentication and reconciliation checks pass. |
| 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  | Merchant payment processor reports refund, chargeback, or dispute lifecycle events.   | Used for clawback/reconciliation.                                                      |

## Verified checkout conversions

For instant checkout, Rako expects platform-side payment evidence from a payment processor or payment orchestration layer. In the production design, Rako authenticates the event, reads AAP metadata, verifies the signed AAP Code, checks the payload and amount against the recommendation, and records a verified conversion only when those checks pass.

Handled successful payment event names include:

* `payment_intent.payment_succeeded`
* `payment_intent.succeeded`
* `payment_succeeded`

The current beta flow reads payment metadata, looks up the recorded recommendation, computes commission, and inserts a conversion with `conversionPath: "verified_payment"`. The full production gate also requires webhook authentication plus AAP Code, payload, amount, and payment-status verification before that label should be treated as production-grade.

```json theme={null}
{
  "received": true,
  "status": "conversion_recorded",
  "conversionId": "01K...",
  "verification": "beta_payment_observed"
}
```

The conversion starts as `pending` while validation, refund, dispute, and settlement windows remain open.

## Merchant-reported conversions

Merchants can report a completed sale or payable action with:

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

```json theme={null}
{
  "sessionId": "01KN6KV0TWMH8VS6TDS3S7V2EJ",
  "orderReference": "ORD-100045",
  "transactionValue": 10
}
```

Required fields:

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

Response:

```json theme={null}
{
  "conversionId": "01K...",
  "sessionId": "01KN6KV0TWMH8VS6TDS3S7V2EJ",
  "orderReference": "ORD-100045",
  "transactionValue": 10,
  "commission": {
    "amount": 8,
    "networkFee": 1.6,
    "builderPayout": 6.4,
    "type": "cpa"
  },
  "status": "pending",
  "validationPeriodDays": 30
}
```

Merchant-reported conversions are useful for verticals where the payable outcome is not a simple checkout payment: broadband installation, insurance policy start, regulated applications, recurring subscriptions, or first-bill milestones.

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

Merchants record milestones against a conversion:

```http theme={null}
POST /v1/conversions/{conversionId}/milestones
Authorization: Bearer <merchant-api-key>
Content-Type: application/json
```

```json theme={null}
{
  "step": "service_activated",
  "status": "completed",
  "metadata": {
    "activatedAt": "2026-04-15T10:30:00Z",
    "serviceReference": "BB-88391"
  }
}
```

Milestones do not replace the conversion record. They provide the audit trail needed to validate, delay, settle, or claw back commission.

## Refunds, disputes, and clawbacks

Payment webhook handling also reconciles negative lifecycle events:

* `refund.succeeded` or `charge.refunded` marks the conversion `clawed_back`
* `dispute.opened` or `charge.dispute.created` marks the conversion `disputed`
* `dispute.closed` resolves the dispute according to the configured policy

This is designed to keep the AAP ledger aligned with the merchant's payment reality instead of relying on agent self-reporting. The production trust level depends on the payment webhook being authenticated and reconciled against the signed AAP metadata.

## Settlement fields

Each conversion stores the values Rako needs for invoicing and payouts:

* `transactionValue`
* `commissionAmount`
* `networkFee`
* `builderPayout`
* `conversionPath`
* `status`
* `orderReference`
* `recommendationId`, `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.