Introduction
Dub es una plataforma de atribución de enlaces para enlaces cortos, seguimiento de conversiones y programas de afiliados. Con esta integración, Dub registra un evento de conversión de venta cada vez que un cliente paga a través de Dodo Payments, para que puedas medir el rendimiento de tus campañas de marketing y programas de referidos. Dub registra una venta cuando un cliente:- Completa un pago único
- Se suscribe a un plan de pago
- Realiza un pago de suscripción recurrente
Esta integración requiere una cuenta de Dub con el seguimiento de conversiones habilitado en tus enlaces. El seguimiento de conversiones de Dub requiere un plan Business o superior.
How It Works
Cuando un visitante hace clic en uno de tus enlaces cortos de Dub, Dub almacena un ID de clic único en la cookiedub_id. Para atribuir las ventas a tus enlaces:
- Captura el ID de clic de Dub de la cookie
dub_idcuando crees el checkout. - Almacena el ID de clic en el
metadatadel pago, junto con el ID de tu cliente en tu sistema (el ID externo). - Envía la venta a Dub mediante su Track API cuando el pago se complete correctamente.
Prerequisites
Antes de configurar esta integración, necesitas:- Una cuenta de Dub con un workspace.
- El seguimiento de conversiones habilitado para tus enlaces.
- Una clave de API de Dub, que puedes crear en tu panel de Dub, en Settings → API Keys.
Getting Started
1
Enable Conversion Tracking in Dub
En tu panel de Dub, habilita el seguimiento de conversiones para los enlaces cuyas ventas quieras rastrear. Dub registrará eventos de venta de los clientes que lleguen a través de esos enlaces.
Para habilitar el seguimiento de conversiones, consulta la documentación de Dub.
2
Get Your Dub API Key
En tu panel de Dub, ve a Settings → API Keys y crea una clave de API con el alcance
conversions.write.3
Capture Click ID in Checkout
Cuando crees un checkout, lee el ID de clic de Dub de la cookie y añádelo al
metadata del pago. Consulta el paso 1.4
Send Sale Data via Webhook
Crea un endpoint de webhook que envíe cada venta a la Track API de Dub cuando un pago se complete correctamente. Consulta el paso 2.
5
Done
Los eventos de conversión de ventas aparecen en tu panel de analíticas de Dub, atribuidos a tus enlaces.
Implementation Guide
Step 1: Add Click ID and Customer ID to Checkout Metadata
Cuando crees un checkout, lee el ID de clic de Dub de la cookie e inclúyelo en elmetadata del pago, junto con el ID externo de tu cliente.
Los ejemplos siguientes usan
POST /payments, que está obsoleto. Sigue funcionando para integraciones existentes, pero las integraciones nuevas deben usar Checkout Sessions (POST /checkouts), que aceptan metadata de la misma manera.Paso 2: Envía los datos de ventas a Dub
Crea un endpoint de webhook que envíe los datos de la venta a la Track API de Dub cuando un pago se complete correctamente.1
Open the Webhook Section
En el dashboard de Dodo Payments, ve a Developer → Webhooks y haz clic en Add endpoint.

