Descuentos

Crea códigos promocionales para impulsar conversiones, ejecutar campañas y recompensar a los clientes con descuentos porcentuales en compras únicas y suscripciones.

Los códigos de descuento permiten ejecutar promociones e incentivos específicos. Cree descuentos basados en porcentajes, establezca límites y fechas de vencimiento, restrínjalos a productos y aplíquelos en el checkout.

Checkout Sessions

Aplica uno o más códigos apilados durante el pago alojado con discount_codes y controles de UI.

Get Discount

Recupera un descuento por su ID para consultar su estado y sus restricciones.

Get Discount by Code

Busca y valida un descuento usando su nombre de código (p. ej., “SAVE20”).

Create Discount (API)

Crea programáticamente nuevos códigos de descuento.

List & Update Discounts

Navega y administra descuentos existentes; actualiza o elimina según sea necesario.

​

¿Qué Son los Códigos de Descuento?

Los códigos de descuento son tokens promocionales que reducen los totales de pedidos en el proceso de pago. Son ideales para:

Los códigos de descuento son tokens promocionales que reducen los totales de los pedidos en el checkout. Úselos para campañas estacionales, incentivos para la primera compra, ofertas para recuperar clientes o precios B2B negociados.

Los códigos pueden basarse en porcentajes (por ejemplo, 15 % de descuento) o en importes fijos (por ejemplo, 5 $ de descuento). Puede combinar hasta 20 códigos por checkout, pago o suscripción, de modo que un cliente pueda canjear una oferta de bienvenida y un código de campaña en la misma transacción. Restrinja los códigos a productos específicos, limite cuántas veces puede usarlos cada cliente, establezca fechas de vencimiento y controle quiénes pueden canjearlos.

• Descuentos flexibles: Porcentaje o cantidad fija de descuento

• Control dirigido: Restringir por producto y ciclos de suscripción

• Gobernanza de campañas: Fechas de expiración y límites de uso

• Proceso de pago sin problemas: Soporte de campo de UI y API a través de sesiones de pago

• Descuentos flexibles: Descuentos basados en porcentajes o importes fijos

• Códigos combinables: Aplique hasta 20 códigos por checkout, pago o suscripción

• Control específico: Restrinja por producto, ciclos de suscripción y elegibilidad del cliente

• Gestión de campañas: Fechas de inicio programadas, fechas de vencimiento y límites de uso generales y por cliente

• Precios por moneda: Establezca la deducción fija, el límite del importe y el subtotal mínimo por moneda

Crea códigos de descuento en tu panel de Dodo Payments, luego aplícalos en el pago alojado o a través de la API.

​

Configuración del Panel

​

Configuración en el Dashboard

• Discount Name (obligatorio): Etiqueta interna para el dashboard.
• Code (obligatorio): La cadena que los clientes introducen durante el checkout. Genera un código aleatorio o introduce uno propio (mínimo 3 caracteres, convertido automáticamente a mayúsculas).
• Type (obligatorio): Percentage (un porcentaje de descuento) o Amount (una deducción fija).
• Amount (obligatorio): Para percentage, el porcentaje de descuento en el dashboard (por ejemplo, 15 para un 15 %). A través de la API, el mismo valor se expresa en puntos básicos (1500). Para amount, la deducción fija en la moneda predeterminada del código.
• Start Date (opcional): Programa el código para que se active en una fecha futura. Déjalo vacío para activarlo inmediatamente.
• Expiration Date (opcional): Fecha después de la cual el código ya no se puede canjear.
• Usage Limit (opcional, en Advanced): Número máximo total de canjes entre todos los clientes. Un carrito con varias suscripciones cuenta como un canje.
• Per-Customer Usage Limit (opcional, en Advanced): Número máximo de canjes por parte de un único cliente. Debe ser menor o igual que el límite de uso general cuando ambos estén definidos.
• Customer Eligibility (opcional): Restringe quién puede canjearlo: todos los clientes, clientes nuevos, clientes existentes o una lista seleccionada manualmente.
• Currency Options (opcional): El importe del descuento para cada moneda en la que vendas. Consulta Per-Currency Options.
• Product Restriction (opcional): Limita el código a productos específicos.
• Subscription Cycle Limit (opcional, en Advanced): Número de ciclos de facturación durante los que se aplica el descuento. Déjalo vacío para que sea indefinido.
• Preserve on Plan Change (opcional): Mantén el descuento activo cuando una suscripción cambie de plan (preserve_on_plan_change).
• Metadata (opcional): Añade pares clave-valor personalizados para el seguimiento interno.
• Require a minimum order value (opcional, en Advanced): Subtotal mínimo del carrito (por moneda) para que se aplique el código.

