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.

Các ví dụ dưới đây sử dụng POST /payments, hiện đã deprecated. Tính năng này vẫn hoạt động với các integration hiện có, nhưng các integration mới nên sử dụng Checkout Sessions (POST /checkouts) — metadata được truyền theo cùng cách.

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
}

Bước 2: Gửi dữ liệu giao dịch đến Dub

Cấu hình một webhook endpoint để gửi dữ liệu giao dịch đến Track API của Dub khi thanh toán thành công.

Open the Webhook Section

Trong dashboard Dodo Payments, điều hướng đến Webhooks → + Add Endpoint và mở rộng danh sách thả xuống integrations.

Select Dub

Chọn integration card Dub.

Enter API Key

Nhập Dub API Key vào trường cấu hình.

Configure Transformation

Chỉnh sửa transformation code để định dạng dữ liệu thanh toán cho Track Sale API của Dub.

Test & Create

Kiểm tra bằng sample payload và nhấp Create để kích hoạt integration.

Ví dụ về Transformation Code

Theo dõi giao dịch cơ bản

Theo dõi các giao dịch khi thanh toán thành công:

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

Theo dõi giao dịch Subscription

Theo dõi cả subscription ban đầu và các khoản thanh toán định kỳ:

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

Theo dõi giao dịch không bao gồm thuế

Chỉ gửi số tiền trước thuế đến Dub để theo dõi doanh thu chính xác:

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

Theo dõi giao dịch với tên Event tùy chỉnh

Sử dụng tên event tùy chỉnh để phân loại các loại giao dịch khác nhau:

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

Phương án thay thế: Triển khai phía Client

Nếu muốn theo dõi giao dịch từ server thay vì sử dụng webhook, bạn có thể gọi trực tiếp Track API của Dub sau khi thanh toán thành công:

'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

Thu thập click ID sớm: Lưu Dub click ID sớm nhất có thể trong quy trình checkout để đảm bảo attribution chính xác, ngay cả khi người dùng rời đi và quay lại sau.

Luôn include click ID trong metadata: Nếu không có click ID, Dub không thể xác định doanh thu đến từ các link của bạn
Sử dụng external ID nhất quán: Truyền cùng customer ID mà bạn sử dụng trong hệ thống để có analytics chính xác ở cấp độ customer
Xử lý organic traffic phù hợp: Set webhook.cancel = true khi không có click ID để tránh các API call không cần thiết
Kiểm tra bằng sample payment: Xác minh integration hoạt động chính xác trước khi go live
Theo dõi dashboard Dub: Kiểm tra để đảm bảo các giao dịch xuất hiện chính xác với attribution phù hợp

Lưu ý quan trọng

Định dạng amount: Dub yêu cầu amount tính bằng cents (ví dụ: $10.00 = 1000)
Currency: Sử dụng mã currency ISO 4217 (USD, EUR, GBP, v.v.)
Free trial: Các khoản thanh toán $0 không được theo dõi là giao dịch
Refund: Nếu cần, hãy cân nhắc theo dõi refund riêng để báo cáo doanh thu chính xác

Khắc phục sự cố

Sales not appearing in Dub

Xác minh Dub API key chính xác và có scope conversions.write
Kiểm tra dub_click_id đã được capture và lưu trong payment metadata
Đảm bảo webhook transformation định dạng payload chính xác
Xác minh webhook được trigger bởi các event payment.succeeded
Xác nhận conversion tracking đã được bật cho các link Dub

Revenue attribution not working

Xác nhận người dùng nhấp qua short link Dub trước khi checkout
Xác minh cookie dub_id được set chính xác trên domain của bạn
Kiểm tra click ID khớp nhau giữa lúc tạo checkout và hoàn tất thanh toán
Đảm bảo bạn capture click ID trước khi tạo checkout session

Transformation errors

Xác thực cấu trúc JSON khớp với format của Track Sale API của Dub
Kiểm tra tất cả các field bắt buộc (clickId, externalId, amount) đều có mặt
Đảm bảo amount tính bằng cents (integer, không phải decimal)
Xác minh URL API endpoint chính xác: https://api.dub.co/track/sale
Kiểm tra transformation bằng sample webhook payload

Duplicate sales being tracked

Đảm bảo bạn chỉ theo dõi các event payment.succeeded, không phải payment.processing
Sử dụng các giá trị invoiceId duy nhất cho mỗi giao dịch
Đối với subscription, thêm timestamp hoặc billing period để ngăn trùng lặp khi gia hạn

Tài nguyên bổ sung

Dub Conversions Documentation

Tìm hiểu thêm về các tính năng conversion tracking và analytics của Dub.

Dub Track Sale API

Xem tài liệu tham chiếu API đầy đủ cho Track Sale endpoint của Dub.

Dub Dashboard

Truy cập dashboard Dub để xem conversion analytics và dữ liệu attribution.

Webhook Events Guide

Tìm hiểu về tất cả webhook event hiện có của Dodo Payments.

Cần trợ giúp? Liên hệ bộ phận hỗ trợ của Dodo Payments qua support@dodopayments.com để được hỗ trợ về integration.

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

Bước 2: Gửi dữ liệu giao dịch đến Dub

Ví dụ về Transformation Code

Theo dõi giao dịch cơ bản

Theo dõi giao dịch Subscription

Theo dõi giao dịch không bao gồm thuế

Theo dõi giao dịch với tên Event tùy chỉnh

Phương án thay thế: Triển khai phía Client

Best Practices

Lưu ý quan trọng

Khắc phục sự cố

Tài nguyên bổ sung

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

​Bước 2: Gửi dữ liệu giao dịch đến Dub

​Ví dụ về Transformation Code

​Theo dõi giao dịch cơ bản

​Theo dõi giao dịch Subscription

​Theo dõi giao dịch không bao gồm thuế

​Theo dõi giao dịch với tên Event tùy chỉnh

​Phương án thay thế: Triển khai phía Client

​Best Practices

​Lưu ý quan trọng

​Khắc phục sự cố

​Tài nguyên bổ sung

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

Bước 2: Gửi dữ liệu giao dịch đến Dub

Ví dụ về Transformation Code

Theo dõi giao dịch cơ bản

Theo dõi giao dịch Subscription

Theo dõi giao dịch không bao gồm thuế

Theo dõi giao dịch với tên Event tùy chỉnh

Phương án thay thế: Triển khai phía Client

Best Practices

Lưu ý quan trọng

Khắc phục sự cố

Tài nguyên bổ sung