Skip to main content

Introduction

Dub is a link attribution platform for short links, conversion tracking, and affiliate programs. With this integration, Dub records a sale conversion event each time a customer pays through Dodo Payments, so you can measure the return on your marketing campaigns and referral programs. Dub records a sale when a customer:
  • Completes a one-time payment
  • Subscribes to a paid plan
  • Makes a recurring subscription payment
This integration requires a Dub account with conversion tracking enabled on your links. Dub’s conversion tracking requires a Business plan or higher.
Affiliate Program Integration: This integration also works with Dub Partners, Dub’s affiliate program product. Dub attributes sales to your partners’ affiliate links, so you can track referrals, commissions, and each partner’s performance. To set up an affiliate program, see the Affiliates feature guide.

How It Works

When a visitor clicks one of your Dub short links, Dub stores a unique click ID in the dub_id cookie. To attribute sales to your links:
  1. Capture Dub’s click ID from the dub_id cookie when you create the checkout.
  2. Store the click ID in the payment’s metadata, along with your customer’s ID in your system (the external ID).
  3. Send the sale to Dub through its Track API when the payment succeeds.
Dub matches each successful sale to the original link click, which attributes the conversion to that link.

Prerequisites

Before you set up this integration, you need:
  1. A Dub account with a workspace.
  2. Conversion tracking enabled for your links.
  3. A Dub API key, which you create in your Dub dashboard under Settings → API Keys.

Getting Started

1

Enable Conversion Tracking in Dub

In your Dub dashboard, enable conversion tracking for the links you want to track sales for. Dub then records sale events for customers who arrive through those links.
To enable conversion tracking, see the Dub documentation.
2

Get Your Dub API Key

In your Dub dashboard, go to Settings → API Keys and create an API key with the conversions.write scope.
Keep your API key secure. Never expose it in client-side code.
3

Capture Click ID in Checkout

When you create a checkout, read the Dub click ID from the cookie and add it to the payment’s metadata. See Step 1.
4

Send Sale Data via Webhook

Create a webhook endpoint that sends each sale to Dub’s Track API when a payment succeeds. See Step 2.
5

Done

Sale conversion events appear in your Dub analytics dashboard, attributed to your links.

Implementation Guide

Step 1: Add Click ID and Customer ID to Checkout Metadata

When you create a checkout, read the Dub click ID from the cookie and include it in the payment’s metadata, along with your customer’s external ID.
The examples below use POST /payments, which is deprecated. It still works for existing integrations, but new integrations should use Checkout Sessions (POST /checkouts), which accept metadata the same way.

Step 2: Send Sale Data to Dub

Create a webhook endpoint that sends sale data to Dub’s Track API when a payment succeeds.
1

Open the Webhook Section

In the Dodo Payments dashboard, go to Developer → Webhooks and click Add endpoint.
Add endpoint dialog with Dub.co selected in the Integration dropdown
2

Select Dub

In Integration, select Dub.co.
3

Enter API Key

In API key, paste your Dub API key. Dodo Payments sends it in the Authorization header of every delivery.
API key field for the Dub integration
4

Check the URL and Events

If Endpoint URL is empty, enter https://api.dub.co/track/sale. In Subscribed events, select the events your transformation handles, such as payment.succeeded.
5

Configure Transformation

Under Transformation code, edit the handler to format payment data for Dub’s Track Sale API. Start from the examples.
6

Test & Create

Under Test this code, click Simulate to run the handler against a sample payload. Then click Create endpoint.

Transformation Code Examples

Each handler sends a sale to Dub only when the metadata has a click ID. For organic traffic, with no click ID, it sets webhook.cancel = true, so no request goes to Dub; the canceled delivery still shows as successful in the webhook logs. The request body follows Dub’s Track Sale API: customerExternalId and amount are required, and paymentProcessor is custom, because Dub’s list of payment processors has no Dodo Payments value. Dub takes amount in the same unit as Dodo Payments amounts: cents for two-decimal currencies, and the full integer for zero-decimal currencies such as JPY. The examples pass the amount unchanged.

Basic Sale Tracking

Track a sale when a payment succeeds:
basic_sale.js

