Conversions
conversions:write to send events and conversions:read to read reports.Call the conversion API from trusted server-side code, never from the browser. The capture script stores the click id on your site and posts events to your backend, which forwards them here.
A workspace-scoped API key sends to and reads from its workspace. An account-wide key reads every workspace you can access.
Write Endpoints
POST /api/v1/conversions/leads
POST /api/v1/conversions/sales
POST /api/v1/conversions/refundsEvery request needs:
Authorization: Bearer sk_live_...
Content-Type: application/jsonBodies are JSON with the snake_case fields below; unknown fields are refused
(invalid_request_format). A successful call answers 200 with the recorded event.
Track a Lead
{
"click_id": "clk_...",
"event_name": "Sign up",
"lead_category": "signup",
"idempotency_key": "signup_8412"
}Response:
{
"type": "lead",
"event": {
"public_id": "8c1e…",
"event_type": "lead",
"event_name": "Sign up",
"lead_category": "signup",
"event_origin": "observed",
"duplicate": false,
"is_test": false,
"click_id": "clk_...",
"attribution": { "type": "workspace" },
"occurred_at": "2026-10-24T10:00:00Z",
"created_at": "2026-10-24T10:00:01Z"
}
}A retry with the same idempotency_key answers the existing event with "duplicate": true.
Track a Sale
{
"click_id": "clk_...",
"amount_cents": 4900,
"currency": "EUR",
"invoice_id": "inv_123",
"event_name": "Invoice paid"
}The response has the same shape, with "type": "sale" and the sale’s amount_cents,
amount, currency_decimals, currency and invoice_id. When the click has no lead yet,
the sale also records one (event_origin inferred, lead_category
purchase_inferred), so the funnel stays complete.
Send the amount one of two ways, not both:
amount_cents: hundredths of the currency’s main unit, whatever the currency:4900is 49.00 EUR, ¥1,000 is100000, and 12.35 KWD is1235.amount: the same as a decimal string with up to two decimals, such as"49.00","1000"or"12.35".
Responses carry both: amount_cents, and amount as a decimal string with
currency_decimals (2). A sale without either is recorded with an amount of 0. Stripe
and Dodo send amounts in each currency’s own minor unit (¥1,000 as 1000); Shortn converts
their connectors’ amounts for you.
Settlement Amount
When a sale is paid in one currency and settles in another (the customer pays in euros, your account is credited in dollars), send what it settled for:
{
"click_id": "clk_...",
"amount_cents": 1000,
"currency": "EUR",
"settlement_amount_cents": 1085,
"settlement_currency": "USD",
"invoice_id": "inv_123"
}settlement_amount_cents is in hundredths, on the same basis as amount_cents (if one
excludes tax, so does the other). Send both fields or neither; settlement_currency must
differ from currency. Reporting totals use the settlement amount instead of a daily
exchange rate (see Reporting Currency). A refund needs none: it counts
as its share of its sale’s settlement.
Track a Refund
{
"invoice_id": "inv_123",
"refund_id": "re_456",
"amount_cents": 1900,
"reason": "Damaged item"
}A refund names its sale by invoice_id and can’t exceed what is left to refund. Send its
amount as amount_cents or amount, like a sale. Omit currency and payment_processor
to take the sale’s, or send the same values; a refund sent with amount needs its
currency. The response has "type": "refund"; the event shows the sale’s
refunded_amount_cents, remaining_amount_cents and refund_status.
Request Fields
| Field | Applies to | Required | Description |
|---|---|---|---|
click_id | lead, sale | yes | The click id from the visitor’s click (snt_click_id). |
event_name | all | no | Event name, up to 120 characters, such as Sign up or Invoice paid. |
lead_category | lead | no | signup, form_submission, newsletter_signup, trial_started, add_to_cart, checkout_started or custom. |
event_quantity | lead | no | How many leads the event counts, 1 by default, at most 10000. |
amount_cents | sale, refund | refund: this or amount | Amount in hundredths of the main unit, at most 1000000000000. A sale without an amount records 0. |
amount | sale, refund | refund: this or amount_cents | The amount as a decimal string, such as "49.00". Don’t send it with amount_cents. |
currency | sale, refund | sale: yes; refund: with amount | ISO 4217 code of a currency people are paid in, such as EUR. A refund takes its sale’s. |
settlement_amount_cents | sale | no | What the sale settled for in settlement_currency, in hundredths. Requires settlement_currency. |
settlement_currency | sale | no | ISO 4217 code, different from currency. Requires settlement_amount_cents. |
invoice_id | sale, refund | sale: this or idempotency_key; refund: yes | Your invoice or order ID. Identifies a sale; a refund names its sale with it. |
refund_id | refund | yes | Your refund ID. A retry with the same one is recorded once. |
reason | refund | no | Refund reason, up to 500 characters. |
payment_processor | sale, refund | no | Processor name, such as stripe. |
idempotency_key | all | lead: yes; sale: without invoice_id | Stable key from your system, so a retry is recorded once. |
metadata | all | no | JSON object, up to 32 KiB. |
occurred_at | all | no | RFC 3339 time of the event; now when omitted. |
test_mode | all | no | Records a test event, kept out of live reports. |
event_type | all | no | lead, sale or refund, as the capture script sends it. Ignored when it matches the endpoint; another type is refused with event_type_mismatch. |
Limits: a request body is at most 64 KiB. The click must be within its attribution window (90 days by default) on a link with conversion tracking on.
Validate Without Recording
The validation endpoints accept the same bodies and run the same checks, but record nothing:
POST /api/v1/conversions/leads/validations
POST /api/v1/conversions/sales/validations
POST /api/v1/conversions/refunds/validations{
"valid": true,
"dry_run": true,
"result": {
"valid": true,
"dry_run": true,
"event_type": "sale",
"would_track": true,
"would_create_event": true,
"would_infer_lead": true,
"duplicate": false,
"is_test": false
}
}To try the whole flow, send real requests with "test_mode": true and read them back with
environment=test.
Read Endpoints
GET /api/v1/conversions/summary
GET /api/v1/conversions/attribution
GET /api/v1/conversions/timeline
GET /api/v1/conversions/events| Parameter | Endpoints | Description |
|---|---|---|
from, to | attribution, timeline, events | RFC 3339 time or YYYY-MM-DD date; a date to includes that day. Without dates, the last 14 days. A from before your plan’s history moves up to its first day. |
environment | attribution, timeline, events | live (default) or test. |
limit | attribution, events | Attribution: 1–100, default 50. Events: 1–100, default 50. |
offset | events | Events to skip. |
interval | timeline | day (default), week or month. |
event_type | events | lead, sale or refund. |
lead_category | events | A lead category, or purchase_inferred. |
event_origin | events | observed or inferred. |
link | events | A link’s public ID, short code, short URL or numeric ID. |
event | events | An event’s public ID. |
q | events | Searches event names and attribution labels, up to 200 characters. |
Summary answers all-time live totals in data:
{
"data": {
"leads": 120,
"sales": 31,
"refunds": 2,
"sale_amount_cents": 151900,
"refund_amount_cents": 4900,
"net_revenue_cents": 147000,
"currency": "EUR",
"mixed_currencies": false,
"monetary_totals_available": true,
"lead_to_sale_rate": 0.2583,
"reporting": { "currency": "EUR", "net_revenue_cents": 147000, "approximate": false }
}
}When sales span several currencies, mixed_currencies is true and the per-currency
amounts and currency are null; the reporting object still gives the total (see below).
Attribution answers one row per attribution target (the workspace, a member, a team, a
partner, a campaign) in data, with totals, pagination and date_range. Timeline
answers one point per interval in data, with interval and date_range. Rows and points
carry clicks, leads, sales, refunds, the money fields and reporting.
Events answers events, newest first, in data, with pagination (count, limit,
offset, has_more, next_offset), date_range and environment.
Reporting Currency
Sales keep their own currency. Totals that span several currencies are also reported in one reporting currency, so they add up: the workspace’s (Settings → General, set by owners and administrators), or, for reads across workspaces, the reader’s own (Profile → Regional). Both start as EUR.
The summary, attribution rows and totals, timeline points and A/B results carry a
reporting object beside the per-currency fields, which keep their meaning:
"reporting": {
"currency": "EUR",
"sale_amount_cents": 1234000,
"refund_amount_cents": 50000,
"net_revenue_cents": 1184000,
"approximate": true,
"rate_sources": ["ecb"],
"excluded": [{"currency": "XYZ", "sales": 3, "refunds": 0}]
}Each sale and refund in GET /api/v1/conversions/events carries its own amount the same
way: {"currency": "EUR", "amount_cents": 4512, "approximate": true, "rate_sources": ["ecb"]},
with amount_cents null when no rate was available. The events CSV export in the
dashboard ends with reporting_currency, reporting_amount and reporting_conversion
(exact, approximate or no_rate).
How each sale is counted, most precise first:
- In the reporting currency: as it is. Exact.
- With a settlement amount in the reporting currency (sent with the sale, or reported by a connector): that amount. Exact.
- Otherwise: the amount (or its settlement amount, in another currency) at the
exchange rate of the sale’s date, the latest published on or before it.
approximateistrue. - No rate from the seven days before the sale: left out of the total and listed in
excluded.
A refund uses its sale’s date, so a fully refunded sale nets to zero. Amounts are added up per currency and day, converted once and rounded half to even, to the hundredth.
Rates. Shortn uses the euro foreign exchange reference rates of the European Central
Bank, available free from the ECB
and published on working days around 16:00 CET. Rates between two other currencies are
derived from them (USD→GBP through the euro). For currencies the ECB does not publish,
Shortn falls back to the fawazahmed0 exchange API
(rate_sources names fawazahmed0). Reference rates are mid-market rates.
Why a converted figure can differ from your payout. A payment provider converts with its own rate and fee when it credits your balance. For a sale in another currency than your payout, the converted figure is the sale’s value on its date, not the amount that reached your account:
- Stripe records sales in the currency of your prices, Adaptive Pricing included (the customer’s currency does not affect it). If you price in another currency than your reporting currency, Stripe sales are converted at the reference rate.
- Dodo Payments and Shopify report what a sale settled for in your currency; those sales are exact when your reporting currency is that currency.
For exact totals, choose the reporting currency you price in or are paid in.
Privacy
Conversion events hold no customer profile: the API has no fields for a customer’s name,
email or ID. Keep personal data out of event_name and metadata too.
Errors
Errors use the structured API error shape:
{
"code": "conversion_click_not_found",
"error": "click_id was not found for this API key",
"hint": "Use a click_id from a conversion-enabled Shortn click that is visible to this API key.",
"details": { "field": "click_id" }
}| Code | HTTP | Meaning |
|---|---|---|
invalid_request_format | 400 | The body is not one JSON object of known fields. |
event_type_mismatch | 400 | event_type names a different type from the one the endpoint records. |
conversion_request_too_large | 413 | The body is over 64 KiB. |
<field>_too_long | 400 | A text field is over its limit (details.field). |
conversion_identity_required | 400 | A lead without idempotency_key, or a sale without invoice_id or idempotency_key. |
currency_required | 400 | A sale without currency, or a refund with amount but no currency. |
invalid_currency | 400 | currency is not an ISO 4217 currency people are paid in. Precious metals (XAU), testing (XTS) and other non-money codes are refused. |
conflicting_amounts | 400 | Both amount and amount_cents were sent. |
invalid_amount | 400 | amount is not a decimal number, or has more than two decimals. |
invalid_settlement | 400 | A settlement field is missing its pair, out of range, or in the sale’s own currency. |
invalid_lead_category, invalid_event_quantity | 400 | Unsupported lead_category, or a negative event_quantity. |
conversion_amount_too_large, conversion_quantity_too_large | 400 | The amount is over 1000000000000 hundredths, or event_quantity over 10000. |
invalid_occurred_at | 400 | occurred_at is not RFC 3339, or too far in the future. |
invoice_id_required, refund_id_required, invalid_amount_cents | 400 | A refund without its sale’s invoice_id, a refund_id, or a positive amount. |
conversion_click_not_found | 404 | The click id is unknown, or not visible to this key. |
conversion_link_not_enabled | 409 | The clicked link does not have conversion tracking on. |
conversion_attribution_outside_window | 409 | occurred_at is outside the click’s attribution window. |
conversion_idempotency_conflict | 409 | The key, invoice or refund ID was used for a different event. |
conversion_sale_not_found | 404 | A refund’s invoice_id matches no live sale this key can see. |
conversion_sale_ambiguous | 409 | The invoice_id matches sales in several workspaces; use a workspace-scoped key. |
conversion_refund_exceeds_sale | 409 | The refund is more than what is left to refund. |
conversion_refund_currency_mismatch, conversion_refund_processor_mismatch | 409 | The refund’s currency or processor differs from its sale’s. |
conversion_refund_predates_sale | 409 | The refund’s occurred_at is before its sale. |
conversion_access_denied | 403 | The key can’t record conversions for this click or workspace. |
conversion_plan_unavailable | 403 | The plan does not include conversion tracking. |
conversion_privacy_erased | 410 | The conversion was removed by a privacy request; don’t retry. |
conversion_recording_unavailable | 503 | Recording is briefly unavailable; retry the same request, it is recorded once. |
invalid_conversion_request | 400 | The request failed another check; error says which. |
invalid_date_range, invalid_event_type, invalid_event_origin, invalid_environment, invalid_lead_category | 400 | A read parameter is invalid. |
link_not_found | 400 | The events link filter matches no link this key can see. |
invalid_search | 400 | q is over 200 characters. |
conversion_summary_unavailable, conversion_attribution_unavailable, conversion_timeline_unavailable, conversion_events_unavailable | 503 | Reporting is briefly unavailable; retry later. Other failures of these reads answer 500. |