Conversion tracking require a Business plan subscription or higher.
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 via Stripe Payment Links
A diagram showing how lead events are tracked in the conversion funnel
In this guide, we will be focusing on tracking sale events with Stripe as the payment processor by leveraging Dub’s Stripe integration.

​
Installing the Dub Stripe integration

Dub comes with a powerful Stripe integration that automatically listens to payment events on Stripe and track them as sales on Dub. Here’s how you can install the Dub Stripe integration:
1

Find Dub on the Stripe App Marketplace

Navigate to the Dub Stripe Integration on the Stripe App Marketplace.
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.
The Stripe integration installation flow
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.
Continue to app settings
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.
Connect Stripe to Dub
This will redirect you to the Dub OAuth flow, where you can select the Dub workspace you want to connect to your Stripe account.
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.
The Stripe integration is now installed
Once the integration is installed, Dub will automatically listen to the following events on Stripe and track them as sales on Dub:
  • customer.created: When a new customer is created
  • customer.updated: When a customer is updated
  • checkout.session.completed: When a customer completes a checkout session
  • invoice.paid: When an invoice is paid (for tracking recurring subscriptions)
  • charge.refunded: When a charge is refunded (for tracking refunds and updating payout commissions for Dub Partners)

​
Tracking sales with the Dub Stripe integration

Depending on your setup, there are a few ways you can track sales with the Dub Stripe integration.
For this option to work, you need to install the Dub Stripe integration and enable conversion tracking for your links first.
If you’re using Stripe Payment Links, simply add a ?dub_client_reference_id=1 query parameter to your Stripe Payment Link when shortening it on Dub. Then, when a user clicks on the shortened link, Dub will automatically append the unique click ID as the client_reference_id query parameter to the payment link.
Stripe payment link with Dub click ID
Finally, when the user completes the checkout flow, Dub will automatically track the sale event and update the customer’s customerExternalId with their Stripe customer ID for future reference. Alternatively, if you have a marketing site that you’re redirecting your users to first, you can do this instead:
  1. Install the @dub/analytics client-side SDK, which automatically detects the dub_id in the URL and stores it as a first-party cookie on your site.
  2. Then, retrieve and append the dub_id value as the client_reference_id parameter to the payment links on your pricing page / CTA button (prefixed with dub_id_). 
    https://buy.stripe.com/xxxxxx?client_reference_id=dub_id_xxxxxxxxxxxxxx
If you have a custom checkout flow that uses Stripe’s checkout.sessions.create API, you’d want to associate the Stripe customer object with the user’s unique 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).
First, you’ll need to complete the following prerequisites:
  1. Install the Dub Stripe integration
  2. Enable conversion tracking for your links
  3. Install the @dub/analytics client-side SDK
  4. Install the Dub server-side SDK
Then, when you create a checkout session, pass your customer’s unique user ID in your database as the dubCustomerId value in the metadata field.
Node.js
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 3: Using Stripe Customers

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. First, you’ll need to complete the following prerequisites:
  1. Install the Dub Stripe integration
  2. Enable conversion tracking for your links
  3. Install the @dub/analytics client-side SDK
Then, when you create a Stripe customer, pass the user’s unique user ID in your database as the dubCustomerId value in the metadata field.
Node.js
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,
  },
});
Alternatively, you can also pass the dubCustomerId and dubClickId values in the metadata field of the Stripe customer update flow:
Node.js
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.update(user.id, {
  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.

​
Currency conversion support

If you’re using Stripe’s Adaptive Pricing feature, Dub will 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"
      }
    }
  }
}
If you’re not using Stripe Adaptive Pricing, Dub will record the sale amount in the default currency of your Dub workspace. This means that if you pass a different currency, it will be automatically converted to USD for reporting consistency – using the latest foreign exchange rates.
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 // this will be converted from CAD to USD
    }
  }
}
The default currency for all Dub workspaces is currently set to USD. We will add the ability to customize that in the future.

​
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:
Time-series line chart
  • Funnel chart: A funnel chart view visualizing the conversion & dropoff rates across the different steps in the conversion funnel (clicks → leads → sales).
Funnel chart view showing the conversion & dropoff rates from 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.
The Events Stream dashboard on Dub

​
Example Apps

Dub + Stripe Demo App

See the full example on GitHub.