El formulario muestra un Summary actualizado del código que está creando en un panel lateral. Cambie a Preview para ver cómo aparece el descuento en el checkout:

Más abajo en el formulario: elegibilidad, restricciones y opciones avanzadas:

Usa límites de ciclos para precios introductorios en suscripciones (por ejemplo, “50% de descuento durante 3 meses”).

Un amount porcentual se expresa en puntos básicos a través de la API; 1500 significa un 15 %. Un amount fijo es un valor monetario y está denominado en las opciones de moneda del código.

​

Tipos de descuento

Tipo	Valor de la API	Comportamiento
Percentage	percentage	Reduce el precio en un porcentaje. Opcionalmente, se puede establecer un límite máximo de descuento por moneda.
Amount	flat	Deduce un importe fijo. La deducción se distribuye entre todo el carrito en lugar de aplicarse por artículo de línea.

Ambos tipos pueden combinarse en el mismo array discount_codes y se aplican en el orden del array.

​

Elegibilidad del cliente

Configura customer_eligibility para controlar quién puede canjear un código:

Valor	Quién puede canjearlo
any	Cualquier cliente. Esta es la opción predeterminada.
first_time	Clientes que no te han comprado anteriormente.
existing	Clientes que ya te han comprado anteriormente.
specific	Solo los clientes que añadas a la lista de permitidos del código.

Un código specific comienza con cero clientes elegibles y rechaza todos los canjes hasta que le añadas clientes. Añádelos en el dashboard o mediante la API de clientes de descuentos.

Combina la elegibilidad con el Límite de uso por cliente para limitar cuántas veces puede canjear el código cada cliente, independientemente del límite de uso general.

​

Opciones por moneda

Cuando vende en varias monedas, establezca el comportamiento por moneda para cada código. En Currency options, cada entrada especifica:

• Amount — para un descuento Amount, la deducción fija en esa moneda; para un descuento Percentage, el límite máximo de descuento. Se asigna a max_amount_possible en la API.
• Default — marque una moneda como predeterminada. Las monedas no configuradas se convierten desde esta moneda predeterminada.

Establezca el mínimo por moneda por separado en Require a minimum order value, dentro de Advanced:

• Minimum subtotal — el código se aplica únicamente cuando el carrito alcanza este subtotal en esa moneda. 0 significa que no hay un mínimo.

Los descuentos Amount requieren al menos una opción de moneda con un valor predeterminado resoluble, ya que una deducción fija no tiene sentido sin una moneda. Los descuentos Percentage no requieren opciones de moneda.

El subtotal mínimo siempre se calcula sobre los precios originales del carrito, no sobre el total resultante después de aplicar descuentos anteriores de la cadena. El orden de aplicación nunca cambia si se alcanza el mínimo.

En una suscripción, el mínimo se comprueba una sola vez considerando conjuntamente el producto y sus complementos. Por ejemplo, un producto de $0 con un complemento de $5 cumple un mínimo de $4. Un código de Amount (flat) se aplica únicamente al producto de la suscripción, no a sus complementos.

​

Experiencia de Checkout

Los clientes introducen los códigos de descuento en el campo de checkout. Los códigos válidos se aplican inmediatamente y los totales se actualizan.

En Checkout Sessions, pasa discount_codes (un array) para aplicar previamente uno o varios códigos. El campo de entrada del descuento se muestra de forma predeterminada. Define feature_flags.allow_discount_code como false para ocultarlo. Los códigos se aplican en el orden del array, hasta un máximo de 20.

​

Combinar códigos de descuento

Las sesiones de checkout, los pagos y las suscripciones aceptan hasta 20 códigos combinados mediante el array discount_codes. Los códigos se aplican en el orden del array: el primer código válido reduce el precio inicial, el siguiente reduce el precio ya descontado, y así sucesivamente. Cuando Purchasing Power Parity está habilitado, el precio inicial es el importe ajustado por PPP. La respuesta incluye discount_ids (en pagos/suscripciones) y discounts (información más detallada por descuento, incluida la posición y los ciclos de suscripción restantes).

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  discount_codes: ['WELCOME10', 'BLACKFRIDAY20'], // applied in this order
  customer: { email: '[e-mail]' },
  return_url: 'https://yoursite.com/return'
});

El campo singular discount_code está obsoleto, pero es totalmente compatible por motivos de compatibilidad con versiones anteriores. No se puede combinar con discount_codes en la misma solicitud. Migra a discount_codes (el formato de array) para aprovechar la combinación de códigos y una respuesta más detallada.

