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.

Los ejemplos a continuación utilizan POST /payments, que está obsoleto. Sigue funcionando para integraciones existentes, pero las nuevas integraciones deben usar Checkout Sessions (POST /checkouts); metadata se envía de la misma manera.

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
}

Paso 2: Envía los datos de ventas a Dub

Configura un endpoint de webhook para enviar los datos de ventas a la Track API de Dub cuando los pagos se realicen correctamente.

Open the Webhook Section

En tu panel de Dodo Payments, ve a Webhooks → + Add Endpoint y expande el menú desplegable de integraciones.

Select Dub

Selecciona la tarjeta de integración de Dub.

Enter API Key

Introduce tu clave de API de Dub en el campo de configuración.

Configure Transformation

Edita el código de transformación para dar formato a los datos de pago para la Track Sale API de Dub.

Test & Create

Realiza pruebas con payloads de ejemplo y haz clic en Create para activar la integración.

Ejemplos de código de transformación

Seguimiento básico de ventas

Registra las ventas cuando los pagos se realicen correctamente:

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

Seguimiento de ventas de suscripciones

Registra tanto las suscripciones iniciales como los pagos recurrentes:

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

Seguimiento de ventas sin impuestos

Envía a Dub únicamente el importe antes de impuestos para realizar un seguimiento preciso de los ingresos:

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

Seguimiento de ventas con nombres de eventos personalizados

Usa nombres de eventos personalizados para categorizar distintos tipos de ventas:

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

Alternativa: implementación del lado del cliente

Si prefieres realizar el seguimiento de las ventas desde tu servidor en lugar de usar webhooks, puedes llamar directamente a la Track API de Dub después de un pago exitoso:

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

Prácticas recomendadas

Captura el ID de clic con antelación: Almacena el ID de clic de Dub lo antes posible en tu flujo de checkout para garantizar una atribución precisa, incluso si el usuario abandona la página y regresa más tarde.

Incluye siempre el ID de clic en los metadatos: Sin el ID de clic, Dub no puede atribuir los ingresos a tus enlaces
Usa los ID externos de forma coherente: Pasa el mismo ID de cliente que utilizas en tu sistema para obtener análisis precisos a nivel de cliente
Gestiona correctamente el tráfico orgánico: Establece webhook.cancel = true cuando no haya un ID de clic para evitar llamadas API innecesarias
Realiza pruebas con pagos de ejemplo: Verifica que la integración funcione correctamente antes de ponerla en producción
Supervisa tu panel de Dub: Comprueba que las ventas aparezcan correctamente con la atribución adecuada

Notas importantes

Formato del importe: Dub espera los importes en centavos (por ejemplo, $10.00 = 1000)
Moneda: Usa códigos de moneda ISO 4217 (USD, EUR, GBP, etc.)
Pruebas gratuitas: Los pagos de $0 no se registran como ventas
Reembolsos: Considera realizar un seguimiento de los reembolsos por separado si es necesario para informar los ingresos con precisión

Solución de problemas

Sales not appearing in Dub

Verifica que tu clave de API de Dub sea correcta y tenga el alcance conversions.write
Comprueba que dub_click_id se capture y almacene en los metadatos del pago
Asegúrate de que la transformación del webhook dé el formato correcto al payload
Verifica que el webhook se active en eventos payment.succeeded
Confirma que el seguimiento de conversiones esté habilitado para tus enlaces de Dub

Revenue attribution not working

Confirma que los usuarios hagan clic en tus enlaces cortos de Dub antes del checkout
Verifica que la cookie dub_id se establezca correctamente en tu dominio
Comprueba que los ID de clic coincidan entre la creación del checkout y la finalización del pago
Asegúrate de capturar el ID de clic antes de crear la sesión de checkout

Transformation errors

Valida que la estructura JSON coincida con el formato de la Track Sale API de Dub
Comprueba que todos los campos obligatorios (clickId, externalId, amount) estén presentes
Asegúrate de que el importe esté expresado en centavos (entero, no decimal)
Verifica que la URL del endpoint de API sea correcta: https://api.dub.co/track/sale
Prueba la transformación con payloads de webhook de ejemplo

Duplicate sales being tracked

Asegúrate de realizar el seguimiento únicamente en eventos payment.succeeded, no en payment.processing
Usa valores invoiceId únicos para cada venta
Para las suscripciones, añade marcas de tiempo o el período de facturación para evitar duplicados en las renovaciones

Recursos adicionales

Dub Conversions Documentation

Obtén más información sobre las funciones de seguimiento de conversiones y análisis de Dub.

Dub Track Sale API

Consulta la referencia completa de la API para el endpoint Track Sale de Dub.

Dub Dashboard

Accede a tu panel de Dub para consultar los análisis de conversiones y los datos de atribución.

Webhook Events Guide

Obtén información sobre todos los eventos de webhook disponibles de Dodo Payments.

¿Necesitas ayuda? Contacta con el equipo de soporte de Dodo Payments en support@dodopayments.com para obtener ayuda con la integración.

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

Paso 2: Envía los datos de ventas a Dub

Ejemplos de código de transformación

Seguimiento básico de ventas

Seguimiento de ventas de suscripciones

Seguimiento de ventas sin impuestos

Seguimiento de ventas con nombres de eventos personalizados

Alternativa: implementación del lado del cliente

Prácticas recomendadas

Notas importantes

Solución de problemas

Recursos adicionales

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

​Paso 2: Envía los datos de ventas a Dub

​Ejemplos de código de transformación

​Seguimiento básico de ventas

​Seguimiento de ventas de suscripciones

​Seguimiento de ventas sin impuestos

​Seguimiento de ventas con nombres de eventos personalizados

​Alternativa: implementación del lado del cliente

​Prácticas recomendadas

​Notas importantes

​Solución de problemas

​Recursos adicionales

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

Paso 2: Envía los datos de ventas a Dub

Ejemplos de código de transformación

Seguimiento básico de ventas

Seguimiento de ventas de suscripciones

Seguimiento de ventas sin impuestos

Seguimiento de ventas con nombres de eventos personalizados

Alternativa: implementación del lado del cliente

Prácticas recomendadas

Notas importantes

Solución de problemas

Recursos adicionales