When it comes to conversion tracking, a sale event happens when a user purchases your product or service. Examples include:

  • Subscribing to a paid plan
  • Usage expansion (upgrading from one plan to another)
  • Purchasing a product

In this guide, we will be focusing on tracking sale events with Stripe as the payment processor by leveraging Dub’s Stripe integration.

Prerequisites

Before you get started, make sure you follow the Dub Conversions quickstart guide to get Dub Conversions set up for your links:

  1. Enable conversion tracking for your links
  2. Install the @dub/analytics client-side SDK
  3. Install the Dub server-side SDK

Then, depending on your authentication provider, follow the relevant guide to set up lead conversion tracking:

Alternatively, if your setup doesn’t involve an authentication step (e.g. for one-time purchases / if you’re using Stripe Payment Links), you can skip the server-side SDK step above and just pass the Dub click ID to the Stripe Checkout Flow (instructions below).

Step 1: Install the Dub Stripe integration

1

Find Dub on the Stripe App Marketplace

Navigate to the Dub: Conversions Analytics page on the Stripe App Marketplace.

2

Install the Stripe app

On the top right, click on Install app to install the Dub Conversions app on your Stripe account.

Alternatively, you can also install the Stripe app in test mode first to test your end-to-end flow without involving real money.

Once the app is installed, click on Continue to app settings to finish the installation.

3

Connect Stripe to your Dub workspace

In the app settings page, click on Connect workspace to connect your Stripe account with your Dub workspace.

This will redirect you to the Dub OAuth flow, where you can select the Dub workspace you want to connect to your Stripe account.

Once you click on Authorize, you will be redirected back to the Dub app settings page on Stripe, where you should see that the integration is now installed.

Dub’s Stripe integration will automatically forward the following events to Dub:

  • customer.created: When a new customer is created
  • checkout.session.completed: When a customer completes a checkout session
  • invoice.paid: When an invoice is paid (for tracking recurring subscriptions)

Step 2: Associate Stripe customer with your customer ID

Next, we’ll need to associate the Stripe customer object with the user ID in your database (which we tracked in the lead conversion tracking step).

This will allow Dub to automatically listen for purchase events from Stripe and associate them with the original click event (and by extension, the link that the user came from).

There are 3 ways to associate the Stripe customer object with the user ID in your database:

  1. Include your customer’s unique user ID in checkout sessions
  2. Pass the user ID and the click event ID in the Stripe customer creation flow
  3. Pass the Dub click ID to the Stripe Checkout Flow

Option 1: Include your customer’s unique user ID in checkout sessions

When you create checkout sessions for your users, pass your customer’s unique user ID in your database as the dubCustomerId value in the metadata field.

app/api/upgrade/route.ts
import { stripe } from "@/lib/stripe";

const user = {
  id: "user_123",
  email: "user@example.com",
  teamId: "team_xxxxxxxxx",
};

const priceId = "price_xxxxxxxxx";

const stripeSession = await stripe.checkout.sessions.create({
  customer_email: user.email,
  success_url: "https://app.domain.com/success",
  line_items: [{ price: priceId, quantity: 1 }],
  mode: "subscription",
  client_reference_id: user.teamId,
  metadata: {
    dubCustomerId: user.id, // the unique user ID of the customer in your database
  },
});

This way, when the customer completes their checkout session, Dub will automatically associate the checkout session details (invoice amount, currency, etc.) with the customer – and by extension, the original click event.

Option 2: Pass the user ID and the click event ID in the Stripe customer creation flow

Alternatively, if you don’t use Stripe’s checkout session creation flow, you can also pass the user ID and the click event ID (dub_id) in the Stripe customer creation flow:

app/api/create-customer/route.ts
import { stripe } from "@/lib/stripe";

const user = {
  id: "user_123",
  email: "user@example.com",
  teamId: "team_xxxxxxxxx",
};

const dub_id = req.headers.get("dub_id");

await stripe.customers.create({
  email: user.email,
  name: user.name,
  metadata: {
    dubCustomerId: user.id,
    dubClickId: dub_id,
  },
});

This way, when the customer makes a purchase, Dub will automatically associate the purchase details (invoice amount, currency, etc.) with the original click event.

Option 3: Pass the Dub click ID to the Stripe Checkout Flow

If your setup doesn’t involve a lead event and goes straight to the Stripe checkout flow (e.g. for one-time purchases), you can simply pass the Dub click ID as the client_reference_id parameter to enable conversion tracking with Dub.

When passing the Dub click ID as the client_reference_id parameter to Stripe, remember to prefix it with dub_id_ to allow Dub to detect the conversion event.

Behind the scenes, Dub will automatically detect when the user completes the checkout flow and track the customer as a lead and the purchase event as a sale.

In this case, we will also update the customer’s externalId with their Stripe customer ID for future reference.

Step 3: View conversion results

And that’s it – you’re all set! You can now sit back, relax, and watch your conversion revenue grow. We provide 3 different views to help you understand your conversions:

  • Funnel chart: A funnel chart view visualizing the conversion & dropoff rates across the different steps in the conversion funnel (clicks → leads → sales).
  • Real-time events stream: A real-time events stream of every single conversion event that occurs across all your links in your workspace.

Currency support

For simplicity, Dub records all sales in the native currency of the Stripe account. For example, if you’re using USD for your Stripe account, Dub will record all sales in USD.

If you’re using Stripe’s Adaptive Pricing feature, Dub will still record the sale amount using the currency of your Stripe account:

checkout.session.completed
// Stripe checkout.session.completed event payload
{
  "id": "{{EVENT_ID}}",
  "object": "event",
  "type": "checkout.session.completed",
  "data": {
    "object": {
      "id": "{{SESSION_ID}}",
      "object": "checkout.session",
      "currency": "cad",
      "amount_subtotal": 2055,
      "amount_total": 2055,
      "currency_conversion": {
        "amount_subtotal": 1500,
        "amount_total": 1500, // this is the amount that Dub will record
        "source_currency": "usd", // the currency of your Stripe account
        "fx_rate": "1.37"
      }
    }
  }
}

Example Apps