Track Subscription Sales

Track both initial subscriptions and recurring payments. Use this handler for subscriptions instead of the payment.succeeded handlers, not alongside them: each subscription payment also fires payment.succeeded, so handling both events records every sale twice. See Subscription Integration Guide. The handler reads the click ID from the subscription’s metadata, so pass the same metadata when you create the subscription. For renewals, invoiceId combines the subscription ID with previous_billing_date, the start of the current billing period, so a retried delivery reuses the same invoiceId.
subscription_sale.js

Track Sales with Tax Exclusion

Send only the pre-tax amount to Dub, so revenue in Dub excludes tax:
sale_without_tax.js

Track Sales with Custom Event Names

Use custom event names to categorize different types of sales. The example reads an is_upgrade flag that you set in the payment’s metadata:
custom_events.js

Alternative: Client-Side Implementation

To track sales from your own server instead of through a webhook transformation, call Dub’s Track API directly after a successful payment, for example from your payment.succeeded webhook handler. The code uses your Dub API key, so run it on your server, never in the browser.

Best Practices

Capture the click ID early: Store the Dub click ID as early as possible in your checkout flow, so attribution stays accurate even if the customer leaves and returns later.
  • Include the click ID in metadata: Without the click ID, Dub can’t attribute revenue to your links.
  • Use external IDs consistently: Pass the same customer ID from your system as customerExternalId every time, for accurate customer-level analytics.
  • Handle organic traffic: Set webhook.cancel = true when there’s no click ID, to avoid unnecessary API calls.
  • Test with sample payments: Run the handler with Test this code, and confirm the integration works before you go live.
  • Monitor your Dub dashboard: Check that sales appear with the expected attribution.

Important Notes

  • Amount format: Dub expects amounts in cents for two-decimal currencies (for example, $10.00 is 1000) and the full integer for zero-decimal currencies such as JPY.
  • Currency: Use ISO 4217 currency codes, such as USD, EUR, and GBP. Dub converts each sale to USD at the latest exchange rate.
  • Free trials: Dub’s Track Sale API accepts an amount of 0, and the examples don’t skip $0 payments, so each $0 payment reaches Dub as a sale. To skip $0 payments, set webhook.cancel = true when total_amount is 0.
  • Refunds: If you need accurate revenue reporting, track refunds separately.

Troubleshooting

  • Verify that your Dub API key is correct and has the conversions.write scope.
  • Check that the dub_click_id is captured and stored in the payment metadata.
  • Check that the webhook transformation formats the payload correctly.
  • Verify that the endpoint is subscribed to payment.succeeded.
  • Confirm that conversion tracking is enabled for your Dub links.
  • Open the endpoint’s delivery attempts in the Logs tab of Developer → Webhooks to see Dub’s response. A payment with no click ID is canceled and shows as successful.
  • Confirm that customers click through your Dub short links before checkout.
  • Verify that the dub_id cookie is set on your domain.
  • Check that the click ID in the payment metadata matches the click the customer made.
  • Capture the click ID before you create the checkout.
  • Check that the payload matches Dub’s Track Sale API format.
  • Check that the required fields, customerExternalId and amount, are present, and that clickId is set for attribution.
  • Check that the amount is an integer in the smallest currency unit, not a decimal.
  • Verify that the endpoint URL is https://api.dub.co/track/sale.
  • Test the transformation with sample webhook payloads.
  • Track sales on payment.succeeded events only, not on payment.processing.
  • Use a unique invoiceId for each sale. Dub records only one sale for each invoiceId.
  • For renewals, build invoiceId from the subscription ID and the billing period, as in Track Subscription Sales. A value that changes on every delivery, such as the current time, records a duplicate sale when a delivery is retried.

Additional Resources

Dub Conversions Documentation

Read about Dub’s conversion tracking and analytics features.

Dub Track Sale API

See the complete API reference for Dub’s Track Sale endpoint.

Dub Dashboard

View conversion analytics and attribution data in your Dub dashboard.

Webhook Events Guide

Browse all Dodo Payments webhook events.
For help with this integration, contact Dodo Payments support at support@dodopayments.com.
Last modified on September 26, 2026