Record conversions once

Endpoint and authentication

Use POST /api/ingest/conversion with JSON and an active advertiser API key carrying the conversion:write scope. The authenticated advertiser must match advertiser_account_id.

Request

curl -X POST https://api.example.invalid/api/ingest/conversion \
  -H "Authorization: Bearer rs_test_example_do_not_use" \
  -H "Content-Type: application/json" \
  --data '{
  "schema_version": "2026-06-30.conversion_attribution.v1",
  "event_id": "evt_example_01JTEST0001",
  "event_type": "conversion_recorded",
  "conversion_id": "order-10001",
  "conversion_pixel_id": "55555555-5555-4555-8555-555555555555",
  "event_occurred_at": "2026-06-30T18:00:00.000Z",
  "route_id": "01JTESTROUTE00000000000000",
  "advertiser_account_id": "11111111-1111-4111-8111-111111111111",
  "campaign_id": "22222222-2222-4222-8222-222222222222",
  "publisher_account_id": "33333333-3333-4333-8333-333333333333",
  "publisher_placement_id": "44444444-4444-4444-8444-444444444444",
  "idempotency_key": "conversion:v1:11111111-1111-4111-8111-111111111111:order-10001",
  "settlement_period_kind": "daily"
}'

#

Required and optional fields

Required: schema_version, event_id, event_type, conversion_id, conversion_pixel_id, event_occurred_at, advertiser_account_id, campaign_id, publisher_account_id, publisher_placement_id, and idempotency_key.
At least one of click_id or route_id is required. request_id is optional.
settlement_period_kind is optional and accepts daily or monthly.
The canonical idempotency key is conversion:v1:11111111-1111-4111-8111-111111111111:<conversion_id>.

JSON body

{
  "schema_version": "2026-06-30.conversion_attribution.v1",
  "event_id": "evt_example_01JTEST0001",
  "event_type": "conversion_recorded",
  "conversion_id": "order-10001",
  "conversion_pixel_id": "55555555-5555-4555-8555-555555555555",
  "event_occurred_at": "2026-06-30T18:00:00.000Z",
  "route_id": "01JTESTROUTE00000000000000",
  "advertiser_account_id": "11111111-1111-4111-8111-111111111111",
  "campaign_id": "22222222-2222-4222-8222-222222222222",
  "publisher_account_id": "33333333-3333-4333-8333-333333333333",
  "publisher_placement_id": "44444444-4444-4444-8444-444444444444",
  "idempotency_key": "conversion:v1:11111111-1111-4111-8111-111111111111:order-10001",
  "settlement_period_kind": "daily"
}

#

Success and errors

A successful request returns the attribution outcome. Repeating the same canonical conversion returns the original durable outcome instead of applying financial effects twice.

200 response

{
  "applied": true,
  "attributionId": "attr_example_01JTEST0001",
  "status": "attributed",
  "reasonCode": null,
  "advertiserLedgerEntryId": "66666666-6666-4666-8666-666666666666",
  "publisherEarningId": "77777777-7777-4777-8777-777777777777",
  "publisherEarningStatus": "pending"
}

#

Structured error example

400 response

{
  "error": {
    "code": "idempotency_key_mismatch",
    "message": "The conversion idempotency key is not canonical."
  }
}