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. Install the @dub/analytics client-side SDK
  2. Install the Dub server-side SDK
  3. Enable conversion tracking for your links

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

Step 1: Enable the Stripe Integration on Dub

1

Go to Stripe integration page

Navigate to the Stripe integration page in your Dub workspace.

2

Enable the Stripe integration

Click on the “Enable” button to enable the Stripe integration, which will redirect you to the Stripe App installation flow.

3

4

Install the Stripe app

Select the Stripe account to install the app on, and select “Install App”.

5

Verify the installation

Once this is done, you will be redirected back to your Dub workspace and you should see that the integration is now installed.

6

Optional: Install the app in Stripe test mode

Navigate to your Stripe “Installed Apps” dashboard and verify that the Dub app is installed. We also recommmend installing the app in test mode to be able to test your end-to-end flow without using real money.

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 2 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

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
  },
});

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,
  },
});

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.

Example Apps