Context Token (ctx) Lifecycle

Use this guide to understand how context tokens are minted, transported, and consumed for conversion attribution.

When to use

• You want to attribute conversions back to a specific link click.
• You need to understand why a conversion was rejected with invalid_ctx.
• You are integrating the conversion API (POST /v2/public/conversions) and need to handle the ctx parameter.

What is a context token?

A context token (ctx) is a signed, short-lived token minted at redirect time. It binds a single click event to downstream conversion events so the platform can attribute revenue and conversions to the correct link.

The token encodes:

• Handle and slug that were clicked
• Click timestamp
• Session identifier (if chain signals are active)
• Chain position (for multi-step funnels)
• Consent mode (full, basic, or denied)

Lifecycle

1. Visitor clicks short link
   ↓
2. Redirect handler mints ctx token (HMAC-SHA256 signed)
   ↓
3. ctx appended to destination URL as query parameter
   ↓
4. Destination page extracts ctx from URL
   ↓
5. On conversion event, page POSTs ctx to /v2/public/conversions
   ↓
6. Server verifies signature and TTL
   ↓
7. Conversion attributed to original click

Minting

The ctx token is minted during the HTTP 302/307 redirect response. The redirect handler:

1. Records the click event (handle, slug, country, device, referrer).
2. Signs a payload containing the click metadata using the platform's HMAC-SHA256 signing secret.
3. Appends the signed token to the destination URL as ?ctx={token} (when trackingPolicy.appendContextParam is true).

If the link's tracking policy mode is BRIDGE, the visitor sees an intermediate tracking bridge page before being forwarded. The bridge page carries the ctx token through.

Transport

The ctx token travels from the redirect to the destination in one of two ways:

The destination page is responsible for extracting the ctx value from the URL and storing it until the conversion event fires.

TTL and expiry

The default TTL for a ctx token is 15 minutes from the moment of redirect. After this window:

• The token is rejected with invalid_ctx if submitted to the conversions endpoint.
• The conversion cannot be attributed to the click.

This window is intentionally short to ensure conversions are causally linked to clicks rather than stale sessions.

Submitting a conversion

POST /v2/public/conversions

{
  "ctx": "signed_context_token",
  "eventType": "conversion",
  "idempotencyKey": "unique_key",
  "value": 99.99,
  "currency": "USD"
}

Validation checks

The server performs these checks on submission:

1. Signature verification — HMAC-SHA256 signature must match the platform signing secret.
2. TTL check — Token must not have expired (default 15 minutes).
3. Idempotency — Duplicate submissions with the same idempotencyKey are safely deduplicated (not double-counted).

What happens on success

• A ConversionEvent record is created in the conversion events table.
• The associated click event is incremented (conversionCount).
• Campaign rollups are updated (conversions count, revenue total).
• If webhooks are subscribed, a conversion.created event is emitted.

Chain consent modes

When chain signals are active, the ctx token includes a consent mode that controls data retention:

Session binding

When chain signals are active, the ctx token also carries:

• sessionId — Format: sig_{handle}_{timestamp}_{randomId}
• chainPosition — Integer (1–10,000) indicating the visitor's position in the signal chain

This binding enables multi-step funnel attribution: a visitor who clicks link A, browses, then converts on link B can have the full journey tracked through the signal ledger.

UI path

1. Open https://app.{PUBLIC_DOMAIN}.
2. Navigate to a link and open its settings.
3. Under Tracking Policy, set mode to DIRECT or BRIDGE.
4. Enable "Append context parameter" to include ?ctx= on redirects.
5. View conversion attribution under Analytics > Conversions.

Required auth

• No auth required to submit conversions (/v2/public/conversions is a public endpoint).
• CREATOR-level JWT or above to view conversion analytics.
• The ctx token itself serves as proof of a valid click event.

Common errors

Reconciliation notes

• Clicks will always exceed conversions. Not every click leads to a conversion, and the 15-minute ctx window means late conversions cannot be attributed.
• Duplicate conversions are deduplicated by idempotency key. Replaying the same conversion is safe.
• Bridge mode adds latency but provides more reliable ctx delivery when destination sites strip query parameters.
• Consent mode affects analytics completeness. Denied consent still allows single-click attribution but prevents cross-event signal chaining.

Related:

• Analytics Exports and Reconciliation
• Campaign Funnel Workflow
• Chain Signals and Prefetch
• Glossary