How to track sale conversion events with Stripe and Dub

This feature is only available on Business plans and above.

Dub’s best-in-class Stripe integration listens to payment events on Stripe and tracks them as sales on Dub.

A diagram showing how lead events are tracked in the conversion funnel

Here are the events that Dub listens to:

Recurring subscriptions
One-time payments
Free trials
Refunds (for voiding partner commissions)
Disputes (for holding partner commissions until the dispute closes)
Cancellations/churn
Usage expansion

In this guide, we’ll learn how to install and set up the Dub Stripe integration for tracking sale conversion events.

Installing the Dub Stripe integration

Find Dub on the Stripe App Marketplace

Navigate to the Dub Stripe Integration on the Stripe App Marketplace.

The Dub integration page on the Stripe App Marketplace

Install the Stripe app

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

The Stripe integration installation flow

Alternatively, you can also install the Stripe app in a Stripe sandbox first and connect it to your Dub staging workspace 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.

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.

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 voiding partner commissions)
charge.dispute.created: When a charge is disputed (for holding partner commissions)
charge.dispute.closed: When a dispute is closed (for refunding or releasing the held commission)

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.

Option 1: Using Stripe Checkout (recommended)
Option 2: Using Stripe Customers
Option 3: Using Stripe Coupons and Promotion Codes
Option 4: Using Stripe Payment Links

Option 1: Using Stripe Checkout (recommended)

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).

How does this work?

Remember in the lead conversion tracking guide, we passed the user’s unique user ID along with the click event ID in the dub.track.lead call?

Node.js

await dub.track.lead({
  clickId,
  eventName: "Sign Up",
  customerExternalId: user.id, // the unique user ID of the customer in your database
  customerName: user.name,
  customerEmail: user.email,
  customerAvatar: user.image,
});

Under the hood, Dub records the user as a customer and associates them with the click event that they came from.Then, when the user makes a purchase, Dub will automatically associate the checkout session details (invoice amount, currency, etc.) with the customer – and by extension, the original click event.

First, you’ll need to complete the following prerequisites:

Then, when you create a checkout session, pass your customer’s unique user ID in your database as the dubCustomerExternalId 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: {
    dubCustomerExternalId: 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.

If you’re using guest checkout (e.g. with mode: "payment"), the customer field in the checkout.session.completed webhook event will be null, and sales won’t be tracked on Dub.To fix this, set customer_creation to always when creating your checkout session:

Node.js

const stripeSession = await stripe.checkout.sessions.create({
  // ... other options
  customer_creation: "always", // ensures a Stripe customer is created
});

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

Then, when you create a Stripe customer, pass the user’s unique user ID in your database as the dubCustomerExternalId 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: {
    dubCustomerExternalId: user.id,
    dubClickId: dub_id,
  },
});

