Dub

Introduction

Dub is a powerful link management platform that helps you create, share, and track short links. By integrating Dodo Payments with Dub, you can automatically track sale conversion events when customers complete purchases, enabling you to measure the ROI of your marketing campaigns and referral programs. A “sale” event is recorded in Dub 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.

Affiliate Program Integration: This integration also works seamlessly with Dub Partners for tracking affiliate referrals and commissions. Use Dub’s conversion tracking to attribute sales to your affiliate links and measure partner performance. Learn more about setting up affiliate programs in our Affiliates feature guide.

How It Works

Dub tracks visitors through a unique click ID (dub_id) stored in a cookie when users click your Dub short links. To attribute sales to your links, you need to:

Capture Dub’s click ID from the dub_id cookie when creating checkout sessions
Store the click ID in your payment metadata along with the customer’s external ID
Send sale data to Dub when payments succeed using their Track API

This allows Dub to match successful sales with the original link click, giving you complete conversion attribution.

Prerequisites

Before setting up this integration, ensure you have:

A Dub account with a workspace
Conversion tracking enabled for your links
Your Dub API key (available in your Dub dashboard under Settings → API Keys)

Getting Started

Enable Conversion Tracking in Dub

In your Dub dashboard, enable conversion tracking for the links you want to track sales for. This allows Dub to record sale events when customers complete purchases.

Learn more about enabling conversion tracking in the Dub documentation.

Get Your Dub API Key

Navigate to your Dub dashboard → Settings → API Keys and create a new API key with conversions.write scope.

Keep your API key secure and never expose it in client-side code.

Capture Click ID in Checkout

When creating a checkout session, capture the Dub click ID from the cookie and add it to your payment metadata.

Send Sale Data via Webhook

Configure a webhook to send sale data to Dub’s Track API when payments succeed.

Done!

Sale conversion events will now appear in your Dub analytics dashboard with full attribution to your links.

Implementation Guide

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

When creating a checkout session, capture the Dub click ID from the cookie and include it in your payment metadata along with your customer’s external ID.

Les exemples ci-dessous utilisent POST /payments, qui est obsolète. Il fonctionne toujours pour les intégrations existantes, mais les nouvelles intégrations doivent utiliser Checkout Sessions (POST /checkouts) — metadata reçoit sa valeur de la même manière.

import { cookies } from 'next/headers';
import DodoPayments from 'dodopayments';

const client = new DodoPayments();

export async function createCheckout(productId: string, customerId: string) {
  // Capture Dub click ID from cookie
  const dubClickId = cookies().get('dub_id')?.value;

  const payment = await client.payments.create({
    billing: {
      city: 'New York',
      country: 'US',
      state: 'NY',
      street: '123 Main St',
      zipcode: '10001',
    },
    customer: {
      email: 'customer@example.com',
      name: 'John Doe',
    },
    product_cart: [{ product_id: productId, quantity: 1 }],
    metadata: {
      dub_click_id: dubClickId,           // Store Dub click ID
      dub_external_id: customerId,        // Store your customer's unique ID
    },
  });

  return payment;
}

const express = require('express');
const DodoPayments = require('dodopayments').default;
const router = express.Router();

const client = new DodoPayments();

router.post('/create-checkout', async (req, res) => {
  // Capture Dub click ID from cookie
  const dubClickId = req.cookies?.dub_id;

  const payment = await client.payments.create({
    billing: {
      city: 'New York',
      country: 'US',
      state: 'NY',
      street: '123 Main St',
      zipcode: '10001',
    },
    customer: {
      email: req.body.email,
      name: req.body.name,
    },
    product_cart: [{ product_id: req.body.productId, quantity: 1 }],
    metadata: {
      dub_click_id: dubClickId,           // Store Dub click ID
      dub_external_id: req.body.customerId, // Store your customer's unique ID
    },
  });

  res.json({ payment });
});

from fastapi import FastAPI, Request
from dodopayments import DodoPayments

app = FastAPI()
client = DodoPayments()

