Conversion events
Tell Urlicer when a visitor signs up or buys, and see which links brought them.
Clicks tell you who opened a link. Conversion events tell you what they did next: signed up, started a trial, paid. Your server sends each event to Urlicer, Urlicer works out which short link the visitor came through, and the workspace dashboard and each link's analytics show conversions, the conversion rate and revenue next to the clicks.
Nothing runs in the visitor's browser. Events come from your backend or from a payment provider's webhook, with an API key.
Before you start
- Plan. Conversion tracking is on the Team plan (250,000 events a month) and the Business plan (no monthly limit). The month is the calendar month in UTC.
- Turn it on. The owner or an admin turns it on under
Settings > Tracking, and picks which event names
count as conversions (
signupandpurchaseby default), after ticking a box that confirms what it does. Until it is on, events are refused with403 feature. - A key. Any API key of the workspace can send events. For a server that only reports events, create a key with Events only ticked on the Developers page: it can send and erase events and read the workspace, and cannot touch links.
How an event finds its link
With tracking on, every redirect through one of the workspace's links adds a
ulink parameter to the destination URL, for example
https://example.com/pricing?ulink=go.example.com:spring. A single link can opt
out in its own settings. Each event is then matched in this order:
- The visitor. If you send the visitor's IP address and User-Agent,
Urlicer looks for that visitor's last click on one of your links in the two days before
the event. Inside the link named by
link, when you send one. - The link. If no click is found but you sent
link, the event is credited to that link. - The customer. If neither is there but you sent a
customerRefthat an earlier, matched event of this workspace carried, the event goes to that earlier event's link. This is how a purchase made a week after the signup still counts for the link that brought the signup. - Nothing. The event is stored as unattributed. It counts for no link, and the workspace report says how many such events it left out.
Send everything you have. The link value is the most reliable on its own: keep
ulink from the landing URL in the visitor's session and send it with their
events.
Send an event
/api/v1/events
Report a signup, a purchase or any other named event. Urlicer matches it to the link it came from and adds it to the reports.
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | required | What happened, for example "signup" or "purchase". Up to 64 letters, digits and "_", "-", "." or ":". Which names count as conversions is set in the workspace settings; other names are stored and listed too. |
idempotencyKey |
string | required | Your own unique id for this event, up to 128 characters: an order id, a payment id, a webhook event id. Sending the same key again returns the first event and stores nothing new, so retries are safe. Kept for 7 days. |
value |
number | optional | The amount, in the currency's main unit (49.90, not 4990), from 0 to 1,000,000,000. Needs currency. |
currency |
string | with value | Three-letter ISO 4217 code, for example "EUR". Revenue is reported per currency and never converted. |
occurredAt |
integer | optional | When it happened, in unix seconds UTC. Defaults to now. Accepted from 30 days back to 5 minutes ahead. |
customerRef |
string | optional | Your own id for the customer, up to 128 characters. A later event with the same customerRef, such as a purchase days after the signup, is credited to the link the customer's earlier event came from. Do not send an email address or a name. |
link |
string | optional | The value of the ulink parameter the visitor arrived with, for example "go.example.com:spring". Credits the event to that link. |
visitorIp |
string | with visitorUserAgent | The visitor's IP address as your server saw it. Hashed on arrival and never stored; used to find the visitor's click. |
visitorUserAgent |
string | with visitorIp | The visitor's User-Agent header, up to 1,024 characters. Hashed together with the IP address. |
curl -X POST "https://urlicer.com/api/v1/events" \
-H "Authorization: Bearer url_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "purchase", "idempotencyKey": "order-1042", "value": 49.9, "currency": "EUR", "customerRef": "user-381", "link": "go.example.com:spring"}'
{
"id": "evt_3f9c2a71d04be5a8c6e1",
"duplicate": false
}
| Field | Type | Description |
|---|---|---|
id |
string | The event's id. |
duplicate |
boolean | true when this idempotencyKey was sent before: the answer is the first event's id, with status 200, and nothing new is stored. A new event answers 202. |
- The event is queued and matched within about ten seconds. If it names a visitor whose click has not been processed yet, matching is tried once more two minutes later.
- An event that matches no link is still stored, as unattributed, and the reports say how many there are. It is not an error.
- 403 feature: conversion tracking is off for the workspace; upgrade is true when the plan does not include it, false when it only needs turning on. 403 scope: the key cannot send events. 403 quota: the workspace has sent its plan's events for this month (UTC); a duplicate is still answered, so retries never hit it. 400 validation lists every problem with the body.
Example: a signup
Keep ulink when the visitor lands, and send the event when the account is
created. The visitor's IP address and User-Agent come from the same request.
// On the landing page: keep the link the visitor came through.
if (isset($_GET['ulink'])) {
$_SESSION['ulink'] = $_GET['ulink'];
}
// When the account is created:
$ch = curl_init('https://urlicer.com/api/v1/events');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer url_live_YOUR_EVENTS_KEY',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'name' => 'signup',
'idempotencyKey' => 'signup-' . $user->id,
'customerRef' => 'user-' . $user->id,
'link' => $_SESSION['ulink'] ?? null,
'visitorIp' => $_SERVER['REMOTE_ADDR'],
'visitorUserAgent' => $_SERVER['HTTP_USER_AGENT'] ?? '',
]),
]);
curl_exec($ch);
Example: a Stripe payment
Send purchases from your Stripe webhook, not from the success page, so a closed tab never
loses a sale. Stripe gives amount_total in the smallest currency unit, so
divide it by 100 for EUR or USD. Stripe's lower-case currency codes are accepted. The
webhook event id makes a good idempotencyKey: Stripe may deliver the same
event more than once.
Example: a Paddle payment
The same pattern with Paddle's transaction.completed webhook. Paddle's totals
are also in the smallest unit.
Erase a customer's events
/api/v1/events
Delete every event sent with one customerRef, for example when that customer asks you to erase their data.
| Field | Type | Required | Description |
|---|---|---|---|
customerRef |
string | required | The customerRef the events were sent with. |
curl -X DELETE "https://urlicer.com/api/v1/events?customerRef=user-381" \
-H "Authorization: Bearer url_live_YOUR_KEY"
{
"deleted": "queued"
}
- Answers 202. The deletion is applied by the database shortly after; it removes the data, not just hides it.
- Works whether or not conversion tracking is still on. Events still in the queue at that moment are not reached; calling it again catches them.
- The workspace's audit log records that an erasure happened, without the customerRef.
What the reports count
- Conversions are events credited to a link whose name is one of the workspace's conversion names. Other names are stored and listed by name, but are not conversions.
- A visitor matched by their click counts once, however many conversion events they
send. Events credited through
linkorcustomerRefcount one each. - Conversion rate is visitors who converted divided by unique visitors in the same period, so it never goes above 100%.
- Revenue is the sum of
valueon credited events, shown per currency and never converted between currencies. - An event is counted on the day it happened (
occurredAt), not the day it was sent. - Clicks by bots are never matched, so a bot cannot take credit for a sale.
Privacy
Urlicer sets no cookie for this. The visitor's IP address and User-Agent are turned into a
hash, the same one click analytics uses, before the event is queued, and are not stored.
customerRef is your own identifier: use an internal id, never an email
address or a name.
Whether you need your visitors' consent depends on where they are and on how you use the
data: the ulink parameter and the IP address and User-Agent are information
read from a visitor's device. Check with your own adviser before you turn this on for
visitors in the EU or the UK. To erase one customer's events, use
the erase endpoint.