Send Conversion Events
Send conversion events from your backend, so your Shortn API key stays private. Every lead and sale carries the click id the capture script stored.
Browser to your backend
The capture script posts events to your own endpoint (data-track-endpoint), adding the
stored click_id, UTM values (in metadata), and event_type (lead or sale):
await window.shortn.conversion.trackLead({
event_name: "Sign up",
lead_category: "signup",
idempotency_key: "signup_8412"
});
await window.shortn.conversion.trackSale({
amount_cents: 4900,
currency: "EUR",
invoice_id: "inv_123"
});Fields use the API’s snake_case names. convert(label, value, currency, properties) is a
shortcut: with a value it sends a sale (value in main units, 49 for 49.00), without one a
lead. Each call resolves to { success, ... }; it does not throw when the visitor has not
consented or no click id is stored.
Prefer your own IDs for idempotency_key and invoice_id: the script makes up a key when
you send none, but a new one on every page load, so a retried page records again.
Your backend to Shortn
Forward the body to Shortn with a conversions:write API key, choosing the endpoint by
event_type. You can leave event_type in the body: Shortn ignores it when it matches the
endpoint, and refuses one that names another type with event_type_mismatch.
// Express-style handler for data-track-endpoint="/api/shortn-conversion"
app.post("/api/shortn-conversion", async (req, res) => {
const { event_type, ...event } = req.body;
const kind = event_type === "sale" ? "sales" : "leads";
const response = await fetch(`https://app.shortn.link/api/v1/conversions/${kind}`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SHORTN_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify(event)
});
res.status(response.status).json(await response.json());
});Check the body before you forward it (for example, take the amount from your own order, not from the browser). Your backend can also send events on its own, without the browser.
Track a lead:
POST /api/v1/conversions/leads
Authorization: Bearer sk_live_...
Content-Type: application/json{
"click_id": "clk_...",
"event_name": "Sign up",
"lead_category": "signup",
"idempotency_key": "signup_8412"
}Track a sale:
POST /api/v1/conversions/sales{
"click_id": "clk_...",
"amount_cents": 4900,
"currency": "EUR",
"invoice_id": "inv_123"
}Track a refund of that sale:
POST /api/v1/conversions/refunds{
"invoice_id": "inv_123",
"refund_id": "re_456",
"amount_cents": 1900
}- Send the amount as
amount_cents, in hundredths of the currency’s main unit (4900is 49.00 EUR, ¥1,000 is100000), or asamount, a decimal string ("49.00"). Send one, not both. - Every sale needs a
currency: an ISO 4217 code such asEUR. - Every lead needs an
idempotency_key, and every sale aninvoice_idoridempotency_key, so a retry is recorded once. - A sale whose click has no lead yet records one too (
event_origininferred), so the funnel stays complete. - A refund names its sale by
invoice_id; it can’t exceed what is left to refund. - The click must be within its attribution window, on a link with conversion tracking on.
- A sale paid in one currency and settled in another can carry its settlement amount.
Test before going live
The dry-run endpoints accept the same bodies and checks but record nothing:
POST /api/v1/conversions/leads/validations
POST /api/v1/conversions/sales/validations
POST /api/v1/conversions/refunds/validationsSend "test_mode": true on a real request to record a test event. Test events stay out of
your live numbers; read them with environment=test. You can also try a request from
Conversions → Setup → Test an event.
Read conversion data
With a conversions:read key:
GET /api/v1/conversions/summary
GET /api/v1/conversions/attribution?from=2026-06-01&to=2026-06-30
GET /api/v1/conversions/timeline?interval=week
GET /api/v1/conversions/events?event_type=sale&limit=50Filter events by link with link: its short code, short URL, numeric ID or public ID. See
the conversion API reference for every field and response.