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.

Die folgenden Beispiele verwenden POST /payments, das veraltet ist. Es funktioniert weiterhin für bestehende Integrationen, aber neue Integrationen sollten Checkout Sessions (POST /checkouts) verwenden — metadata wird auf dieselbe Weise übergeben.

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
}

Schritt 2: Verkaufsdaten an Dub senden

Konfigurieren Sie einen Webhook-Endpunkt, um Verkaufsdaten an die Track API von Dub zu senden, wenn Zahlungen erfolgreich sind.

Open the Webhook Section

Navigieren Sie in Ihrem Dodo Payments-Dashboard zu Webhooks → + Add Endpoint und erweitern Sie das Integrations-Dropdown.

Select Dub

Wählen Sie die Dub-Integrationskarte aus.

Enter API Key

Geben Sie Ihren Dub API Key im Konfigurationsfeld ein.

Configure Transformation

Bearbeiten Sie den Transformationscode, um Zahlungsdaten für die Track Sale API von Dub zu formatieren.

Test & Create

Testen Sie die Integration mit Beispiel-Payloads und klicken Sie auf Create, um sie zu aktivieren.

Beispiele für Transformationscode

Grundlegendes Verkaufs-Tracking

Verfolgen Sie Verkäufe, wenn Zahlungen erfolgreich sind:

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

Abonnementverkäufe verfolgen

Verfolgen Sie sowohl erste Abonnements als auch wiederkehrende Zahlungen:

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

Verkäufe ohne Steuern verfolgen

Senden Sie nur den Betrag vor Steuern an Dub, um den Umsatz genau zu verfolgen:

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

Verkäufe mit benutzerdefinierten Ereignisnamen verfolgen

Verwenden Sie benutzerdefinierte Ereignisnamen, um verschiedene Verkaufsarten zu kategorisieren:

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: clientseitige Implementierung

Wenn Sie Verkäufe lieber von Ihrem Server aus verfolgen möchten, anstatt Webhooks zu verwenden, können Sie die Track API von Dub nach einer erfolgreichen Zahlung direkt aufrufen:

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

Best Practices

Click ID frühzeitig erfassen: Speichern Sie die Dub Click ID so früh wie möglich in Ihrem Checkout-Ablauf, um eine genaue Attribution sicherzustellen, selbst wenn der Benutzer die Seite verlässt und später zurückkehrt.

Click ID immer in Metadaten aufnehmen: Ohne die Click ID kann Dub Umsätze nicht Ihren Links zuordnen
Externe IDs einheitlich verwenden: Übergeben Sie dieselbe Kunden-ID, die Sie in Ihrem System verwenden, um genaue Analysen auf Kundenebene zu ermöglichen
Organischen Traffic angemessen verarbeiten: Setzen Sie webhook.cancel = true, wenn keine Click ID vorhanden ist, um unnötige API-Aufrufe zu vermeiden
Mit Beispielzahlungen testen: Überprüfen Sie vor dem Livegang, dass die Integration ordnungsgemäß funktioniert
Ihr Dub-Dashboard überwachen: Prüfen Sie, ob Verkäufe korrekt und mit der richtigen Attribution angezeigt werden

Wichtige Hinweise

Betragsformat: Dub erwartet Beträge in Cent (z. B. $10.00 = 1000)
Währung: Verwenden Sie ISO-4217-Währungscodes (USD, EUR, GBP usw.)
Kostenlose Testzeiträume: Zahlungen über $0 werden nicht als Verkäufe erfasst
Rückerstattungen: Erwägen Sie, Rückerstattungen separat zu erfassen, falls dies für eine genaue Umsatzberichterstattung erforderlich ist

Fehlerbehebung

Sales not appearing in Dub

