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.

Contoh-contoh di bawah menggunakan POST /payments, yang sudah deprecated. Ini masih berfungsi untuk integrasi yang sudah ada, tetapi integrasi baru sebaiknya menggunakan Checkout Sessions (POST /checkouts) — metadata diteruskan dengan cara yang sama.

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
}

Langkah 2: Kirim Data Penjualan ke Dub

Konfigurasikan endpoint webhook untuk mengirim data penjualan ke Track API milik Dub saat pembayaran berhasil.

Open the Webhook Section

Di dashboard Dodo Payments, buka Webhooks → + Add Endpoint, lalu buka dropdown integrasi.

Select Dub

Pilih kartu integrasi Dub.

Enter API Key

Masukkan Dub API Key Anda di kolom konfigurasi.

Configure Transformation

Edit kode transformasi untuk memformat data pembayaran untuk Track Sale API milik Dub.

Test & Create

Uji dengan payload contoh, lalu klik Create untuk mengaktifkan integrasi.

Contoh Kode Transformasi

Pelacakan Penjualan Dasar

Lacak penjualan saat pembayaran berhasil:

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

Lacak Penjualan Subscription

Lacak subscription awal dan pembayaran berulang:

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

Lacak Penjualan Tanpa Pajak

Kirim hanya jumlah sebelum pajak ke Dub untuk pelacakan pendapatan yang akurat:

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

Lacak Penjualan dengan Nama Event Kustom

Gunakan nama event kustom untuk mengategorikan berbagai jenis penjualan:

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

Alternatif: Implementasi Client-Side

Jika Anda lebih suka melacak penjualan dari server, bukan menggunakan webhook, Anda dapat memanggil Track API milik Dub secara langsung setelah pembayaran berhasil:

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

Praktik Terbaik

Tangkap click ID lebih awal: Simpan click ID Dub sesegera mungkin dalam alur checkout Anda untuk memastikan atribusi yang akurat, meskipun pengguna meninggalkan halaman dan kembali nanti.

Selalu sertakan click ID dalam metadata: Tanpa click ID, Dub tidak dapat mengatribusikan pendapatan ke link Anda
Gunakan external ID secara konsisten: Teruskan customer ID yang sama dengan yang Anda gunakan di sistem untuk analitik tingkat pelanggan yang akurat
Tangani traffic organik dengan baik: Tetapkan webhook.cancel = true jika tidak ada click ID untuk menghindari panggilan API yang tidak perlu
Uji dengan pembayaran contoh: Pastikan integrasi berfungsi dengan benar sebelum digunakan di production
Pantau dashboard Dub Anda: Periksa apakah penjualan muncul dengan benar dan atribusinya sesuai

Catatan Penting

Format jumlah: Dub mengharapkan jumlah dalam satuan sen (misalnya, $10.00 = 1000)
Mata uang: Gunakan kode mata uang ISO 4217 (USD, EUR, GBP, dan lainnya)
Free trial: Pembayaran $0 tidak dilacak sebagai penjualan
Refund: Pertimbangkan untuk melacak refund secara terpisah jika diperlukan agar pelaporan pendapatan akurat

Pemecahan Masalah

Sales not appearing in Dub

Pastikan Dub API key Anda benar dan memiliki scope conversions.write
Periksa apakah dub_click_id ditangkap dan disimpan dalam metadata pembayaran
Pastikan transformasi webhook memformat payload dengan benar
Pastikan webhook terpicu pada event payment.succeeded
Pastikan pelacakan konversi diaktifkan untuk link Dub Anda

Revenue attribution not working

Pastikan pengguna mengeklik short link Dub Anda sebelum checkout
Pastikan cookie dub_id ditetapkan dengan benar di domain Anda
Periksa apakah click ID sama antara pembuatan checkout dan penyelesaian pembayaran
Pastikan Anda menangkap click ID sebelum membuat checkout session

Transformation errors

Validasi bahwa struktur JSON sesuai dengan format Track Sale API milik Dub
Periksa apakah semua field yang diperlukan (clickId, externalId, amount) tersedia
Pastikan jumlah dinyatakan dalam satuan sen (integer, bukan desimal)
Pastikan URL endpoint API sudah benar: https://api.dub.co/track/sale
Uji transformasi dengan payload webhook contoh

Duplicate sales being tracked

Pastikan Anda hanya melacak pada event payment.succeeded, bukan payment.processing
Gunakan nilai invoiceId yang unik untuk setiap penjualan
Untuk subscription, tambahkan timestamp atau periode penagihan agar tidak terjadi duplikasi saat perpanjangan

Sumber Daya Tambahan

Dub Conversions Documentation

Pelajari lebih lanjut tentang fitur pelacakan konversi dan analitik Dub.

Dub Track Sale API

Lihat referensi API lengkap untuk endpoint Track Sale Dub.

Dub Dashboard

Akses dashboard Dub Anda untuk melihat analitik konversi dan data atribusi.

Webhook Events Guide

Pelajari semua event webhook Dodo Payments yang tersedia.

Butuh bantuan? Hubungi dukungan Dodo Payments di support@dodopayments.com untuk mendapatkan bantuan terkait integrasi.

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

Langkah 2: Kirim Data Penjualan ke Dub

Contoh Kode Transformasi

Pelacakan Penjualan Dasar

Lacak Penjualan Subscription

Lacak Penjualan Tanpa Pajak

Lacak Penjualan dengan Nama Event Kustom

Alternatif: Implementasi Client-Side

Praktik Terbaik

Catatan Penting

Pemecahan Masalah

Sumber Daya Tambahan

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

​Langkah 2: Kirim Data Penjualan ke Dub

​Contoh Kode Transformasi

​Pelacakan Penjualan Dasar

​Lacak Penjualan Subscription

​Lacak Penjualan Tanpa Pajak

​Lacak Penjualan dengan Nama Event Kustom

​Alternatif: Implementasi Client-Side

​Praktik Terbaik

​Catatan Penting

​Pemecahan Masalah

​Sumber Daya Tambahan

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

Langkah 2: Kirim Data Penjualan ke Dub

Contoh Kode Transformasi

Pelacakan Penjualan Dasar

Lacak Penjualan Subscription

Lacak Penjualan Tanpa Pajak

Lacak Penjualan dengan Nama Event Kustom

Alternatif: Implementasi Client-Side

Praktik Terbaik

Catatan Penting

Pemecahan Masalah

Sumber Daya Tambahan