TraceKit DocsStripe revenue attribution
Connect a restricted Stripe key and attribute Checkout revenue to analytics sessions.
Keep your Stripe key private
The key stays on the server. Never place a complete Stripe key in client code, documentation, or screenshots.
Connect Stripe
Stripe connection is optional.
Only project owners can connect, replace, configure, or remove Stripe.
TraceKit accepts one rk_live_... key.
It rejects test, secret, publishable, and whitespace-modified keys.
Create a restricted key with these permissions:
Create a read-only Stripe key with TraceKit settings
Review the three preselected permissions. Click Create key, copy the one-time key, and paste it into TraceKit. Keep all other permissions at None.
| Stripe resource | Permission | Validation call | Purpose |
|---|---|---|---|
| Account data | Read | GET /v1/account | Validate the connected Stripe account. |
| Checkout Sessions | Read | GET /v1/checkout/sessions?limit=1 | Import completed Checkout revenue. |
| Products | Read | GET /v1/products?limit=1 | Support saved product filters. |
| All other resources | None | No preflight call | Apply least privilege. |
Enter the restricted key in the project owner Stripe settings. TraceKit validates the account, Checkout Sessions, and Products calls.
Add Checkout metadata
Put attribution identifiers directly on Checkout Session.metadata.
Read the host-only cookies in a same-origin Next.js server route.
import { cookies } from 'next/headers';
const cookieStore = await cookies();
const visitorId = cookieStore.get('tracekit_visitor_id')?.value;
const sessionId = cookieStore.get('tracekit_session_id')?.value;
if (!visitorId || !sessionId) {
return new Response('TraceKit analytics IDs are unavailable', { status: 400 });
}
const session = await stripe.checkout.sessions.create({
mode: 'payment',
line_items: [{ price: 'price_...', quantity: 1 }],
success_url: 'https://example.com/success',
cancel_url: 'https://example.com/cancel',
metadata: {
tracekit_visitor_id: visitorId,
tracekit_session_id: sessionId,
},
});Same-origin Checkout route
Use this example only when the Checkout route shares the browser hostname.
The Browser SDK exposes no public visitor or session identity getter.
Host-only cookies use Path=/ and SameSite=Lax.
HTTPS adds Secure.
The visitor cookie lasts 365 days.
The session cookie expires after 30 minutes of inactivity.
Host-only cookies do not reach another API host.
Blocked cookies prevent the server route from reading attribution IDs.
Payments without readable IDs remain visible as unmatched.
| Metadata field | Status | Meaning |
|---|---|---|
tracekit_visitor_id | Required for attribution | Browser visitor ID with 32 lowercase hexadecimal characters, and not all zeroes. |
tracekit_session_id | Required for attribution | Browser session ID with 32 lowercase hexadecimal characters, and not all zeroes. |
tracekit_trace_id | Optional | Enables View checkout trace when the trace exists. |
tracekit_user_id | Optional | Stores an opaque internal user ID for future use. |
Verify sync and attribution
No analytics webhook
TraceKit polls Checkout Sessions every five minutes. Analytics revenue needs no webhook setup.
TraceKit imports only completed, paid, live-mode Checkout Sessions. It does not import PaymentIntents or Payment Links as separate revenue sources. Renewals are included by default. Excluding renewals changes reports only. TraceKit does not import subscription cancellations. TraceKit performs no foreign-exchange conversion. The selected dashboard currency controls which imported revenue appears.
The first import covers the 30-day analytics retention window. Later syncs resume from a cursor and reconcile the prior 24 hours. Unmatched payments stay visible. Removing Stripe deletes its connection settings and imported payments.
Continue
- Return to Analytics setup for browser installation.
- Read the analytics reference for attribution and revenue states.