Source-to-Revenue Tagging Spec
One small contract: attach the Metrivo visitor and session IDs to every checkout you create. When the payment webhook arrives, Metrivo resolves it to the exact session, page, and source that produced it — the highest-confidence attribution there is.
The contract
Send window.Metrivo.getAttributionMetadata() to your server and pass it into provider metadata (Stripe / Dodo), notes (Razorpay), or custom data (Paddle / Lemon Squeezy). Hosted checkout pages are not modified by the tracker.
1. Read the IDs on the client
The tracking script exposes a small API. Use the global attribution metadata helper or the drop-in module helper:
// Browser global helper from the tracker
const metadata = window.Metrivo.getAttributionMetadata()
// {
// metrivo_visitor_id, metrivo_session_id, metrivo_site_id,
// public_key, landing_url, referrer, utm_source, ...
// }
// Drop-in helper for app code
import { metrivoCheckoutMetadata } from "@/lib/tracking/checkout-tagging"
const metadata = metrivoCheckoutMetadata()2. Stripe — checkout metadata
Pass the IDs to your server, then attach them to the Checkout Session or Payment Intent metadata (and optionally client_reference_id).
stripe.checkout.sessions.create({
mode: "subscription",
line_items: [{ price: "price_123", quantity: 1 }],
success_url: "https://example.com/success",
client_reference_id: metadata.metrivo_session_id,
metadata,
})3. Dodo Payments — metadata
Dodo forwards the metadata object on its payment webhook. Include the same keys.
dodo.payments.create({
product_cart: [{ product_id: "prod_123", quantity: 1 }],
return_url: "https://example.com/success",
metadata,
})4. Razorpay — order notes
Razorpay does not have a metadata field, so put the IDs in notes. They arrive on payment.captured and order.paid webhooks.
razorpay.orders.create({
amount: 4900,
currency: "USD",
notes: metadata,
})5. Paddle — custom_data
Paddle Billing sends custom_data in transaction webhooks. Put the same normalized metadata object there when creating checkout.
createPaddleCheckout({
items: [{ price_id: "pri_123", quantity: 1 }],
customer: { email },
custom_data: metadata,
})6. Lemon Squeezy — custom_data
Lemon Squeezy sends checkout custom data under webhook meta.custom_data.
createLemonSqueezyCheckout({
variant_id: variantId,
checkout_data: {
email,
custom: metadata,
},
})What this unlocks
With the IDs present, Metrivo records a high-confidence, session-level match and writes it to an append-only attribution ledger — your durable revenue history. Without them, Metrivo falls back to email-hash or metadata evidence, or leaves the payment transparently unattributed. Nothing is ever guessed.