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.

Exemplen nedan använder POST /payments, som är föråldrad. Den fungerar fortfarande för befintliga integrationer, men nya integrationer bör använda Checkout Sessions (POST /checkouts) — metadata skickas på samma sätt.

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
}

Steg 2: Skicka försäljningsdata till Dub

Konfigurera en webhook-endpoint för att skicka försäljningsdata till Dubs Track API när betalningar lyckas.

Open the Webhook Section

Gå till Webhooks → + Add Endpoint i din Dodo Payments-dashboard och expandera rullgardinsmenyn för integrationer.

Select Dub

Välj integrationskortet Dub.

Enter API Key

Ange din Dub API Key i konfigurationsfältet.

Configure Transformation

Redigera transformationskoden för att formatera betalningsdata för Dubs Track Sale API.

Test & Create

Testa med exempelnyttolaster och klicka på Create för att aktivera integrationen.

Exempel på transformationskod

Grundläggande spårning av försäljning

Spåra försäljningar när betalningar lyckas:

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

Spåra prenumerationsförsäljningar

Spåra både initiala prenumerationer och återkommande betalningar:

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

Spåra försäljningar utan skatt

Skicka endast beloppet före skatt till Dub för korrekt intäktsspårning:

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

Spåra försäljningar med anpassade händelsenamn

Använd anpassade händelsenamn för att kategorisera olika typer av försäljningar:

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

Alternativ: implementering på klientsidan

Om du föredrar att spåra försäljningar från din server i stället för att använda webhooks kan du anropa Dubs Track API direkt efter en lyckad betalning:

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

Bästa praxis

Samla in klick-ID:t tidigt: Spara Dub-klick-ID:t så tidigt som möjligt i ditt checkout-flöde för att säkerställa korrekt attribuering, även om användaren lämnar sidan och återkommer senare.

Inkludera alltid klick-ID:t i metadata: Utan klick-ID:t kan Dub inte attribuera intäkter till dina länkar
Använd externa ID:n konsekvent: Skicka samma kund-ID som du använder i ditt system för korrekt analys på kundnivå
Hantera organisk trafik på ett smidigt sätt: Ange webhook.cancel = true när det inte finns något klick-ID för att undvika onödiga API-anrop
Testa med exempelbetalningar: Kontrollera att integrationen fungerar korrekt innan den tas i drift
Övervaka din Dub-dashboard: Kontrollera att försäljningar visas korrekt med rätt attribuering

Viktiga anmärkningar

Beloppsformat: Dub förväntar sig belopp i cent (t.ex. $10.00 = 1000)
Valuta: Använd ISO 4217-valutakoder (USD, EUR, GBP osv.)
Gratis provperioder: Betalningar på $0 spåras inte som försäljningar
Återbetalningar: Överväg att spåra återbetalningar separat om det behövs för korrekt intäktsrapportering

Felsökning

Sales not appearing in Dub

Kontrollera att din Dub API key är korrekt och har conversions.write-behörighet
Kontrollera att dub_click_id samlas in och lagras i betalningsmetadata
Säkerställ att webhook-transformationen formaterar nyttolasten korrekt
Kontrollera att webhooken utlöses vid payment.succeeded-händelser
Bekräfta att konverteringsspårning är aktiverad för dina Dub-länkar

Revenue attribution not working

Bekräfta att användare klickar på dina korta Dub-länkar före checkout
Kontrollera att dub_id-cookien anges korrekt på din domän
Kontrollera att klick-ID:n överensstämmer mellan skapandet av checkout och slutförandet av betalningen
Säkerställ att du samlar in klick-ID:t innan checkout-sessionen skapas

Transformation errors

Validera att JSON-strukturen överensstämmer med formatet för Dubs Track Sale API
Kontrollera att alla obligatoriska fält (clickId, externalId, amount) finns
Säkerställ att beloppet anges i cent (heltal, inte decimaltal)
Kontrollera att API-endpointens URL är korrekt: https://api.dub.co/track/sale
Testa transformationen med exempelnyttolaster från webhooken

Duplicate sales being tracked

Säkerställ att du endast spårar vid payment.succeeded-händelser, inte payment.processing
Använd unika invoiceId-värden för varje försäljning
För prenumerationer kan du lägga till tidsstämplar eller faktureringsperioder för att förhindra dubbletter vid förnyelser

Ytterligare resurser

Dub Conversions Documentation

Läs mer om Dubs funktioner för konverteringsspårning och analys.

Dub Track Sale API

Se den fullständiga API-referensen för Dubs Track Sale-endpoint.

Dub Dashboard

Öppna din Dub-dashboard för att se konverteringsanalys och attribueringsdata.

Webhook Events Guide

Läs mer om alla tillgängliga Dodo Payments webhook-händelser.

Behöver du hjälp? Kontakta Dodo Payments support på support@dodopayments.com för hjälp med integrationen.

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

Steg 2: Skicka försäljningsdata till Dub

Exempel på transformationskod

Grundläggande spårning av försäljning

Spåra prenumerationsförsäljningar

Spåra försäljningar utan skatt

Spåra försäljningar med anpassade händelsenamn

Alternativ: implementering på klientsidan

Bästa praxis

Viktiga anmärkningar

Felsökning

Ytterligare resurser

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

​Steg 2: Skicka försäljningsdata till Dub

​Exempel på transformationskod

​Grundläggande spårning av försäljning

​Spåra prenumerationsförsäljningar

​Spåra försäljningar utan skatt

​Spåra försäljningar med anpassade händelsenamn

​Alternativ: implementering på klientsidan

​Bästa praxis

​Viktiga anmärkningar

​Felsökning

​Ytterligare resurser

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

Steg 2: Skicka försäljningsdata till Dub

Exempel på transformationskod

Grundläggande spårning av försäljning

Spåra prenumerationsförsäljningar

Spåra försäljningar utan skatt

Spåra försäljningar med anpassade händelsenamn

Alternativ: implementering på klientsidan

Bästa praxis

Viktiga anmärkningar

Felsökning

Ytterligare resurser