Someone lands on your site from a newsletter link tagged with utm_source, reads your pricing and clicks buy. The browser leaves for checkout.stripe.com or buy.stripe.com, the customer pays, and the payment in Stripe has no idea a newsletter was involved. If you want revenue by source, the source has to cross that redirect with the customer. Stripe gives you two fields for it, client_reference_id and metadata, and a webhook that hands them back. This post shows how to use each one with a Checkout Session you create and with a Payment Link, how to read them back from the webhook, renewals included, and how Vero’s checkout module and webhook do the same job without you writing that code.
Why do UTM parameters disappear at Stripe Checkout?
UTM parameters live in the URL of the page the visitor landed on. They are not a property of the visitor. The moment the visitor opens another page, the tags are gone from the address bar, unless your own code read them and kept them somewhere.
Checkout makes it worse. Stripe Checkout runs on Stripe’s domain, so the payment page never sees your landing URL, and the only referrer it gets is your own pricing page. Stripe stores what you send it when the session is created and nothing else. Send nothing about the source and the payment arrives without one.
So the work has two halves. Keep the source, or a pointer to it, until the customer clicks buy. Then put it into a field Stripe stores on the payment and returns in the webhook.
Carry the source on a Checkout Session you create
If your server creates the Checkout Session, you set two fields on it. client_reference_id takes one string, which Stripe describes as a reference to reconcile the session with your own systems, such as a customer or cart id. metadata takes key-value pairs: up to 50 keys, each key up to 40 characters and each value up to 500. Both are listed in the Checkout Session create reference.
For UTM tags, metadata is the natural fit, one key per tag: utm_source set to newsletter, utm_medium to email, utm_campaign to the name of the send. client_reference_id holds a single value, so it suits one id better than five tags.
For a subscription, set the same keys on subscription_data.metadata too. Stripe does not copy metadata between related objects on its own, so the session’s metadata stays on the session. What you put in subscription_data.metadata is saved on the subscription, and each invoice the subscription creates gets a snapshot of it in parent.subscription_details.metadata. Stripe’s metadata guide lists which objects copy to which. That snapshot is what lets a renewal six months later still say where the customer came from.
How do you pass UTM parameters to a Stripe Payment Link?
A Payment Link is a fixed URL on buy.stripe.com. There is no server call where you could set metadata per customer, so what you can pass is query parameters. Stripe documents two kinds on its Payment Links URL parameters page.
The first is UTM codes: utm_source, utm_medium, utm_campaign, utm_term and utm_content appended to the link. Stripe says they come back on your redirect URL once the customer pays, when the link’s confirmation behavior is a redirect. That hands the tags to your thank-you page. It does not put them in the webhook you would use to record the sale.
The second is client_reference_id. Append it to the link and Stripe sends it in the checkout.session.completed webhook. The value can use letters, digits, dashes and underscores, up to 200 characters. An invalid one is dropped without an error, so a malformed value fails quietly.
The catch is that a Payment Link is one URL for everyone. A client_reference_id typed into the link is the same for every buyer, so it can name a campaign at most, never a visit. To carry something per visitor, a script has to rewrite the link at the moment of the click.
Read the source back from checkout.session.completed
When the payment finishes, Stripe sends checkout.session.completed to your webhook endpoint. The event carries the Checkout Session with client_reference_id and metadata as you set them, plus the amounts. Check the stripe-signature header against your endpoint’s signing secret before you trust any of it, then record the sale with its source.
Two details catch people. A completed session is not always a paid one: with a delayed method such as SEPA Direct Debit, payment_status is not paid yet, and the money is confirmed later by checkout.session.async_payment_succeeded. Stripe’s fulfillment guide covers both events.
And renewals never pass through Checkout. They arrive as invoice.paid, and the source is in the invoice’s parent.subscription_details.metadata only if you set subscription_data.metadata when the subscription was created. Skip that step and every renewal reaches you with no source.
Carry the visit, not the tags
Everything above assumes the tags are still at hand when the customer clicks buy. Usually they are not: the visitor landed on a blog post, read three pages and then opened pricing. Keeping five tags alive across those pages means writing them to the device, in a cookie or in localStorage, and that brings back the consent question you were trying to avoid.
The alternative is to carry one id that names the visit, and leave the tags where they were recorded: in your analytics, on the first event of that visit. The checkout carries the id, the webhook brings it back, and the server looks up how that visit began. Nothing about the source has to survive in the browser. How to attribute revenue without cookies explains why the credited visit is the one that brought the customer, not the checkout page.
What Vero’s checkout module and webhook do for you
The tracker’s checkout module handles the Payment Link half. On a click on a buy.stripe.com link it adds client_reference_id with the session id. The rest of the link stays as it was, a value the page already set is never replaced, and the module sends no event. It adds 319 B gzipped to the 1.2 KB core.
If your server creates the Checkout Session, read the id with window.vero.session() on the page, send it to your server with the request, and set it as client_reference_id or as metadata.vero. For a free trial, put it in subscription_data.metadata.vero as well, which every invoice of that subscription carries. The module does not recognize a checkout on your own domain, so this is the path for one.
On the Vero side, you paste one webhook URL into Stripe and select four events: checkout.session.completed, checkout.session.async_payment_succeeded, invoice.paid and charge.refunded. Vero checks every signature and refuses one more than 5 minutes off, reads the visit from client_reference_id, metadata.vero or the subscription’s metadata.vero, and stores the sale without tax under the source of that visit. An id counts only if it names a visit of that site. The Stripe integration page has the four steps, and the docs list every field Vero reads.
A renewal with no visit on it inherits the source of the customer’s first attributed payment, and a refund comes off the source of the sale it reverses. Every plan stores the sale and shows the total. Which source brought it is part of revenue attribution on Pro.
When does the source still go missing?
A sale arrives with no source when nothing named a visit: a Payment Link pasted into an email or a chat, where the tracker never ran; a session your server created without the id; a buyer whose ad blocker stopped the script. The sale still counts in your revenue, outside every source.
If your Payment Link already carries a client_reference_id of your own, the module keeps it, and that sale cannot carry the visit. On a session you create, put your id in client_reference_id and the visit in metadata.vero to keep both.
A test-mode purchase is acknowledged and not counted. It proves the URL and the secret work without adding to your revenue. The step-by-step guide walks through a first sale from end to end.
Unsure of a term? Read the glossary

Vero is built by one person in Spain. I read every waitlist entry and pick the beta accounts myself.