Report Conversions with the Advertising API

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

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
  }'

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

Headers

string

required

Your advertiser token. Stored as a SHA-256 hash on the server. Never send service-role keys.

string

required

A unique key for this request. Duplicate keys return an accepted duplicate response without a second charge.

Body fields

string

required

The campaign to attribute the conversion to.

string

required

Your unique conversion identifier. Duplicate external IDs return an accepted duplicate response without a second charge.

string

required

The type of conversion, for example purchase, signup, or lead.

string

Optional. The click to attribute the conversion to.

integer

Optional. The monetary value of the conversion in micros. One whole unit equals 1,000,000 micros.

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.

​Request

​Headers

​Body fields

​Duplicate handling

​CPA charging

Request

Headers

Body fields

Duplicate handling

CPA charging