Alternatively, you can also pass the dubCustomerExternalId 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: {
    dubCustomerExternalId: 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.

When using Stripe Customers, lead and sale events are tracked but lead rewards will not be generated. Sale rewards (both recurring and one-time rewards) will still be generated as usual.

Option 3: Using Stripe Coupons and Promotion Codes

If you’re using Stripe Coupons and Promotion Codes, you can start tracking sale conversions simply by installing the Stripe integration in your Dub workspace. Then, follow these steps to generate discount codes for your partners on Dub, and you are all set!

While Stripe promo-code-based discounts is much easier to set up (no code required), you sacrifice attribution accuracy since you won’t have any insights into the customer’s geolocation, device info, referrer details, and UTM data. Our Stripe integration will try to derive the customer’s location based on their Stripe billing address, but it can sometimes be inaccurate.

Option 4: Using Stripe Payment Links

When using Stripe Payment Links, lead and sale events are tracked but lead webhooks and lead rewards will not be generated. Sale rewards (both recurring and one time rewards) will still be generated as usual.

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.

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:

Install the Dub Analytics script, which automatically detects the dub_id in the URL and stores it as a first-party cookie on your site.
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

What if I'm using Stripe Pricing Tables?

If you’re using Stripe Pricing Tables – you’d want to pass the Dub click ID as a client-reference-id attribute instead:

<body>
  <h1>We offer plans that help any business!</h1>
  <!-- Paste your embed code script here. -->
  <script async src="https://js.stripe.com/v3/pricing-table.js"></script>
  <stripe-pricing-table
    pricing-table-id="{{PRICING_TABLE_ID}}"
    publishable-key="pk_test_51ODHJvFacAXKeDpJsgWLQJSzBIDtCUFN6MoB4IIXKJDfWdFmiEO4JuvAU1A0Y2Ri4m4q1egIfwYy3s72cUBRCwXC00GQhEZuXa"
    client-reference-id="dub_id_xxxxxxxxxxxxxx"
  >
  </stripe-pricing-table>
</body>

import * as React from "react";

function PricingPage() {
  // Paste the stripe-pricing-table snippet in your React component
  return (
    <stripe-pricing-table
      pricing-table-id="'{{PRICING_TABLE_ID}}'"
      publishable-key="pk_test_51ODHJvFacAXKeDpJsgWLQJSzBIDtCUFN6MoB4IIXKJDfWdFmiEO4JuvAU1A0Y2Ri4m4q1egIfwYy3s72cUBRCwXC00GQhEZuXa"
      client-reference-id="dub_id_xxxxxxxxxxxxxx"
    ></stripe-pricing-table>
  );
}

export default PricingPage;

What if I'm using Stripe's Checkout Sessions API?

If you’re using Stripe’s Checkout Sessions API for a recurring subscription service, you might want to check out our Stripe Checkout option instead.If your setup doesn’t involve a lead/signup event and goes straight to the Stripe checkout flow (e.g. for one-time purchases), you can simply pass the Dub click ID (prefixed with dub_id_) as the client_reference_id parameter to enable conversion tracking with Dub.

const session = await stripe.checkout.sessions.create({
  success_url: "https://example.com/success",
  line_items: [
    {
      price: "price_xxxxxxxxxxxxxxxx",
      quantity: 2,
    },
  ],
  mode: "payment",
  client_reference_id: "dub_id_xxxxxxxxxxxxxx",
});

  stripe.checkout.Session.create(
    success_url="https://example.com/success",
    line_items=[{"price": "price_xxxxxxxxxxxxxxxx", "quantity": 2}],
    mode="payment",
    client_reference_id="dub_id_xxxxxxxxxxxxxx",
  )

  params := &stripe.CheckoutSessionParams{
    SuccessURL: stripe.String("https://example.com/success"),
    LineItems: []*stripe.CheckoutSessionLineItemParams{
      &stripe.CheckoutSessionLineItemParams{
        Price: stripe.String("price_xxxxxxxxxxxxxxxx"),
        Quantity: stripe.Int64(2),
      },
    },
    Mode: stripe.String(string(stripe.CheckoutSessionModePayment)),
    ClientReferenceID: stripe.String("dub_id_xxxxxxxxxxxxxx"),
  };
  result, err := session.New(params);

  $stripe->checkout->sessions->create([
    'success_url' => 'https://example.com/success',
    'line_items' => [
      [
        'price' => 'price_xxxxxxxxxxxxxxxx',
        'quantity' => 2,
      ],
    ],
    'mode' => 'payment',
    'client_reference_id' => "dub_id_xxxxxxxxxxxxxx",
  ]);

  Stripe::Checkout::Session.create({
    success_url: 'https://example.com/success',
    line_items: [
      {
        price: 'price_xxxxxxxxxxxxxxxx',
        quantity: 2,
      },
    ],
    mode: 'payment',
    client_reference_id: "dub_id_xxxxxxxxxxxxxx",
  })

Tracking free trials

Dub supports tracking subscription free trials as lead events on Dub. This is useful for products with free trials since you might want to track trial activations as part of your attribution flow. To enable free trial tracking, go to your Stripe integration settings and enable the Track Free Trials option:

Optionally, you can also configure the integration to track the provisioned quantity in the subscription as separate lead events. This is useful if you have a lead-based reward for your partner program and want to reward partners for each unit of the subscription that their customers purchase (e.g. $50 per lead/provisioned seat).

To differentiate between manually tracked lead events and free trial lead events for lead reward types, use the Customer Source reward condition to filter for Stripe free trial lead events:

First-time order restriction

By default, discount codes created via Dub are restricted to first-time orders in Stripe. That means the code can only be redeemed by customers who have never made a purchase (Stripe treats any successful payment or paid invoice as a prior purchase). If your signup flow creates a trial subscription or a $0 invoice, Stripe may classify those customers as returning purchasers and reject the code. In that case, go to your Stripe integration settings and disable Eligible for first-time order only:

Changes will only take effect for future discount codes. Existing promotion codes keep the restriction they were created with.

Handling disputes

When a customer disputes a charge in Stripe, Dub puts the partner commission for that sale on hold. An on-hold commission cannot be added to a payout, so the partner is not paid while the dispute is open. If the commission is already in a pending payout, Dub removes it from that payout.

Holding commissions for open disputes is only available on Advanced plans and above.

When the dispute closes, Dub updates the commission based on the outcome:

Dispute outcome	Commission status
`lost`	`Refunded`
`won`	`Pending`
`warning_closed` (an inquiry that closed without a chargeback)	`Pending`

A lost dispute refunds the commission on every plan, the same as a Stripe refund. A won dispute keeps the commission on hold in these cases:

The commission was already on hold before the dispute opened (for example, a manual hold).
A pending risk event also covers the commission.

Dub does not change a commission after its payout starts processing or is paid. To recover a paid commission after a lost dispute, create a clawback.

Tax handling

When tracking sale conversions from Stripe, Dub automatically excludes taxes from the final sale amount to ensure accurate revenue reporting. For checkout sessions, Dub calculates the sale amount by subtracting the tax amount from the total:

// Sale amount calculation for checkout sessions
saleAmount = amount_total - total_details.amount_tax;

For invoices, Dub removes the tax share from the amount paid:

// Sale amount calculation for invoices
saleAmount = amount_paid × total_excluding_tax / total;

A fully paid invoice records exactly total_excluding_tax. A partly paid invoice (for example, when a credit balance is applied) records the paid amount without its tax share. This ensures that the sale amounts recorded in Dub reflect the actual revenue before taxes, providing more accurate metrics for:

Revenue tracking and reporting
Partner commission calculations
Analytics and conversion metrics

Tax amounts are automatically excluded from all sale events tracked through the Stripe integration, including one-time purchases, subscriptions, and recurring invoices.

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"
      }
    }
  }
}