En un precio de suscripción con Card-Optional at Zero Price habilitado, una combinación de códigos que reduce el importe adeudado hoy hasta 0 también omite el requisito de tarjeta: el cliente completa el checkout sin un método de pago registrado, igual que con un precio nativo de 0.

​

Gestión mediante la API

Create discounts

Crea códigos de descuento mediante programación con el tipo y el importe.

API Reference

Consulta la API de creación de descuentos.

List and retrieve

Enumera todos los descuentos o recupera sus detalles para gestionarlos y auditarlos.

API Reference

Consulta las API de enumeración y recuperación.

Get discount by code

Busca un descuento mediante su código legible para humanos (por ejemplo, “SAVE20”) en lugar de usar el ID interno.

API Reference

Recupera un descuento por nombre de código.

Update discounts

Modifica la configuración del descuento, como el importe, la fecha de caducidad o las restricciones.

API Reference

Aprende a actualizar los detalles de un descuento.

Retrieve a discount

Obtén un descuento mediante su ID para consultar su estado, el número de usos y las restricciones antes de aplicarlo.

API Reference

Obtén un descuento por ID.

Delete discounts

Desactiva o elimina los descuentos que ya no sean necesarios.

API Reference

Elimina un descuento.

Manage the customer allow list

Para un descuento con customer_eligibility establecido como specific, gestiona los clientes que pueden canjearlo:

• GET /discounts/{discount_id}/customers — enumera los clientes asociados (paginados, hasta 100 por página).
• POST /discounts/{discount_id}/customers — asocia clientes mediante su ID. La llamada es idempotente y acepta hasta 1000 ID, que deben existir previamente en tu negocio. La respuesta solo devuelve los ID enviados en esa solicitud, por lo que debes enumerar el endpoint para leer la lista de permitidos completa.
• DELETE /discounts/{discount_id}/customers/{customer_id} — desvincula un único cliente.

​

Casos de uso habituales

• Ofertas de introducción: Promociones de lanzamiento por tiempo limitado para productos nuevos
• Volumen o B2B: Descuentos contratados para conjuntos de productos seleccionados
• Estrategias de retención: Códigos para recuperar clientes en flujos de prevención de cancelaciones
• Campañas de temporada: Promociones basadas en festividades o eventos

​

Ejemplos de integración

​

Crear un descuento con metadata

Añade pares clave-valor personalizados para el seguimiento interno.

const discount = await client.discounts.create({
  type: 'percentage',
  amount: 1500, // 15%
  code: 'SUMMER2025',
  metadata: {
    campaign: 'summer_promo',
    source: 'email_blast'
  }
});

Usa metadata para etiquetar descuentos por campaña, origen o ID de referencia interno, de modo que puedas conciliar el uso y medir el ROI posteriormente.

​

Aplicar descuentos en Checkout Sessions

Aplica previamente uno o varios descuentos combinados y muestra la interfaz de entrada del código.

const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'pdt_abc', quantity: 1 }
  ],
  discount_codes: ['BLACKFRIDAY2024', 'NEWUSER5'], // stacked in array order
  customer: { email: '[e-mail]', name: 'Jane Doe' },
  return_url: 'https://yoursite.com/return'
});

​

Aplicar descuentos durante los cambios de plan

Ofrece precios promocionales cuando los clientes mejoren o reduzcan su plan de suscripción.

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  discount_codes: ['UPGRADE20']
});

El parámetro discount_codes controla cómo se gestionan los descuentos:

Valor	Comportamiento
No proporcionado (undefined / null)	Los descuentos existentes con preserve_on_plan_change=true se conservan si se aplican al nuevo producto.
[] (array vacío)	Se eliminan todos los descuentos existentes.
['CODE_A', 'CODE_B', ...]	Sustituye los descuentos existentes por este conjunto combinado, aplicado en el orden del array.

Lee todos los descuentos aplicados desde el array discounts de la suscripción en la respuesta. Cada entrada incluye discount_id, position, cycles_remaining y el código original.

​

Ocultar el campo de código de descuento

La entrada del descuento se muestra de forma predeterminada. Define allow_discount_code como false para ocultarla.

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  feature_flags: {
    allow_discount_code: false
  },
  return_url: 'https://yoursite.com/return'
});

​

Prácticas recomendadas

• Nombra claramente: Usa códigos reconocibles que coincidan con los nombres de las campañas.
• Limita el periodo: Añade fechas de caducidad para generar urgencia y evitar usos indebidos.
• Define el alcance con criterio: Limita los descuentos a productos específicos para evitar pérdidas de margen.
• Valida con antelación: Comprueba la aplicabilidad del código antes de confirmar el checkout.
• Supervisa el impacto: Haz un seguimiento del uso y la conversión por campaña.