@app.post("/create-checkout")
async def create_checkout(request: Request):
    # Capture Dub click ID from cookie
    dub_click_id = request.cookies.get("dub_id")

    body = await request.json()

    payment = client.payments.create(
        billing={
            "city": "New York",
            "country": "US",
            "state": "NY",
            "street": "123 Main St",
            "zipcode": "10001",
        },
        customer={
            "email": body["email"],
            "name": body["name"],
        },
        product_cart=[{"product_id": body["product_id"], "quantity": 1}],
        metadata={
            "dub_click_id": dub_click_id,          # Store Dub click ID
            "dub_external_id": body["customer_id"], # Store your customer's unique ID
        },
    )

    return {"payment": payment}

package main

import (
    "context"

    "github.com/dodopayments/dodopayments-go"
)

func createCheckout(dubClickId, customerId, productId string) (*dodopayments.PaymentNewResponse, error) {
    client := dodopayments.NewClient()

    payment, err := client.Payments.New(context.Background(), dodopayments.PaymentNewParams{
        Billing: dodopayments.F(dodopayments.BillingAddressParam{
            City:    dodopayments.F("New York"),
            Country: dodopayments.F(dodopayments.CountryCodeUs),
            State:   dodopayments.F("NY"),
            Street:  dodopayments.F("123 Main St"),
            Zipcode: dodopayments.F("10001"),
        }),
        Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](
            dodopayments.NewCustomerParam{
                Email: dodopayments.F("customer@example.com"),
                Name:  dodopayments.F("John Doe"),
            },
        ),
        ProductCart: dodopayments.F([]dodopayments.OneTimeProductCartItemParam{{
            ProductID: dodopayments.F(productId),
            Quantity:  dodopayments.F(int64(1)),
        }}),
        Metadata: dodopayments.F(map[string]string{
            "dub_click_id":    dubClickId, // Store Dub click ID
            "dub_external_id": customerId, // Store your customer's unique ID
        }),
    })

    return payment, err
}

Étape 2 : Envoyer les données de vente à Dub

Configurez un endpoint webhook pour envoyer les données de vente à l’API Track de Dub lorsque les paiements sont réussis.

Open the Webhook Section

Dans votre tableau de bord Dodo Payments, accédez à Webhooks → + Add Endpoint et développez le menu déroulant des intégrations.

Select Dub

Sélectionnez la carte d’intégration Dub.

Enter API Key

Saisissez votre clé API Dub dans le champ de configuration.

Configure Transformation

Modifiez le code de transformation afin de formater les données de paiement pour l’API Track Sale de Dub.

Test & Create

Testez avec des payloads d’exemple, puis cliquez sur Create pour activer l’intégration.

Exemples de code de transformation

Suivi des ventes de base

Suivez les ventes lorsque les paiements sont réussis :

basic_sale.js

