Docs menu

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

  1. Turn on conversions for the link when you make or edit it in the members area.
  2. A visitor clicks the short link and lands on your page at an address ending in ?sz_cid=3f9a6c1e5b7d40a28c91e0d4.
  3. Your page, or the sz.js snippet, keeps that click id for the rest of the visit.
  4. 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

NameInTypeDescription
click_id (required)BodystringThe click id, 24 characters, from the sz_cid value on the address the visitor landed on.
name (required)BodystringWhat happened, such as signup or purchase. Up to 60 characters.
valueBodynumberWhat it was worth, such as 49.00. At least 0.
currencyBodystringA three-letter currency code. Used when a value is sent; the default is USD.
referenceBodystringYour 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

Shell
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"}'
JavaScript
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);
Python
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())
PHP
$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

JSON
{
    "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 reference answers 200 with "duplicate": true and 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

NameInTypeDescription
click_id (required)BodystringThe click id.
name (required)BodystringWhat happened.
valueBodynumberWhat it was worth.
currencyBodystringA three-letter currency code.
referenceBodystringYour own id for this event.

Example request

Shell
curl -X POST "https://siz.la/api/conversions/beacon" \
  -H "Content-Type: application/json" \
  -d '{"click_id":"3f9a6c1e5b7d40a28c91e0d4","name":"signup"}'
JavaScript
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);
Python
import requests

response = requests.post(
    "https://siz.la/api/conversions/beacon",
    json={
        "click_id": "3f9a6c1e5b7d40a28c91e0d4",
        "name": "signup",
    },
)
print(response.status_code)
PHP
$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.js snippet 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

NameInTypeDescription
linkQueryintegerOnly this link id. Leave it out for the whole account.
daysQueryintegerHow many days back to report. 1 to 365. Default 30.

Example request

Shell
curl "https://siz.la/api/conversions?link=1042&days=30" \
  -H "Authorization: Bearer $SIZLA_API_KEY"
JavaScript
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);
Python
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())
PHP
$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

JSON
{
    "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: The link is not one of yours.

Notes

  • recent holds the newest 100. value has 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.

HTML
<script async src="https://siz.la/sz.js"></script>

Then, when the thing happens:

JavaScript
sizla.convert("signup", { value: 19, currency: "USD", reference: "user-8841" });
  • The first argument is the name of the conversion. The options are optional.
  • sizla.convert returns true when the report was handed to the browser to send, and false when there is no click id to report against.
  • sizla.clickId() returns the saved click id, or null.
  • 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).