> ## Documentation Index > Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt > Use this file to discover all available pages before exploring further. # Descuentos > Crea códigos promocionales para impulsar conversiones, ejecutar campañas y recompensar a los clientes con descuentos porcentuales en compras únicas y suscripciones. Portada de la descripción general de los códigos de descuento Los códigos de descuento te permiten ejecutar promociones e incentivos dirigidos. Crea descuentos basados en porcentajes, establece límites y expiraciones, restríngelos a productos y aplícalos de manera fluida en el checkout. Aplica uno o más códigos apilados durante el pago alojado con `discount_codes` y controles de UI. Comprueba si un descuento es válido según su ID. Busca y valida un descuento usando su nombre de código (p. ej., "SAVE20"). Crea programáticamente nuevos códigos de descuento. 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: * **Campañas estacionales**: Black Friday, lanzamientos de productos o aniversarios * **Ofertas de adquisición**: Incentivos para la primera compra o recompensas por referencias * **Retención**: Recompensas de recuperación o lealtad para clientes existentes * **Ofertas B2B**: Precios contratados o negociados a través de códigos privados ## Beneficios Clave * **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 * **Códigos acumulables**: Aplica hasta 20 códigos por checkout, pago o suscripción — combina campañas (por ejemplo, `WELCOME10` + `BLACKFRIDAY20`) sin crear códigos a medida * **Control dirigido**: Restringir por producto y ciclos de suscripción * **Gobernanza de campaña**: Fechas de expiración y límites de uso * **Checkout fluido**: Campo de UI y soporte API a través de sesiones de checkout 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 * **Nombre del Descuento** (requerido): Nombre interno y de visualización en el panel * **Código** (requerido): La cadena que los clientes ingresan en el pago * **Tipo y Monto** (requerido): Establece un valor de porcentaje o cantidad fija, o genera un código aleatorio usando el botón proporcionado * **Fecha de Expiración** (opcional): Fecha después de la cual el código se vuelve inválido * **Límite de Uso** (opcional): Máximo total de redenciones entre todos los clientes * **Restricción de Producto** (opcional): Limitar la aplicabilidad a productos seleccionados * **Límite de Ciclo de Suscripción** (opcional): Número de ciclos de facturación a los que se aplica el descuento * **Nombre del descuento** (requerido): Nombre de visualización interna y en el panel * **Código** (requerido): La cadena que los clientes ingresan en el checkout * **Tipo y cantidad** (requerido): Establece un valor porcentual (actualmente solo se admiten descuentos basados en porcentajes), o genera un código aleatorio usando el botón proporcionado * **Fecha de expiración** (opcional): Fecha después de la cual el código se vuelve inválido * **Límite de uso** (opcional): Máximo de redenciones totales de todos los clientes * **Restricción de productos** (opcional): Limita la aplicabilidad a productos seleccionados * **Límite de ciclos de suscripción** (opcional): Número de ciclos de facturación a los que se aplica el descuento * **Metadatos** (opcional): Adjunta pares de clave-valor personalizados para seguimiento interno o integraciones ## Experiencia de Pago 1. Los compradores ingresan el código en el campo de pago. 2. Se aplican los descuentos elegibles y los totales se actualizan de inmediato. En Checkout Sessions, pasa `discount_code` para preaplicar un código y configura `feature_flags.allow_discount_code` para mostrar el campo de entrada. En las sesiones de pago, pasa `discount_codes` (un array) para preaplicar uno o más códigos, y establece `feature_flags.allow_discount_code` para mostrar el campo de entrada. Los códigos se aplican en orden del array, hasta un máximo de 20. ## Apilamiento de Códigos de Descuento Las sesiones de pago, los pagos y las suscripciones aceptan hasta **20 códigos apilados** a través del array `discount_codes` (máximo 20 entradas). Los códigos se aplican **en orden del array**, por lo que el primer código elegible reduce primero el precio base, el siguiente código reduce el precio ya descontado, y así sucesivamente. El conjunto completo de descuentos aplicados se devuelve en la respuesta bajo `discount_ids` (en pagos/suscripciones) y `discounts` (detalle más rico por descuento, incluyendo posición y ciclos de suscripción restantes). ```typescript theme={null} const session = await client.checkoutSessions.create({ product_cart: [{ product_id: 'prod_abc', quantity: 1 }], discount_codes: ['WELCOME10', 'BLACKFRIDAY20'], // applied in this order customer: { email: 'user@example.com' }, return_url: 'https://yoursite.com/return' }); ``` El campo singular `discount_code` está **obsoleto** pero aún totalmente soportado para compatibilidad hacia atrás — las integraciones existentes continúan funcionando sin cambios. No se puede combinar con `discount_codes` en la misma solicitud. Recomendamos migrar a `discount_codes` (la forma de array) cuando sea conveniente, incluso para códigos individuales, para aprovechar el apilamiento y la forma de respuesta más rica. ## Gestión de API Crea códigos de descuento programáticamente con tipo y cantidad. Ve la API de creación de descuentos. Lista todos los descuentos o recupera detalles para gestión y auditoría. Explora APIs de listado y recuperación. Busca un descuento usando su código fácil de leer (por ejemplo, "SAVE20") en lugar del ID interno. Recupera descuentos por nombre de código. Modifica la configuración del descuento como cantidad, expiración o restricciones. Aprende cómo actualizar los detalles del descuento. Verifica si un descuento es válido y aplicable antes de aplicar. Valida el uso de descuentos. Desactiva o elimina descuentos que ya no se necesiten. Elimina un descuento. ## Casos de Uso Comunes * **Ofertas de introducción**: Promociones de lanzamiento por tiempo limitado para nuevos productos * **Al por mayor o B2B**: Descuentos contratados para conjuntos de productos selectos * **Juegos de retención**: Códigos de recuperación en flujos de trabajo de prevención de cancelación * **Campañas de temporada**: Promociones basadas en festividades o eventos ## Ejemplos de Integración ### Crea un descuento con metadatos Adjunta pares clave-valor personalizados para seguimiento interno. ```typescript theme={null} const discount = await client.discounts.create({ type: 'percentage', amount: 1500, // 15% code: 'SUMMER2025', metadata: { campaign: 'summer_promo', source: 'email_blast' } }); ``` Usa metadatos para etiquetar descuentos por campaña, fuente o ID de referencia interna para poder conciliar el uso y medir el ROI más tarde. ### Aplica descuentos en sesiones de checkout Preaplica uno o más descuentos apilados y muestra la UI de entrada de código. ```typescript theme={null} const session = await client.checkoutSessions.create({ product_cart: [ { product_id: 'prod_abc', quantity: 1 } ], discount_codes: ['BLACKFRIDAY2024', 'NEWUSER5'], // stacked in array order customer: { email: 'user@example.com', name: 'Jane Doe' }, return_url: 'https://yoursite.com/return' }); ``` ### Aplica descuentos durante cambios de plan Ofrece precios promocionales cuando los clientes mejoran o degradan su suscripción. ```typescript theme={null} await client.subscriptions.changePlan('sub_123', { product_id: 'prod_pro', quantity: 1, proration_billing_mode: 'prorated_immediately', discount_codes: ['UPGRADE20'] }); ``` | `discount_codes` valor | Comportamiento en el cambio de plan | | --------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | `undefined` / `null` (no proporcionado) | Los descuentos existentes con `preserve_on_plan_change=true` se conservan si son aplicables al nuevo producto. | | `[]` (array vacío) | **Todos** los descuentos existentes se eliminan de la suscripción. | | `['CODE_A', 'CODE_B', ...]` | Reemplaza cualquier descuento existente con este conjunto apilado, aplicado en orden de array. | Lee todos los descuentos aplicados de la suscripción a través del nuevo array `discounts` en la respuesta de suscripción. Cada entrada incluye `discount_id`, `position`, `cycles_remaining` (para suscripciones), y el código original. ### Habilitar la entrada de descuentos sin preaplicar Permitir que los clientes ingresen un código en el checkout sin pasar uno por adelantado. ```typescript theme={null} const session = await client.checkoutSessions.create({ product_cart: [ { product_id: 'prod_abc', quantity: 1 } ], feature_flags: { allow_discount_code: true }, return_url: 'https://yoursite.com/return' }); ``` ## Mejores Prácticas * **Nombra claramente**: Usa códigos reconocibles que coincidan con los nombres de campaña * **Define el tiempo**: Agrega vencimientos para generar urgencia y prevenir mal uso * **Define el alcance sabiamente**: Limita a productos específicos para evitar pérdida de margen * **Valida temprano**: Verifica la aplicabilidad del código antes de confirmar el checkout * **Monitorea el impacto**: Rastrea el uso y la conversión por campaña Los códigos de descuento son poderosas herramientas para la adquisición y retención. Comienza con ofertas simples y bien nombradas, valida a fondo e itera basado en el rendimiento.