function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;

    // Only send to Dub if click ID exists in metadata
    if (payment.metadata && payment.metadata.dub_click_id) {
      webhook.payload = {
        clickId: payment.metadata.dub_click_id,
        externalId: payment.metadata.dub_external_id || payment.customer.customer_id,
        amount: payment.total_amount, // Ensure the amount is in cents
        currency: payment.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: payment.payment_id,
        metadata: {
          customer_email: payment.customer.email,
          customer_name: payment.customer.name,
          product_id: payment.product_cart ? payment.product_cart.map(product => product.product_id).join(', ') : undefined,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }
  return webhook;
}

Suivi des ventes d’abonnements

Suivez à la fois les abonnements initiaux et les paiements récurrents :

subscription_sale.js

function handler(webhook) {
  const data = webhook.payload.data;

  // Track initial subscription activation
  if (webhook.eventType === "subscription.active") {
    if (data.metadata && data.metadata.dub_click_id) {
      webhook.payload = {
        clickId: data.metadata.dub_click_id,
        externalId: data.metadata.dub_external_id || data.customer.customer_id,
        amount: data.recurring_pre_tax_amount, // Amount in cents
        currency: data.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: data.subscription_id,
        eventName: "Subscription Started",
        metadata: {
          subscription_id: data.subscription_id,
          product_id: data.product_id,
          billing_interval: data.payment_frequency_interval,
          customer_email: data.customer.email,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }

  // Track recurring subscription payments
  if (webhook.eventType === "subscription.renewed") {
    if (data.metadata && data.metadata.dub_click_id) {
      webhook.payload = {
        clickId: data.metadata.dub_click_id,
        externalId: data.metadata.dub_external_id || data.customer.customer_id,
        amount: data.recurring_pre_tax_amount,
        currency: data.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: `${data.subscription_id}_${Date.now()}`,
        eventName: "Subscription Renewed",
        metadata: {
          subscription_id: data.subscription_id,
          product_id: data.product_id,
          customer_email: data.customer.email,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }

  return webhook;
}

Suivi des ventes hors taxes

Envoyez uniquement le montant hors taxes à Dub pour assurer un suivi précis des revenus :

sale_without_tax.js

function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;

    if (payment.metadata && payment.metadata.dub_click_id) {
      // Calculate pre-tax amount (total minus tax)
      const preTaxAmount = payment.total_amount - (payment.tax || 0);

      webhook.payload = {
        clickId: payment.metadata.dub_click_id,
        externalId: payment.metadata.dub_external_id || payment.customer.customer_id,
        amount: preTaxAmount, // Pre-tax amount in cents
        currency: payment.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: payment.payment_id,
        metadata: {
          total_amount: payment.total_amount,
          tax_amount: payment.tax || 0,
          customer_email: payment.customer.email,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }
  return webhook;
}

Suivi des ventes avec des noms d’événements personnalisés

Utilisez des noms d’événements personnalisés pour catégoriser différents types de ventes :

custom_events.js

function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;

    if (payment.metadata && payment.metadata.dub_click_id) {
      // Determine event name based on payment type
      let eventName = "Purchase";
      if (payment.subscription_id) {
        eventName = "Subscription Purchase";
      } else if (payment.metadata && payment.metadata.is_upgrade) {
        eventName = "Plan Upgrade";
      }

      webhook.payload = {
        clickId: payment.metadata.dub_click_id,
        externalId: payment.metadata.dub_external_id || payment.customer.customer_id,
        amount: payment.total_amount,
        currency: payment.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: payment.payment_id,
        eventName: eventName,
        metadata: {
          product_id: payment.product_cart ? payment.product_cart.map(product => product.product_id).join(', ') : undefined,
          customer_email: payment.customer.email,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }
  return webhook;
}

Alternative : implémentation côté client

Si vous préférez suivre les ventes depuis votre serveur plutôt que d’utiliser des webhooks, vous pouvez appeler directement l’API Track de Dub après un paiement réussi :

'use server';

import { Dub } from 'dub';

const dub = new Dub();

export async function trackSale(
  paymentId: string,
  clickId: string,
  customerId: string,
  amount: number,
  currency: string
) {
  await dub.track.sale({
    clickId: clickId,
    externalId: customerId,
    amount: amount,
    currency: currency,
    paymentProcessor: 'dodo',
    invoiceId: paymentId,
  });
}

const { Dub } = require('dub');

const dub = new Dub();

async function trackSale(payment) {
  if (payment.metadata?.dub_click_id) {
    await dub.track.sale({
      clickId: payment.metadata.dub_click_id,
      externalId: payment.metadata.dub_external_id,
      amount: payment.total_amount,
      currency: payment.currency,
      paymentProcessor: 'dodo',
      invoiceId: payment.payment_id,
    });
  }
}

Bonnes pratiques

Capturez l’ID de clic rapidement : enregistrez l’ID de clic Dub dès que possible dans votre parcours de paiement afin de garantir une attribution précise, même si l’utilisateur quitte la page et revient plus tard.

Incluez toujours l’ID de clic dans les métadonnées : sans l’ID de clic, Dub ne peut pas attribuer les revenus à vos liens
Utilisez les ID externes de manière cohérente : transmettez le même ID client que celui utilisé dans votre système pour obtenir des analyses précises au niveau du client
Gérez correctement le trafic organique : définissez webhook.cancel = true lorsqu’il n’y a pas d’ID de clic afin d’éviter les appels API inutiles
Testez avec des paiements d’exemple : vérifiez que l’intégration fonctionne correctement avant sa mise en production
Surveillez votre tableau de bord Dub : vérifiez que les ventes apparaissent correctement avec une attribution appropriée

Remarques importantes

Format du montant : Dub attend les montants en centimes (par exemple, 10,00 $ = 1000)
Devise : utilisez les codes de devise ISO 4217 (USD, EUR, GBP, etc.)
Essais gratuits : les paiements de 0 $ ne sont pas suivis comme des ventes
Remboursements : envisagez de suivre les remboursements séparément si nécessaire pour garantir l’exactitude des rapports de revenus

Résolution des problèmes

Sales not appearing in Dub

Vérifiez que votre clé API Dub est correcte et dispose de l’étendue conversions.write
Vérifiez que dub_click_id est bien capturé et enregistré dans les métadonnées du paiement
Assurez-vous que la transformation du webhook formate correctement le payload
Vérifiez que le webhook se déclenche lors des événements payment.succeeded
Confirmez que le suivi des conversions est activé pour vos liens Dub

Revenue attribution not working

Confirmez que les utilisateurs cliquent sur vos liens courts Dub avant le paiement
Vérifiez que le cookie dub_id est correctement défini sur votre domaine
Vérifiez que les ID de clic correspondent entre la création du paiement et sa finalisation
Assurez-vous de capturer l’ID de clic avant de créer la session de paiement

Transformation errors

Validez que la structure JSON correspond au format de l’API Track Sale de Dub
Vérifiez que tous les champs obligatoires (clickId, externalId, amount) sont présents
Assurez-vous que le montant est exprimé en centimes (entier, et non décimal)
Vérifiez que l’URL de l’endpoint API est correcte : https://api.dub.co/track/sale
Testez la transformation avec des payloads webhook d’exemple

Duplicate sales being tracked

Assurez-vous de suivre uniquement les événements payment.succeeded, et non les événements payment.processing
Utilisez des valeurs invoiceId uniques pour chaque vente
Pour les abonnements, ajoutez des horodatages ou la période de facturation afin d’éviter les doublons lors des renouvellements

Ressources supplémentaires

Dub Conversions Documentation

Découvrez-en davantage sur les fonctionnalités de suivi des conversions et d’analyse de Dub.

Dub Track Sale API

Consultez la référence complète de l’API pour l’endpoint Track Sale de Dub.

Dub Dashboard

Accédez à votre tableau de bord Dub pour consulter les analyses de conversion et les données d’attribution.

Webhook Events Guide

Découvrez tous les événements webhook disponibles de Dodo Payments.

Besoin d’aide ? Contactez l’assistance de Dodo Payments à l’adresse support@dodopayments.com pour obtenir de l’aide concernant l’intégration.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Introduction

How It Works

Prerequisites

Getting Started

Implementation Guide

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

Étape 2 : Envoyer les données de vente à Dub

Exemples de code de transformation

Suivi des ventes de base

Suivi des ventes d’abonnements

Suivi des ventes hors taxes

Suivi des ventes avec des noms d’événements personnalisés

Alternative : implémentation côté client

Bonnes pratiques

Remarques importantes

Résolution des problèmes

Ressources supplémentaires

Dub Conversions Documentation

Dub Track Sale API

Dub Dashboard

Webhook Events Guide

​Introduction

​How It Works

​Prerequisites

​Getting Started

​Implementation Guide

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

​Étape 2 : Envoyer les données de vente à Dub

​Exemples de code de transformation

​Suivi des ventes de base

​Suivi des ventes d’abonnements

​Suivi des ventes hors taxes

​Suivi des ventes avec des noms d’événements personnalisés

​Alternative : implémentation côté client

​Bonnes pratiques

​Remarques importantes

​Résolution des problèmes

​Ressources supplémentaires

Dub Conversions Documentation

Dub Track Sale API

Dub Dashboard

Webhook Events Guide

Introduction

How It Works

Prerequisites

Getting Started

Implementation Guide

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

Étape 2 : Envoyer les données de vente à Dub

Exemples de code de transformation

Suivi des ventes de base

Suivi des ventes d’abonnements

Suivi des ventes hors taxes

Suivi des ventes avec des noms d’événements personnalisés

Alternative : implémentation côté client

Bonnes pratiques

Remarques importantes

Résolution des problèmes

Ressources supplémentaires