Record a conversion event (public)

POST

/api/v1/conversions/track

curl --request POST \
  --url https://example.com/api/v1/conversions/track \
  --header 'Content-Type: application/json' \
  --data '{ "goalKey": "purchase", "clickToken": "550e8400-e29b-41d4-a716-446655440000", "linkCode": "aEOYX3B", "revenueAmount": 49.99, "revenueCurrency": "USD", "metadata": { "orderId": "12345" }, "status": "lead", "payout": 49.99, "payoutCurrency": "USD", "tid": "aff-net-12345", "rawParams": {}, "receivedVia": "api", "convertedAt": "2026-02-14T10:00:00.000Z" }'

Request Body^required

Media typeapplication/json

object

goalKey

required

Goal key

string

Example

purchase

clickToken

Click token from redirect (required if linkCode is absent)

string

Example

550e8400-e29b-41d4-a716-446655440000

linkCode

Short link code — alternative to clickToken for landing-page conversions

string

Example

aEOYX3B

revenueAmount

number

Example

49.99

revenueCurrency

ISO 4217 currency code

string

Example

USD

metadata

object

Example

{
  "orderId": "12345"
}

status

Conversion status — postbacks use this to move lead -> sale, etc. When omitted on a new conversion: “sale” if payout/revenueAmount > 0, otherwise “lead”. Only sale/rebill/upsell count as revenue.

string

Allowed values: lead sale rejected rebill upsell

Example

sale

payout

Payout amount as reported by the affiliate network

number

Example

49.99

payoutCurrency

ISO 4217 currency code for payout

string

Example

USD

tid

External conversion id from the affiliate network. Combined with the goal, this is the dedup key: a second postback with the same tid updates the existing conversion (e.g. lead -> sale) instead of creating a new one.

string

Example

aff-net-12345

rawParams

Raw incoming params, kept for debugging postback ingestion

object

receivedVia

string

Allowed values: api postback pixel

Example

postback

convertedAt

Backdate the conversion (CSV import / API pull of historical data). Also fixes which FX rate is used for revenueBase — omit for “now”.

string

Example

2026-02-14T10:00:00.000Z

Responses

201

Conversion recorded

400

Invalid click token

404

Goal not found