currency_conversion.amount_total includes tax, so Dub removes the session’s tax share first: currency_conversion.amount_total × (amount_total − total_details.amount_tax) / amount_total. 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.

Multiple line items per invoice

When a Stripe invoice or checkout session contains multiple line items (e.g. a base subscription plus an add-on, or several products purchased in a single transaction), Dub processes each line item individually to calculate the correct commission amount. For each line item, Dub:

Resolves the Stripe product ID for that line item.
Matches it against any product-specific reward modifiers configured for the partner’s group.
Calculates the commission for that line item using the matching reward rate (falling back to the default reward if no modifier matches). The commission uses that line’s share of the recorded sale amount (after discounts, tax exclusion and currency conversion), not the raw Stripe line amount. Line items without a product keep their share of the sale but earn no product commission.

The final commission recorded for the invoice is the sum of the per-line-item commissions.

For example, if a partner has a 40% reward for prod_gold and a 10% reward for everything else, an invoice with $100 of prod_gold and $50 of prod_addon will generate a commission of ($100 × 40%) + ($50 × 10%) = $45.

The total saleAmount recorded on Dub still reflects the full invoice total (after tax exclusion and currency conversion), so your revenue analytics remain accurate.

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: A time-series view of the number clicks, leads and sales.

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.

Example apps

Dub + Stripe Demo App

See the full example on GitHub.

GETTING STARTED

CONCEPTS

INTEGRATIONS

OPEN SOURCE

Stripe

Installing the Dub Stripe integration

Tracking sales with the Dub Stripe integration

Option 1: Using Stripe Checkout (recommended)

Option 2: Using Stripe Customers

Option 3: Using Stripe Coupons and Promotion Codes

Option 4: Using Stripe Payment Links

Tracking free trials

First-time order restriction

Handling disputes

Tax handling

Currency conversion support

Multiple line items per invoice

View conversion results

Example apps

Dub + Stripe Demo App