latestOpenAPI 3.0.02026-08-202629123.8 KB

351c1f004617

Conversions

Report a conversion

Report a conversion — a purchase, signup, or custom event that happened on your site after someone clicked a Linkly link.

Pass the linkly_cid your landing page captured to attribute the conversion to the originating link. A missing or unrecognised linkly_cid is not an error: the conversion is recorded unattributed rather than dropped.

Leads and sales

Set event_type to lead for signups, trials and demo requests, sale when money changes hands, or custom for anything else. The type drives the clicks → leads → sales funnel.

Send external_id — your own customer identifier — on every event. A lead reported with both an linkly_cid and an external_id ties that customer to the link, and later events for the same external_id inherit the attribution automatically. This is what makes server-side sales attributable: the purchase usually arrives from a billing webhook that never saw the linkly_cid. Attribution is first-touch, so a customer who later arrives via a different link keeps the credit on their original one.

Supply event_id to make the call idempotent. Reporting the same event_id twice returns 200 with the original conversion instead of creating a duplicate, so a retrying client is safe.

post/api/v1/conversions

Request body

amount_centsinteger

Value in the smallest currency unit. May be negative to record a refund or chargeback, which nets against earlier revenue.

countrystring

Two-letter country code for the conversion. Inferred for browser-side calls; supply it explicitly from a server-side integration, where the connecting address is your own infrastructure rather than the customer's.

currencystring

ISO 4217 currency code. Defaults to USD.

event_idstring

Your identifier for this event. Used as an idempotency key — reporting the same value twice will not create a second conversion. Applies to any event type, not just purchases.

event_namestring required

What happened, e.g. purchase, signup, trial_started

event_type'lead' | 'sale' | 'custom'

Coarse type driving the funnel. lead establishes customer identity, sale records revenue. Defaults to custom.

external_idstring

Your identifier for the customer. Send it on every event: it is what links a later server-side sale back to the click that produced the signup.

linkly_cidstring

The attribution token captured from the landing page URL. Omit if unavailable — the conversion is then recorded without a link attribution.

metadataobject

Arbitrary JSON, up to 10,000 bytes encoded.

occurred_atstring date-time

When the conversion happened. Defaults to now.

visitor_ipstring

The end customer's IP, when your server has it. Omit unless you do — for server-side calls Linkly otherwise records the connecting address as your server, not the customer, and excludes it from geographic reporting. Sending this asserts you have a lawful basis to share it. Never returned by the API.

Example request

{
  "amount_cents": 4999,
  "country": "US",
  "currency": "USD",
  "event_id": "shopify-1234",
  "event_name": "purchase",
  "event_type": "sale",
  "external_id": "customer-42",
  "linkly_cid": "2on1Y.01KYPGEEPJSPR3S564QRBDGA1W",
  "metadata": {
    "sku": "ABC-123"
  },
  "occurred_at": "2026-07-29T10:30:00Z",
  "visitor_ip": "203.0.113.42"
}

Response

Already recorded — the existing conversion for this event_id

amount_centsinteger nullable

click_idstring nullable

countrystring nullable

currencystring nullable

event_idstring nullable

event_namestring

event_typestring

external_idstring nullable

idstring

ULID. Sorts chronologically, so ids are ordered by creation.

inserted_atstring date-time

ip_source'visitor' | 'server' | 'unknown'

Whose address was recorded. server means the connecting address belonged to your backend or a platform relay, so it is excluded from geographic reporting. The address itself is never returned.

link_idinteger nullable

The attributed link, or null if the conversion could not be attributed.

metadataobject nullable

occurred_atstring date-time

sourcestring

Which integration reported it.

Example response

{
  "amount_cents": 4999,
  "click_id": "01KYPGEEPJSPR3S564QRBDGA1W",
  "country": "US",
  "currency": "USD",
  "event_id": "shopify-1234",
  "event_name": "purchase",
  "event_type": "sale",
  "external_id": "customer-42",
  "id": "01KYPH20SEJY4HQSCPMWW60QE0",
  "ip_source": "visitor",
  "link_id": 41657524,
  "source": "api"
}