Überprüfen Sie, ob Ihr Dub API key korrekt ist und über den conversions.write-Scope verfügt
Prüfen Sie, ob die dub_click_id erfasst und in den Zahlungsmetadaten gespeichert wird
Stellen Sie sicher, dass die Webhook-Transformation den Payload korrekt formatiert
Überprüfen Sie, ob der Webhook bei payment.succeeded-Ereignissen ausgelöst wird
Bestätigen Sie, dass Conversion-Tracking für Ihre Dub-Links aktiviert ist

Revenue attribution not working

Bestätigen Sie, dass Benutzer vor dem Checkout auf Ihre Dub-Kurzlinks klicken
Überprüfen Sie, ob das dub_id-Cookie auf Ihrer Domain korrekt gesetzt wird
Prüfen Sie, ob die Click IDs zwischen der Erstellung des Checkouts und dem Abschluss der Zahlung übereinstimmen
Stellen Sie sicher, dass Sie die Click ID erfassen, bevor Sie die Checkout Session erstellen

Transformation errors

Validieren Sie, dass die JSON-Struktur dem Format der Dub Track Sale API entspricht
Prüfen Sie, ob alle erforderlichen Felder (clickId, externalId, amount) vorhanden sind
Stellen Sie sicher, dass der Betrag in Cent angegeben ist (Ganzzahl, keine Dezimalzahl)
Überprüfen Sie, ob die URL des API-Endpunkts korrekt ist: https://api.dub.co/track/sale
Testen Sie die Transformation mit Beispiel-Webhook-Payloads

Duplicate sales being tracked

Stellen Sie sicher, dass Sie nur bei payment.succeeded-Ereignissen und nicht bei payment.processing-Ereignissen tracken
Verwenden Sie für jeden Verkauf eindeutige invoiceId-Werte
Hängen Sie bei Abonnements Zeitstempel oder den Abrechnungszeitraum an, um Duplikate bei Verlängerungen zu vermeiden

Zusätzliche Ressourcen

Dub Conversions Documentation

Erfahren Sie mehr über die Conversion-Tracking- und Analysefunktionen von Dub.

Dub Track Sale API

Sehen Sie sich die vollständige API-Referenz für den Track Sale-Endpunkt von Dub an.

Dub Dashboard

Rufen Sie Ihr Dub-Dashboard auf, um Conversion-Analysen und Attributionsdaten einzusehen.

Webhook Events Guide

Erfahren Sie mehr über alle verfügbaren Dodo Payments-Webhook-Ereignisse.

Benötigen Sie Hilfe? Wenden Sie sich unter support@dodopayments.com an den Support von Dodo Payments, wenn Sie Unterstützung bei der Integration benötigen.

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

Schritt 2: Verkaufsdaten an Dub senden

Beispiele für Transformationscode

Grundlegendes Verkaufs-Tracking

Abonnementverkäufe verfolgen

Verkäufe ohne Steuern verfolgen

Verkäufe mit benutzerdefinierten Ereignisnamen verfolgen

Alternative: clientseitige Implementierung

Best Practices

Wichtige Hinweise

Fehlerbehebung

Zusätzliche Ressourcen

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

​Schritt 2: Verkaufsdaten an Dub senden

​Beispiele für Transformationscode

​Grundlegendes Verkaufs-Tracking

​Abonnementverkäufe verfolgen

​Verkäufe ohne Steuern verfolgen

​Verkäufe mit benutzerdefinierten Ereignisnamen verfolgen

​Alternative: clientseitige Implementierung

​Best Practices

​Wichtige Hinweise

​Fehlerbehebung

​Zusätzliche Ressourcen

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

Schritt 2: Verkaufsdaten an Dub senden

Beispiele für Transformationscode

Grundlegendes Verkaufs-Tracking

Abonnementverkäufe verfolgen

Verkäufe ohne Steuern verfolgen

Verkäufe mit benutzerdefinierten Ereignisnamen verfolgen

Alternative: clientseitige Implementierung

Best Practices

Wichtige Hinweise

Fehlerbehebung

Zusätzliche Ressourcen