Skip to content
Send Conversion Events

Send Conversion Events

Availability: Conversion tracking is available on Professional and Agency plans.

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 (4900 is 49.00 EUR, ¥1,000 is 100000), or as amount, a decimal string ("49.00"). Send one, not both.
  • Every sale needs a currency: an ISO 4217 code such as EUR.
  • Every lead needs an idempotency_key, and every sale an invoice_id or idempotency_key, so a retry is recorded once.
  • A sale whose click has no lead yet records one too (event_origin inferred), 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/validations

Send "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=50

Filter 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.

Last updated on