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.

Gli esempi di seguito utilizzano POST /payments, che è deprecato. Funziona ancora per le integrazioni esistenti, ma per le nuove integrazioni è consigliato usare Checkout Sessions (POST /checkouts) — metadata viene passato nello stesso modo.

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
}

Passaggio 2: invia i dati delle vendite a Dub

Configura un endpoint webhook per inviare i dati delle vendite all’API Track di Dub quando i pagamenti vanno a buon fine.

Open the Webhook Section

Nella dashboard di Dodo Payments, vai a Webhooks → + Add Endpoint ed espandi il menu a discesa delle integrazioni.

Select Dub

Seleziona la scheda dell’integrazione Dub.

Enter API Key

Inserisci la tua chiave API di Dub nel campo di configurazione.

Configure Transformation

Modifica il codice di trasformazione per formattare i dati dei pagamenti per l’API Track Sale di Dub.

Test & Create

Esegui un test con payload di esempio e fai clic su Create per attivare l’integrazione.

Esempi di codice di trasformazione

Monitoraggio di base delle vendite

Monitora le vendite quando i pagamenti vanno a buon fine:

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

Monitoraggio delle vendite degli abbonamenti

Monitora sia gli abbonamenti iniziali sia i pagamenti ricorrenti:

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

Monitoraggio delle vendite con esclusione delle imposte

Invia a Dub solo l’importo al netto delle imposte per un monitoraggio accurato dei ricavi:

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

Monitoraggio delle vendite con nomi di eventi personalizzati

Utilizza nomi di eventi personalizzati per classificare diversi tipi di vendite:

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: implementazione lato client

Se preferisci monitorare le vendite dal tuo server invece di utilizzare i webhook, puoi chiamare direttamente l’API Track di Dub dopo un pagamento completato con successo:

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

Procedure consigliate

Acquisisci presto il click ID: salva il click ID di Dub il prima possibile nel flusso di checkout per garantire un’attribuzione accurata, anche se l’utente abbandona la pagina e torna in un secondo momento.

Includi sempre il click ID nei metadati: senza il click ID, Dub non può attribuire i ricavi ai tuoi link
Utilizza gli ID esterni in modo coerente: passa lo stesso ID cliente che utilizzi nel tuo sistema per ottenere analisi accurate a livello di cliente
Gestisci correttamente il traffico organico: imposta webhook.cancel = true quando non è presente alcun click ID, per evitare chiamate API non necessarie
Esegui test con pagamenti di esempio: verifica che l’integrazione funzioni correttamente prima di renderla operativa
Monitora la dashboard di Dub: verifica che le vendite vengano visualizzate correttamente con la giusta attribuzione

Note importanti

Formato dell’importo: Dub si aspetta gli importi in centesimi (ad es., $10.00 = 1000)
Valuta: utilizza i codici valuta ISO 4217 (USD, EUR, GBP, ecc.)
Prove gratuite: i pagamenti di $0 non vengono monitorati come vendite
Rimborsi: valuta la possibilità di monitorare separatamente i rimborsi, se necessario, per una rendicontazione accurata dei ricavi

Risoluzione dei problemi

Sales not appearing in Dub

Verifica che la chiave API di Dub sia corretta e disponga dell’ambito conversions.write
Verifica che dub_click_id venga acquisito e memorizzato nei metadati del pagamento
Assicurati che la trasformazione del webhook formatti correttamente il payload
Verifica che il webhook venga attivato sugli eventi payment.succeeded
Conferma che il monitoraggio delle conversioni sia abilitato per i tuoi link Dub

Revenue attribution not working

Conferma che gli utenti facciano clic sui tuoi short link Dub prima del checkout
Verifica che il cookie dub_id venga impostato correttamente sul tuo dominio
Verifica che i click ID coincidano tra la creazione del checkout e il completamento del pagamento
Assicurati di acquisire il click ID prima di creare la sessione di checkout

Transformation errors

Convalida che la struttura JSON corrisponda al formato dell’API Track Sale di Dub
Verifica che siano presenti tutti i campi obbligatori (clickId, externalId, amount)
Assicurati che l’importo sia espresso in centesimi (intero, non decimale)
Verifica che l’URL dell’endpoint API sia corretto: https://api.dub.co/track/sale
Testa la trasformazione con payload webhook di esempio

Duplicate sales being tracked

Assicurati di monitorare solo gli eventi payment.succeeded, non payment.processing
Utilizza valori invoiceId univoci per ogni vendita
Per gli abbonamenti, aggiungi timestamp o il periodo di fatturazione per evitare duplicati nei rinnovi

Risorse aggiuntive

Dub Conversions Documentation

Scopri di più sulle funzionalità di monitoraggio delle conversioni e analisi di Dub.

Dub Track Sale API

Consulta la documentazione API completa per l’endpoint Track Sale di Dub.

Dub Dashboard

Accedi alla dashboard di Dub per visualizzare i dati sulle analisi delle conversioni e sull’attribuzione.

Webhook Events Guide

Scopri tutti gli eventi webhook disponibili di Dodo Payments.

Hai bisogno di aiuto? Contatta il supporto di Dodo Payments all’indirizzo support@dodopayments.com per ricevere assistenza con l’integrazione.

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

Passaggio 2: invia i dati delle vendite a Dub

Esempi di codice di trasformazione

Monitoraggio di base delle vendite

Monitoraggio delle vendite degli abbonamenti

Monitoraggio delle vendite con esclusione delle imposte

Monitoraggio delle vendite con nomi di eventi personalizzati

Alternativa: implementazione lato client

Procedure consigliate

Note importanti

Risoluzione dei problemi

Risorse aggiuntive

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

​Passaggio 2: invia i dati delle vendite a Dub

​Esempi di codice di trasformazione

​Monitoraggio di base delle vendite

​Monitoraggio delle vendite degli abbonamenti

​Monitoraggio delle vendite con esclusione delle imposte

​Monitoraggio delle vendite con nomi di eventi personalizzati

​Alternativa: implementazione lato client

​Procedure consigliate

​Note importanti

​Risoluzione dei problemi

​Risorse aggiuntive

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

Passaggio 2: invia i dati delle vendite a Dub

Esempi di codice di trasformazione

Monitoraggio di base delle vendite

Monitoraggio delle vendite degli abbonamenti

Monitoraggio delle vendite con esclusione delle imposte

Monitoraggio delle vendite con nomi di eventi personalizzati

Alternativa: implementazione lato client

Procedure consigliate

Note importanti

Risoluzione dei problemi

Risorse aggiuntive