Stripe

​

What this lets you do

​

Before you start

• A Traceten account with at least one site tracked.
• A Stripe account with live mode access, and permission to create restricted API keys on it.
• The Traceten snippet installed and verified on the site where Stripe Checkout runs.
• Workspace admin in Traceten. Connecting and disconnecting a revenue source affects the whole workspace, so only admins can do it.

​

Connect Stripe

​

What Traceten does with the key

1. Reads your account name, account ID and default currency from Stripe.
2. Reads one charge and one Checkout Session, to prove the key can actually see the revenue it is being connected for. Both are read, because the import uses both.
3. Creates a webhook endpoint on your Stripe account pointed at Traceten, subscribed to exactly seven events.
4. Stores the key and the webhook signing secret, both encrypted.
5. Starts importing your last 90 days of completed Checkout Sessions and paid invoices.

​

Refunds and net revenue

• The refund is dated on the day it was issued, not the day of the original charge. A past day’s revenue figure never changes after the fact, and a day on which you refunded more than you took in reads as a negative number.
• Conversion counts stay gross. A refunded charge still counts as a conversion. The money is reported separately as a refunded figure beside the net one.
• Partial refunds subtract exactly what Stripe returned. A Stripe refund states its own amount rather than a running total, so two partial refunds on one charge subtract each amount once.
• A refund for a charge Traceten never attributed leaves your totals alone. A charge from before you connected Stripe, or one outside the 90-day import, added no revenue in the first place, so there is nothing to take back off. Traceten holds such a refund and retries it rather than dropping it, in case the charge arrives later.
• A cancelled subscription is not a refund. Cancelling stops future charges. The charges already paid were earned and stay in your totals, so cancelling changes no figure in Traceten. Only a refund takes money back off.

​

If the key is missing a permission

​

Keys Traceten will not accept

• Secret keys (the ones starting sk_) are rejected. A secret key can do anything in your Stripe account, including moving money. Traceten does not need that and will not hold it.
• Publishable keys (starting pk_) are rejected. They cannot read the data Traceten needs.
• Test-mode restricted keys (rk_test_) are rejected in production. Test-mode charges carry synthetic amounts that would corrupt your revenue totals.

​

Connecting Stripe with multiple sites

• A Stripe account can be connected to only one site at a time. Reconnecting a Stripe account that is already linked to another site moves the connection to the new site and removes revenue attribution from the first one, with no error, so long as the new site has no Stripe connection of its own. If it already has one, Traceten refuses rather than replacing it; disconnect that one first. If several sites all charge through one Stripe account, only one site can hold that connection at a time; split billing into separate Stripe accounts if each site needs its own revenue attribution.
• Payments are matched only within the connecting site. A charge from a site’s Stripe account is attributed to sessions on that same site. Revenue never crosses between sites.

​

How attribution works

1. client_reference_id: if you passed the visitor’s _traceten_vid cookie through as client_reference_id, Traceten matches it to the originating session exactly. This field only exists on checkout.session.completed.
2. Payment Link redirect: if you set the Payment Link’s confirmation page to your own site with ?session_id={CHECKOUT_SESSION_ID}, the Traceten snippet on that page reports the Checkout Session id and Traceten matches it to the browser that completed the purchase. See below.
3. Email hash: if the buyer’s session called traceten.identify({ email }), Traceten matches the payment’s customer email (hashed, never stored) to that visitor. This is the only path available to invoice-only and subscription-renewal payments, which never carry a client_reference_id.
4. No match: the payment is still recorded so revenue totals stay complete, but it shows as unattributed (no AI source).

​

Payment Links: attribute without writing code

https://yourdomain.com/thanks?session_id={CHECKOUT_SESSION_ID}

• You change nothing in your code. The only edit is the redirect URL in Stripe.
• Stripe must be connected to Traceten. Traceten ignores a thank-you-page report for a site whose Stripe account is not connected, and does not hold it until you connect. A report can also be discarded for up to a minute after you connect.
• The order of events does not matter. Stripe’s webhook usually reaches Traceten before the buyer’s browser finishes redirecting. When that happens the payment is recorded first and re-attributed the moment the browser reports in, on the original payment’s own date.
• The thank-you page must load within 30 minutes of payment. Traceten pairs a report with a payment only when the two are no more than 30 minutes apart. Stripe’s redirect happens straight after payment, so this only matters for a thank-you page opened again much later.
• The thank-you page needs the snippet. If the redirect points somewhere the snippet is not installed, nothing is reported and the payment stays unattributed.
• Payment Links with “Create invoices” turned on work too. Stripe then sends both the checkout and an invoice for one payment. Traceten records the revenue once, against whichever event reaches it first, and matches the thank-you page report to that record either way. If both events are processed at the same moment, the report can miss the pairing and the payment keeps whatever match it already had.
• One-time payments are covered in both directions; subscriptions only when the browser gets there first. A subscription’s revenue is recorded against the invoice rather than the checkout, and the invoice carries no Checkout Session id, so there is nothing to match a late redirect against. For subscription Payment Links, pass client_reference_id from your own checkout flow where you can.

​

Guest checkout: pass the visitor ID via client_reference_id

// Client-side: read the visitor id and send it to your own backend
const visitorId = window.traceten.getVisitorId(); // null before the first pageview resolves

// Server-side: create a Stripe Checkout Session, using the value your client sent
const session = await stripe.checkout.sessions.create({
  // ... your checkout config
  client_reference_id: visitorIdFromClient ?? null,
});

// Server-side: read whatever cookie name Sites → Settings → Cookies shows for this site
const visitorId = req.cookies["_traceten_vid"] ?? null;
const session = await stripe.checkout.sessions.create({
  // ... your checkout config
  client_reference_id: visitorId,
});

​

Invoice and subscription payments: call identify()

// Client-side: call this as soon as you know the customer's email
// (e.g. after login, or after they submit a lead form).
traceten.identify({ email: "customer@example.com" });

​

Testing your setup

​

Backfilling historical orders

• completed Checkout Sessions: one-time purchases, Payment Links and subscription checkouts. These carry client_reference_id, so a historical order can be attributed to the exact AI session that produced it.
• paid invoices: subscription charges and manually issued invoices, attributed by email hash.

​

Rotating the key

​

Using a processor we do not integrate with

​

Disconnecting Stripe

1. Open Settings → Integrations in the dashboard and choose the site.
2. Pick Stripe, then click Disconnect and confirm.
3. Delete the restricted key in your Stripe dashboard.