LIlinklyhq
Conversions

Report a conversion

Changed on

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 conversion that cannot be attributed — no linkly_cid, an unrecognised one, and no earlier attributed event for the same external_id — is discarded: the call returns 202 with attributed: false and nothing is stored. It is not an error, so do not retry it; check that your landing page is capturing and forwarding linkly_cid.

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

Query parameters

workspace_idstring

The ID of the workspace. Required when authenticating with an API key. Omit it with an OAuth token, which is bound to one workspace.

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 required

The click the conversion is attributed to.

countrystring nullable
currencystring nullable
event_idstring nullable
event_namestring required
event_typestring required
external_idstring nullable
idstring required

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

inserted_atstring required

When Linkly stored it. UTC, ISO 8601 without an offset (YYYY-MM-DDTHH:MM:SS), unlike occurred_at.

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 required

The link the conversion is attributed to.

metadataobject nullable
occurred_atstring date-time required

When the conversion happened, UTC with offset.

sourcestring required

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",
  "inserted_at": "2026-07-29T10:30:01",
  "ip_source": "visitor",
  "link_id": 41657524,
  "occurred_at": "2026-07-29T10:30:00.123456Z",
  "source": "api"
}

Changes

  • 9c5b6c116b85Revision changes
    • breaking

      the response's property format changed from date-time to no format for status

    • breaking

      the response's property format changed from date-time to no format for status

    • info

      added the new optional query request parameter workspace_id

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      added the success response with the status