Stripe Checkout Tracking: Developer Guide 2025

Stripe Checkout tracking lets developers see exactly which marketing campaigns generate actual revenue from their e-commerce store. This complete guide shows you how to implement Stripe payment attribution and e-commerce analytics in 15-20 minutes using Pimms.

You'll get real-time payment tracking showing which ads, email campaigns, or YouTube posts drive actual purchases through your Stripe Checkout flow. Perfect for e-commerce conversion tracking with complete revenue attribution from click to payment.

What you'll implement: Complete payment tracking setup, webhook integration, and revenue attribution for every Stripe Checkout transaction in your application.

👉 Before continuing, make sure you understand the Pimms attribution flow:
📘 How Pimms tracks clicks, leads, and sales

What you’ll achieve

By the end of this guide, you’ll be able to:

• Automatically track when someone completes a Stripe Checkout
• Attribute that sale to a Pimms click
• Link the conversion to a user or customer in your app

Pimms handles the heavy lifting — you just need to pass the right ID at the right moment.

1. Prerequisites

Before you dive into code, make sure you’ve completed the setup below:

• Client-side tracking is live

See Set up the Pimms script or SDK on your site

• Your links have conversion tracking enabled

Either globally in Workspace Settings, or individually from the Link Builder.

• You’ve installed the official Pimms x Stripe integration

Follow the steps in the Stripe setup guide

2. Use checkout sessions to track sales

If you're using stripe.checkout.sessions.create, just pass the right ID when creating the session.

This lets Pimms associate the purchase with the original click and the correct user in your database.

Use the ID you used to create the conversion.

Example:

import { stripe } from "@/lib/stripe"
 
const user = {
  id: "user_123",
  email: "user@example.com"
}
 
const pimms_id = req.cookies["pimms_id"]
 
const session = await stripe.checkout.sessions.create({
  customer_email: user.email,
  client_reference_id: "project_123",
  metadata: {
    // your internal user ID or email (the one used to create the conversion event)
    pimmsCustomerId: user.id 
  }
})

That’s all.

3. Using Stripe Customers (alternative flow)

If you're not using Stripe Checkout sessions, you can still associate purchases by storing the data in the Stripe Customer object.

Option A — During customer creation

Pass the pimmsCustomerId and pimmsClickId in the metadata:

import { stripe } from "@/lib/stripe"
 
const user = {
  id: "user_123",
  email: "user@example.com",
  teamId: "team_xxxxxxxxx"
}
 
const pimms_id = req.headers.get("pimms_id")
 
await stripe.customers.create({
  email: user.email,
  name: user.name,
  metadata: {
    // your internal user ID or email (the one used to create the conversion event)
    pimmsCustomerId: user.id,
    // get the pimms_id from the cookie (recommended) or window.pimms_id
    pimmsClickId: pimms_id
  }
})

Option B — Update existing customer

Same logic, but with .update instead of .create:

import { stripe } from "@/lib/stripe"
 
const user = {
  id: "user_123",
  email: "user@example.com",
  teamId: "team_xxxxxxxxx"
}
 
const pimms_id = req.headers.get("pimms_id")
 
await stripe.customers.update(user.id, {
  metadata: {
    // your internal user ID or email (the one used to create the conversion event)
    pimmsCustomerId: user.id,
    // get the pimms_id from the cookie (recommended) or window.pimms_id
    pimmsClickId: pimms_id
  }
})

✅ This allows Pimms to link future payments (invoices, renewals, etc.) to the original click.

4. What Pimms tracks automatically

Once your integration is live, Pimms will listen for key Stripe events:

• checkout.session.completed — primary sale trigger
• invoice.paid — for subscriptions
• customer.created, customer.updated — for ID mapping
• charge.refunded — to handle refunds

You don’t need to manage any webhooks — Pimms handles everything behind the scenes.

Currency handling (soon)

Multi-currency support is coming soon.

For now, Pimms automatically converts all amounts to USD using real-time exchange rates. Workspace-level currency preferences will be added shortly.

What about Stripe Payment Links?

If you're using Stripe Payment Links instead of Checkout, follow this guide:
👉 Track sales using Stripe Payment Links

FAQs

You're done 🎉

Stripe Checkout is now fully connected to your Pimms conversion tracking and sales attribution flow.

Every sale is tied to the right link, campaign, and user — with complete analytics and zero manual effort.

👉 Track your first sale