2
Select Dub
En Integration, selecciona Dub.co.
3
Enter API Key
En API key, pega tu clave de API de Dub. Dodo Payments la envía en el encabezado 
Authorization de cada entrega.
4
Check the URL and Events
Si Endpoint URL está vacío, introduce
https://api.dub.co/track/sale. En Subscribed events, selecciona los eventos que gestiona tu transformación, como payment.succeeded.5
Configure Transformation
En Transformation code, edita el handler para dar formato a los datos de pago para la API Track Sale de Dub. Empieza con los ejemplos.
6
Test & Create
En Test this code, haz clic en Simulate para ejecutar el handler con un payload de ejemplo. Después, haz clic en Create endpoint.
Ejemplos de código de transformación
Cada handler envía una venta a Dub solo cuandometadata tiene un ID de clic. Para el tráfico orgánico, sin ID de clic, establece webhook.cancel = true, por lo que no se envía ninguna solicitud a Dub; la entrega cancelada sigue apareciendo como exitosa en los logs del webhook.
El cuerpo de la solicitud sigue la API Track Sale de Dub: customerExternalId e amount son obligatorios, y paymentProcessor es custom, porque la lista de procesadores de pago de Dub no incluye un valor para Dodo Payments. Dub toma amount en la misma unidad que los importes de Dodo Payments: centavos para monedas con dos decimales y el entero completo para monedas sin decimales, como JPY. Los ejemplos pasan el importe sin cambios.
Seguimiento básico de ventas
Registra una venta cuando un pago se realiza correctamente:basic_sale.js
Seguimiento de ventas de suscripciones
Registra tanto las suscripciones iniciales como los pagos recurrentes. Usa este handler para las suscripciones en lugar de los handlers depayment.succeeded, no junto con ellos: cada pago de suscripción también activa payment.succeeded, por lo que gestionar ambos eventos registra cada venta dos veces. Consulta la guía de integración de suscripciones.
El handler lee el ID de clic de metadata de la suscripción, así que pasa los mismos metadatos cuando crees la suscripción. Para las renovaciones, invoiceId combina el ID de la suscripción con previous_billing_date, el inicio del periodo de facturación actual, por lo que una entrega reintentada reutiliza el mismo invoiceId.
subscription_sale.js
Seguimiento de ventas sin impuestos
Envía a Dub solo el importe antes de impuestos, para que los ingresos en Dub excluyan los impuestos:sale_without_tax.js
Seguimiento de ventas con nombres de eventos personalizados
Usa nombres de eventos personalizados para categorizar distintos tipos de ventas. El ejemplo lee un indicadoris_upgrade que estableces en metadata del pago:
custom_events.js
Alternativa: implementación del lado del cliente
Para realizar el seguimiento de ventas desde tu propio servidor en lugar de hacerlo mediante una transformación de webhook, llama directamente a la API Track de Dub después de un pago exitoso, por ejemplo, desde tu handler de webhookpayment.succeeded. El código utiliza tu clave de API de Dub, así que ejecútalo en tu servidor, nunca en el navegador.
Prácticas recomendadas
- Incluye el ID de clic en los metadatos: sin el ID de clic, Dub no puede atribuir los ingresos a tus enlaces.
- Usa los IDs externos de forma coherente: pasa siempre el mismo ID de cliente de tu sistema como
customerExternalIdpara obtener análisis precisos a nivel de cliente. - Gestiona el tráfico orgánico: establece
webhook.cancel = truecuando no haya un ID de clic para evitar llamadas innecesarias a la API. - Prueba con pagos de ejemplo: ejecuta el handler con Test this code y confirma que la integración funciona antes de ponerla en producción.
- Supervisa tu dashboard de Dub: comprueba que las ventas aparezcan con la atribución esperada.
Notas importantes
- Formato del importe: Dub espera los importes en centavos para monedas con dos decimales (por ejemplo, $10.00 es
1000) y el entero completo para monedas sin decimales, como JPY. - Moneda: usa códigos de moneda ISO 4217, como USD, EUR y GBP. Dub convierte cada venta a USD según el tipo de cambio más reciente.
- Pruebas gratuitas: la API Track Sale de Dub acepta un
amountde0, y los ejemplos no omiten los pagos de $0, por lo que cada pago de $0 llega a Dub como una venta. Para omitir los pagos de $0, establecewebhook.cancel = truecuandototal_amountsea0. - Reembolsos: si necesitas informes precisos de ingresos, realiza el seguimiento de los reembolsos por separado.
Solución de problemas
Sales Not Appearing in Dub
Sales Not Appearing in Dub
- Verifica que tu clave de API de Dub sea correcta y tenga el alcance
conversions.write. - Comprueba que
dub_click_idse capture y almacene en los metadatos del pago. - Comprueba que la transformación del webhook dé el formato correcto al payload.
- Verifica que el endpoint esté suscrito a
payment.succeeded. - Confirma que el seguimiento de conversiones esté habilitado para tus enlaces de Dub.
- Abre los intentos de entrega del endpoint en la pestaña Logs de Developer → Webhooks para ver la respuesta de Dub. Un pago sin ID de clic se cancela y aparece como exitoso.
Revenue Attribution Not Working
Revenue Attribution Not Working
- Confirma que los clientes hagan clic en tus enlaces cortos de Dub antes del checkout.
- Verifica que la cookie
dub_idesté establecida en tu dominio. - Comprueba que el ID de clic de los metadatos del pago coincida con el clic que realizó el cliente.
- Captura el ID de clic antes de crear el checkout.
Transformation Errors
Transformation Errors
- Comprueba que el payload coincida con el formato de la API Track Sale de Dub.
- Comprueba que los campos obligatorios,
customerExternalIdeamount, estén presentes y queclickIdesté establecido para la atribución. - Comprueba que el importe sea un entero en la unidad monetaria más pequeña, no un decimal.
- Verifica que la URL del endpoint sea
https://api.dub.co/track/sale. - Prueba la transformación con payloads de webhook de ejemplo.
Duplicate Sales Being Tracked
Duplicate Sales Being Tracked
- Registra las ventas solo en eventos
payment.succeeded, no enpayment.processing. - Usa un
invoiceIdúnico para cada venta. Dub registra solo una venta por cadainvoiceId. - Para las renovaciones, crea
invoiceIda partir del ID de la suscripción y del periodo de facturación, como se muestra en Seguimiento de ventas de suscripciones. Un valor que cambie en cada entrega, como la hora actual, registra una venta duplicada cuando se reintenta una entrega.
Recursos adicionales
Dub Conversions Documentation
Obtén más información sobre las funciones de seguimiento de conversiones y análisis de Dub.
Dub Track Sale API
Consulta la referencia completa de la API del endpoint Track Sale de Dub.
Dub Dashboard
Consulta los análisis de conversiones y los datos de atribución en tu dashboard de Dub.
Webhook Events Guide
Explora todos los eventos de webhook de Dodo Payments.
Para obtener ayuda con esta integración, contacta con el equipo de soporte de Dodo Payments en support@dodopayments.com.