> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.orbitdev.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Report Conversions with the Advertising API

> Use the Advertising API conversion action to report CPA events. Learn about authentication, body fields, duplicate handling, and charging.

The `conversion` action of the Advertising API records idempotent conversion events and triggers CPA charging. This page explains the request format, required headers, body fields, and duplicate handling.

## Request

```bash theme={"dark"}
curl -X POST "https://<your-orbit-functions-host>/functions/v1/advertising-api?action=conversion" \
  -H "Content-Type: application/json" \
  -H "x-advertiser-token: <your-advertiser-token>" \
  -H "idempotency-key: <unique-idempotency-key>" \
  -d '{
    "campaign_id": "<campaign-id>",
    "external_id": "<your-conversion-id>",
    "conversion_type": "purchase",
    "click_id": "<optional-click-id>",
    "value_micros": 1000000
  }'
```

<Note>
  Replace `<your-orbit-functions-host>` with your actual Orbit Functions host. All values in the example are illustrative.
</Note>

## Headers

<ParamField header="x-advertiser-token" type="string" required>
  Your advertiser token. Stored as a SHA-256 hash on the server. Never send service-role keys.
</ParamField>

<ParamField header="idempotency-key" type="string" required>
  A unique key for this request. Duplicate keys return an accepted duplicate response without a second charge.
</ParamField>

## Body fields

<ParamField body="campaign_id" type="string" required>
  The campaign to attribute the conversion to.
</ParamField>

<ParamField body="external_id" type="string" required>
  Your unique conversion identifier. Duplicate external IDs return an accepted duplicate response without a second charge.
</ParamField>

<ParamField body="conversion_type" type="string" required>
  The type of conversion, for example `purchase`, `signup`, or `lead`.
</ParamField>

<ParamField body="click_id" type="string">
  Optional. The click to attribute the conversion to.
</ParamField>

<ParamField body="value_micros" type="integer">
  Optional. The monetary value of the conversion in micros. One whole unit equals 1,000,000 micros.
</ParamField>

## Duplicate handling

The API deduplicates conversions using both `external_id` and `idempotency-key`. If either value has been seen before, the API returns an accepted duplicate response and does not charge a second time.

## CPA charging

On an eligible, non-duplicate conversion, the API locks the campaign and balance, verifies budget and funds, updates spend and balance, and inserts an immutable ledger entry in a single database transaction.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.