Conversions
Count sign-ups and sales against the click that brought the visitor, from your server or with the sz.js browser snippet.
A conversion is something that happens after a click: a sign-up, a sale, a download. When you turn conversions on for a link, siz.la adds a click id to the address visitors are sent to, as a sz_cid query value. When the visitor does something worth counting, you send the click id back and the sale is counted against the click, with its value. Conversion tracking is part of the paid plans.
How it fits together
- Turn on conversions for the link when you make or edit it in the members area.
- A visitor clicks the short link and lands on your page at an address ending in
?sz_cid=3f9a6c1e5b7d40a28c91e0d4. - Your page, or the
sz.jssnippet, keeps that click id for the rest of the visit. - When they sign up or buy, you send the click id with a name, and optionally a value, either from your server or from the browser.
A click can be counted for 90 days after it happened. A reference, such as an order number, stops the same sale being counted twice.
From your server
This is the call to use for anything you pay out on. It needs your API key.
Record a conversion
POST/api/conversions
Tell siz.la that a click led to a sign-up or a sale. Call it from your server with your API key.
Needs: API key. Needs Pro and the plans above it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
click_id (required) | Body | string | The click id, 24 characters, from the sz_cid value on the address the visitor landed on. |
name (required) | Body | string | What happened, such as signup or purchase. Up to 60 characters. |
value | Body | number | What it was worth, such as 49.00. At least 0. |
currency | Body | string | A three-letter currency code. Used when a value is sent; the default is USD. |
reference | Body | string | Your own id for this event, such as an order number. Sending the same reference again for the same link does not count it twice. Up to 100 characters. |
Example request
curl -X POST "https://siz.la/api/conversions" \
-H "Authorization: Bearer $SIZLA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"click_id":"3f9a6c1e5b7d40a28c91e0d4","name":"purchase","value":49,"currency":"USD","reference":"order-1042"}'const response = await fetch("https://siz.la/api/conversions", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"click_id": "3f9a6c1e5b7d40a28c91e0d4",
"name": "purchase",
"value": 49,
"currency": "USD",
"reference": "order-1042"
}),
});
const data = await response.json();
console.log(data);import os
import requests
response = requests.post(
"https://siz.la/api/conversions",
headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
json={
"click_id": "3f9a6c1e5b7d40a28c91e0d4",
"name": "purchase",
"value": 49.0,
"currency": "USD",
"reference": "order-1042",
},
)
print(response.json())$ch = curl_init('https://siz.la/api/conversions');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer '.getenv('SIZLA_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'click_id' => '3f9a6c1e5b7d40a28c91e0d4',
'name' => 'purchase',
'value' => 49.0,
'currency' => 'USD',
'reference' => 'order-1042',
]),
]);
$data = json_decode(curl_exec($ch), true);Example answer, status 201
{
"error": 0,
"id": 318,
"duplicate": false
}Errors specific to this call
403: The plan does not include conversion tracking.404: No click of yours matches that id.422: A field is not valid, or the click is older than the counting window.
Notes
- A repeated
referenceanswers 200 with"duplicate": trueand the id of the first one.
Record a conversion from the browser
POST/api/conversions/beacon
The call the browser snippet makes. There is no API key: the click id is the proof. It always answers 204 with no body, even when it refuses the report.
Needs: No key. Needs Pro and the plans above it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
click_id (required) | Body | string | The click id. |
name (required) | Body | string | What happened. |
value | Body | number | What it was worth. |
currency | Body | string | A three-letter currency code. |
reference | Body | string | Your own id for this event. |
Example request
curl -X POST "https://siz.la/api/conversions/beacon" \
-H "Content-Type: application/json" \
-d '{"click_id":"3f9a6c1e5b7d40a28c91e0d4","name":"signup"}'const response = await fetch("https://siz.la/api/conversions/beacon", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"click_id": "3f9a6c1e5b7d40a28c91e0d4",
"name": "signup"
}),
});
const data = response.status;
console.log(data);import requests
response = requests.post(
"https://siz.la/api/conversions/beacon",
json={
"click_id": "3f9a6c1e5b7d40a28c91e0d4",
"name": "signup",
},
)
print(response.status_code)$ch = curl_init('https://siz.la/api/conversions/beacon');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'click_id' => '3f9a6c1e5b7d40a28c91e0d4',
'name' => 'signup',
]),
]);
curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);Example answer, status 204
No body.
Notes
- Most people use the
sz.jssnippet instead of calling this directly. See the conversions page. - Anyone who has a click id can report a conversion for it. Use the server call for anything you pay out on.
List conversions
GET/api/conversions
Totals, the conversion rate and the newest conversions for one link or the whole account.
Needs: API key. Needs Pro and the plans above it.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
link | Query | integer | Only this link id. Leave it out for the whole account. |
days | Query | integer | How many days back to report. 1 to 365. Default 30. |
Example request
curl "https://siz.la/api/conversions?link=1042&days=30" \
-H "Authorization: Bearer $SIZLA_API_KEY"const response = await fetch("https://siz.la/api/conversions?link=1042&days=30", {
headers: {
Authorization: `Bearer ${process.env.SIZLA_API_KEY}`,
},
});
const data = await response.json();
console.log(data);import os
import requests
response = requests.get(
"https://siz.la/api/conversions",
headers={"Authorization": f"Bearer {os.environ['SIZLA_API_KEY']}"},
params={
"link": 1042,
"days": 30,
},
)
print(response.json())$ch = curl_init('https://siz.la/api/conversions?link=1042&days=30');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer '.getenv('SIZLA_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);Example answer, status 200
{
"error": 0,
"days": 30,
"conversions": 4,
"clicks": 37,
"conversion_rate": 10.800000000000000710542735760100185871124267578125,
"value": {
"USD": 196
},
"by_name": {
"purchase": 3,
"signup": 1
},
"recent": [
{
"id": 318,
"link_id": 1042,
"click_id": "3f9a6c1e5b7d40a28c91e0d4",
"name": "purchase",
"value": 49,
"currency": "USD",
"reference": "order-1042",
"source": "server",
"converted_at": "2026-11-14T10:02:44+00:00"
}
]
}Errors specific to this call
403: The plan does not include conversion tracking.404: Thelinkis not one of yours.
Notes
recentholds the newest 100.valuehas one total for each currency.
From the browser with sz.js
Add the snippet to the page people land on. It reads sz_cid from the address, keeps it in the browser for 90 days, and sends a conversion when you call sizla.convert.
<script async src="https://siz.la/sz.js"></script>
Then, when the thing happens:
sizla.convert("signup", { value: 19, currency: "USD", reference: "user-8841" });
- The first argument is the name of the conversion. The options are optional.
sizla.convertreturnstruewhen the report was handed to the browser to send, andfalsewhen there is no click id to report against.sizla.clickId()returns the saved click id, ornull.- The snippet sends one small request to the beacon call above. It never shows an error to your visitors.
- Anyone who has a click id can report a conversion for it, and the beacon call is limited to 60 requests a minute for each address. Use the server call for anything you pay out on.
Reading the results
The members area shows conversions next to clicks on each link's statistics page. The list call returns the same totals as JSON, and every new conversion can be sent to you as a conversion.created message. See (https://siz.la/docs/webhooks).