Skip to content
Conversions

Conversions

Availability: Conversion tracking is available on Professional and Agency plans. API keys need 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/refunds

Every request needs:

Authorization: Bearer sk_live_...
Content-Type: application/json

Bodies 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: 4900 is 49.00 EUR, ¥1,000 is 100000, and 12.35 KWD is 1235.
  • 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

FieldApplies toRequiredDescription
click_idlead, saleyesThe click id from the visitor’s click (snt_click_id).
event_nameallnoEvent name, up to 120 characters, such as Sign up or Invoice paid.
lead_categoryleadnosignup, form_submission, newsletter_signup, trial_started, add_to_cart, checkout_started or custom.
event_quantityleadnoHow many leads the event counts, 1 by default, at most 10000.
amount_centssale, refundrefund: this or amountAmount in hundredths of the main unit, at most 1000000000000. A sale without an amount records 0.
amountsale, refundrefund: this or amount_centsThe amount as a decimal string, such as "49.00". Don’t send it with amount_cents.
currencysale, refundsale: yes; refund: with amountISO 4217 code of a currency people are paid in, such as EUR. A refund takes its sale’s.
settlement_amount_centssalenoWhat the sale settled for in settlement_currency, in hundredths. Requires settlement_currency.
settlement_currencysalenoISO 4217 code, different from currency. Requires settlement_amount_cents.
invoice_idsale, refundsale: this or idempotency_key; refund: yesYour invoice or order ID. Identifies a sale; a refund names its sale with it.
refund_idrefundyesYour refund ID. A retry with the same one is recorded once.
reasonrefundnoRefund reason, up to 500 characters.
payment_processorsale, refundnoProcessor name, such as stripe.
idempotency_keyalllead: yes; sale: without invoice_idStable key from your system, so a retry is recorded once.
metadataallnoJSON object, up to 32 KiB.
occurred_atallnoRFC 3339 time of the event; now when omitted.
test_modeallnoRecords a test event, kept out of live reports.
event_typeallnolead, 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
ParameterEndpointsDescription
from, toattribution, timeline, eventsRFC 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.
environmentattribution, timeline, eventslive (default) or test.
limitattribution, eventsAttribution: 1–100, default 50. Events: 1–100, default 50.
offseteventsEvents to skip.
intervaltimelineday (default), week or month.
event_typeeventslead, sale or refund.
lead_categoryeventsA lead category, or purchase_inferred.
event_origineventsobserved or inferred.
linkeventsA link’s public ID, short code, short URL or numeric ID.
eventeventsAn event’s public ID.
qeventsSearches 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:

  1. In the reporting currency: as it is. Exact.
  2. With a settlement amount in the reporting currency (sent with the sale, or reported by a connector): that amount. Exact.
  3. 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. approximate is true.
  4. 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" }
}
CodeHTTPMeaning
invalid_request_format400The body is not one JSON object of known fields.
event_type_mismatch400event_type names a different type from the one the endpoint records.
conversion_request_too_large413The body is over 64 KiB.
<field>_too_long400A text field is over its limit (details.field).
conversion_identity_required400A lead without idempotency_key, or a sale without invoice_id or idempotency_key.
currency_required400A sale without currency, or a refund with amount but no currency.
invalid_currency400currency is not an ISO 4217 currency people are paid in. Precious metals (XAU), testing (XTS) and other non-money codes are refused.
conflicting_amounts400Both amount and amount_cents were sent.
invalid_amount400amount is not a decimal number, or has more than two decimals.
invalid_settlement400A settlement field is missing its pair, out of range, or in the sale’s own currency.
invalid_lead_category, invalid_event_quantity400Unsupported lead_category, or a negative event_quantity.
conversion_amount_too_large, conversion_quantity_too_large400The amount is over 1000000000000 hundredths, or event_quantity over 10000.
invalid_occurred_at400occurred_at is not RFC 3339, or too far in the future.
invoice_id_required, refund_id_required, invalid_amount_cents400A refund without its sale’s invoice_id, a refund_id, or a positive amount.
conversion_click_not_found404The click id is unknown, or not visible to this key.
conversion_link_not_enabled409The clicked link does not have conversion tracking on.
conversion_attribution_outside_window409occurred_at is outside the click’s attribution window.
conversion_idempotency_conflict409The key, invoice or refund ID was used for a different event.
conversion_sale_not_found404A refund’s invoice_id matches no live sale this key can see.
conversion_sale_ambiguous409The invoice_id matches sales in several workspaces; use a workspace-scoped key.
conversion_refund_exceeds_sale409The refund is more than what is left to refund.
conversion_refund_currency_mismatch, conversion_refund_processor_mismatch409The refund’s currency or processor differs from its sale’s.
conversion_refund_predates_sale409The refund’s occurred_at is before its sale.
conversion_access_denied403The key can’t record conversions for this click or workspace.
conversion_plan_unavailable403The plan does not include conversion tracking.
conversion_privacy_erased410The conversion was removed by a privacy request; don’t retry.
conversion_recording_unavailable503Recording is briefly unavailable; retry the same request, it is recorded once.
invalid_conversion_request400The request failed another check; error says which.
invalid_date_range, invalid_event_type, invalid_event_origin, invalid_environment, invalid_lead_category400A read parameter is invalid.
link_not_found400The events link filter matches no link this key can see.
invalid_search400q is over 200 characters.
conversion_summary_unavailable, conversion_attribution_unavailable, conversion_timeline_unavailable, conversion_events_unavailable503Reporting is briefly unavailable; retry later. Other failures of these reads answer 500.
Last updated on