# Cupones y códigos de promoción Agrega descuentos a suscripciones y artículos de suscripción con cupones y códigos promocionales. Crea y administra cupones y códigos promocionales para aplicar descuentos a las suscripciones, partidas de suscripción o facturas de un cliente mediante el Dashboard o las API de Stripe. Usa los cupones para lo siguiente: - Aplicar [descuentos](https://docs.stripe.com/api/discounts.md) a una suscripción, partida de suscripción o factura. - Configura un cupón para que se aplique una única vez, por una cantidad determinada de meses o de manera indefinida. - Reducir los importes de las facturas conforme a un porcentaje o un importe fijo ## Cupones vs. códigos promocionales Estas son las diferencias entre un cupón y un código promocional: - [Cupones](https://docs.stripe.com/billing/subscriptions/coupons.md#coupons): tú decides qué cliente recibe el descuento y cuándo. Son descuentos controlados por el back-end (tu sistema decide quién recibe el descuento). - [Códigos promocionales](https://docs.stripe.com/billing/subscriptions/coupons.md#promotion-codes): tu cliente decide cuándo aplicar un descuento. Este es un código destinado al cliente que incluye un cupón, lo que agrega una capa de distribución y control sobre los cupones. Varios códigos promocionales pueden referirse a un mismo cupón. Los códigos de promoción heredan las restricciones de productos de su cupón principal. Por ejemplo, si un cupón solo se aplica a determinados productos, cualquier código promocional creado a partir de él tiene las mismas restricciones. En esta página, «descuento» tiene dos significados. En el lenguaje cotidiano, un descuento es cualquier reducción de precio. En la API de Stripe, un [Descuento](https://docs.stripe.com/api/discounts/object.md) es un objeto específico que representa la solicitud de un cupón para un cliente, una suscripción o una factura. Cuando un cliente canjea un cupón, Stripe crea un objeto `Discount` para realizar el seguimiento de ese canje. Puedes aplicar hasta 20 descuentos a una suscripción, partida de suscripción o factura. Este límite se comparte entre cupones y códigos promocionales. | | **Cupón** | **Código promocional** | | --- | --- | --- | | Definición | Objeto de la API que define la lógica de descuentos. Aplícalos directamente a la suscripción de un cliente mediante el Dashboard o la API. | Código que se asigna a tus cupones y que ve el cliente. Es la cadena que el cliente ingresa en la confirmación de compra. Por ejemplo, `FALLPROMO` y `SPRINGPROMO` pueden asignarse ambos a un único cupón del 25 % de descuento. | | Caso de uso | Tu equipo de ventas cierra un trato con un cliente por un 20 % de descuento negociado en su suscripción anual. Tu back-end aplica el descuento directamente y el cliente no tiene que ingresar nada. | Tu equipo de marketing lanza una campaña en redes sociales y quiere que los creadores compartan un código `EXAMPLE2026` que ofrezca a los nuevos suscriptores un 25 % de descuento durante 3 meses. Solo funciona para los clientes nuevos con un gasto mínimo de USD 50 y quieres limitarlo a 500 canjes. | | Restringir a un cliente en particular | ❌ No admitido | ✓ Admitido | | Aplicar solo a las compras que se realizan por primera vez | ❌ No admitido | ✓ Admitido | | Gasto mínimo para canjear | ❌ No admitido | ✓ Admitido | | Desactivar sin eliminar | Solo puedes eliminar cupones, no desactivarlos. La eliminación no quita los descuentos existentes, pero impide que se realicen nuevas solicitudes. Cuando se elimina un cupón, se archivan sus códigos promocionales asociados. | Puedes archivar el código promocional cambiando el indicador a `activo` (active). | Para usar descuentos en pagos únicos, consulta mejor [Cómo agregar descuentos para pagos únicos](https://docs.stripe.com/payments/checkout/discounts.md). ## Cupones Para reducir los cargos de un cliente, canjea un cupón para crear un objeto [Discount](https://docs.stripe.com/api/discounts/object.md) en una suscripción o un cliente. Consulta cómo crear y gestionar cupones en las siguientes secciones. ### Crear un cupón Crea cupones en el Dashboard o con el [método para crear un cupón](https://docs.stripe.com/api/coupons/create.md): #### Dashboard 1. En el Dashboard, abre la página [Productos](https://dashboard.stripe.com/test/products?active=true). 2. Haz clic en **Cupones**. 3. Haz clic en **+Nuevo**. 4. En el cuadro de diálogo **Crear un cupón**, ingresa los parámetros del cupón. 5. Haz clic en **Crear cupón**. A continuación se muestran todas las configuraciones de los cupones. El nombre es la única configuración que puedes editar después de crear el cupón. | Configuración | Descripción | | --- | --- | | **Nombre** | El nombre del cupón que aparece en los recibos y facturas. | | **ID** (opcional) | Un identificador único para el cupón en la API. Si dejas este campo en blanco, Stripe te genera un ID. | | **Tipo** | Determina si un cupón aplica un descuento a una suscripción por un importe fijo o por un porcentaje. | | **Porcentaje de descuento** o **Importe del descuento** | Indica el descuento que ofrece el cupón. Si vendes en varias monedas, un solo cupón puede definir diferentes importes de descuento para diferentes monedas. Los cupones en múltiples monedas siguen las mismas reglas que los [precios en múltiples monedas](https://docs.stripe.com/products-prices/how-products-and-prices-work.md#multiple-currencies). | | **Aplicar a productos específicos** (opcional) | Limita el tipo de artículos a los que se puede aplicar el cupón. | | **Duración** | Indica por cuánto tiempo es válido el cupón. | | **Límites de canjes** (opcional) | Te permite limitar el momento en que el cliente puede canjear el cupón y la cantidad de veces que se puede canjear. | | **Códigos** (opcional) | Te permite crear [códigos de promoción](https://docs.stripe.com/billing/subscriptions/coupons.md#promotion-codes) para el cupón. | #### API ```curl curl https://api.stripe.com/v1/coupons \ -u "<>:" \ -d duration=once \ -d id=free-period \ -d percent_off=100 ``` La siguiente tabla contiene los parámetros del cupón. | Configuración | Descripción | | --- | --- | | `id` | Un identificador único para el cupón. | | `percent_off` o `amount_off` | El importe que se deduce del subtotal mientras dure la validez del cupón. | | `currency` (si se establece `amount_off`) | El código ISO de tres letras de la moneda del importe a descontar. | | `currency_options` (si se establece `amount_off`) (opcional) | Si vendes en varias monedas, descuenta los importes correspondientes del subtotal para las diferentes monedas. Los cupones en múltiples monedas siguen las mismas reglas que los [precios en múltiples monedas](https://docs.stripe.com/products-prices/how-products-and-prices-work.md#multiple-currencies). | | `duration` | Indica por cuánto tiempo es válido el cupón. Los valores incluyen **una vez**, **siempre** o **varias veces**. | | `max_redemptions` (opcional) | Cantidad máxima de veces que se puede canjear un cupón para todos los clientes. | | `redeem_by` (opcional) | La fecha límite para aplicar este cupón a clientes. | | `applies_to` (opcional) | Limita los artículos de una factura a los que se puede aplicar el cupón. | ### Definir los productos elegibles #### Dashboard Para establecer los productos elegibles para descuentos, agrega el producto pertinente en el campo **Aplicar a un producto específico**. Todos los códigos de promoción asociados con el cupón también están restringidos a esta lista de productos aptos. Si configuras un cupón para que se aplique a productos específicos y una suscripción no tiene ningún producto aplicable, no se aplicará ningún descuento cuando agregues el cupón a la suscripción. #### API Para establecer qué productos son aptos para descuentos, agrega los ID de los productos correspondientes al hash `applies_to` del cupón. Esta lista de productos elegibles también se aplica a los códigos de promoción asociados con el cupón. Si configuras un cupón para que se aplique a productos específicos y una suscripción no tiene ningún producto aplicable, no se aplicará ningún descuento cuando agregues el cupón a la suscripción. Cuando [haces cambios](https://docs.stripe.com/billing/subscriptions/change.md) a una suscripción, Stripe calcula el prorrateo y aplica los descuentos existentes. No puedes descontar más partidas de prorrateo en la factura que se genera. ### Aplica cupones a las suscripciones Después de crear los cupones, crea un descuento aplicándolos a una suscripción. Puedes aplicar el cupón creando la suscripción o [actualizando la suscripción vigente del cliente](https://docs.stripe.com/api.md#update_subscription). #### Dashboard 1. En el Dashboard, abre la página [Suscripciones](https://dashboard.stripe.com/test/subscriptions?status=active). 2. Haz clic en la suscripción correspondiente. 3. Haz clic en **Acciones**. 4. Haz clic en **Actualizar suscripción**. 5. Haz clic en **Agregar cupón**. 6. Selecciona uno o más cupones del menú desplegable y haz clic en **Enviar**. #### API > #### Usa la API Accounts v2 para representar a los clientes > > La API Accounts v2 suele estar disponible para usuarios Connect y en versión preliminar pública para otros usuarios de Stripe. Si eres parte de la versión preliminar Accounts v2, debes especificar una [versión preliminar](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning) en tu código. > > Con el propósito de unirte a la versión preliminar Accounts v2, ve a las [versiones preliminares y funcionalidades de la cuenta](https://dashboard.stripe.com/settings/previews) en tu Dashboard y habilita **Métodos de pago reutilizables para Global Payouts**. > > Para la mayoría de los casos de uso, te recomendamos que[modeles a tus clientes como objetos Account configurados por el cliente](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md) en lugar de usar objetos [Customer](https://docs.stripe.com/api/customers.md). #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "discounts[0][coupon]=free-period" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "discounts[0][coupon]=free-period" ``` Aún puedes crear una suscripción cuando un cliente no tenga un método de pago almacenado si [no se requiere un pago inmediato](https://docs.stripe.com/billing/subscriptions/deferred-payment.md) después de apliques cupones a dicha suscripción. ### Aplica cupones a Checkout Aplica cupones a las suscripciones en una sesión de Checkout estableciendo el parámetro `discounts` al [crear una sesión de Checkout](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-discounts). Para crear una sesión con un descuento aplicado, pasa el ID del cupón en el parámetro `coupon` del arreglo `discounts`. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "line_items[][price]"="{{PRICE_ID}}" \ -d "line_items[][quantity]"=1 \ -d mode=subscription \ -d "discounts[][coupon]"="{{COUPON_ID}}" \ -d success_url="https://example.com/success" ``` ### Eliminar cupones Puedes eliminar cupones desde el Dashboard o con el método para [eliminar un cupón](https://docs.stripe.com/api/coupons/delete.md). La eliminación de un cupón impide que se aplique a futuras suscripciones o facturas, pero no elimina el descuento de ninguna suscripción o factura que ya lo tenga. #### Dashboard 1. En el Dashboard, abre la página [Productos](https://dashboard.stripe.com/test/products?active=true). 2. Haz clic en **Cupones** 3. Haz clic en el cupón correspondiente. 4. Haz clic en el menú de contenido adicional (⋯). 5. Haz clic en **Eliminar cupón**. #### API ```curl curl -X DELETE https://api.stripe.com/v1/coupons/free-period \ -u "<>:" ``` ### Duración del cupón La duración de un cupón indica por cuánto tiempo es válido el [descuento](https://docs.stripe.com/api/.md#discounts) canjeado. La duración predeterminada es `once`, que se aplica solo a la primera factura. Establece `duration=repeating` con `duration_in_months` para aplicar un descuento durante varios meses, o `duration=forever` con el fin de aplicarlo a todas las facturas de forma indefinida. Por ejemplo, un cupón de 50 % de descuento con `duration_in_months=4` se aplica a todas las facturas en el período de 4 meses que comienza cuando el cupón se aplica por primera vez. En una suscripción mensual, el cupón se aplica a las primeras 4 facturas. En una suscripción anual, el descuento del 50 % se aplica a todo el año si la suscripción se renueva dentro del período de 4 meses. En una suscripción semanal, se aplica a cada factura durante los primeros 4 meses. Cuando una suscripción usa un cupón con `duration=once`, el cupón se considera utilizado una vez que la factura se finaliza y se elimina de la matriz `discounts` de la suscripción: - Antes de que el cupón se aplique a cualquier factura, el parámetro `discounts` de la suscripción incluye el objeto de descuento. - Una vez que la factura se finaliza, el parámetro `discounts` de la suscripción ya no incluye ese descuento. - La factura que consumió el cupón sigue mostrando el descuento aplicado sobre el recurso de factura y las partidas. Esto significa que una suscripción puede parecer que no tiene descuento a pesar de que se haya aplicado un cupón. > Si aplicas un cupón a una [suscripción con fecha anterior](https://docs.stripe.com/billing/subscriptions/backdating.md), la duración del cupón comienza a contar desde la fecha de inicio anterior, no desde el momento en que realizas la llamada API. Para `repetir` cupones, esto significa que el período anterior consume parte de la duración del cupón. El valor de `duration_in_months` del cupón debe ser mayor que el período con fecha anterior si quieres que el descuento se aplique a las facturas posteriores a este. Consulta [Fechas y descuentos](https://docs.stripe.com/billing/subscriptions/backdating.md#backdating-discounts) para obtener más detalles. ### Límites de canjes Aplicar un cupón significa adjuntarlo directamente a una suscripción, un cliente o una factura utilizando la API o el Dashboard. Canjear un código de promoción significa que un cliente ingresa un código en el proceso de compra con el fin de activar el cupón subyacente. Ambas acciones cuentan para el mismo límite de `max_redemptions` en el cupón. Los límites de canje restringen la cantidad de veces que se puede aplicar un cupón en todos los clientes. Por ejemplo, establecer `max_redemptions=50` significa que el cupón solo se puede aplicar 50 veces en total: una vez a 50 clientes diferentes, 50 veces al mismo cliente o cualquier combinación hasta alcanzar el límite. Con el uso de códigos de promoción, el canje del código por parte de un cliente cuenta para este límite. Si configuras un cupón con el fin de que dure para siempre cuando un cliente lo usa, pero el cupón tiene una fecha de vencimiento, cualquier cliente que reciba ese cupón tendrá el descuento de este cupón para siempre. Los clientes nuevos no pueden aplicar el cupón después de la fecha de vencimiento. ## Códigos de promoción Los códigos de promoción son códigos visibles para el cliente que creas para los cupones. Por ejemplo, FALLPROMO y SPRINGPROMO pueden asociarse con un único cupón de un 25 % de descuento. Puedes compartir los códigos de promoción directamente con tus clientes para que los usen durante el pago. Si implementaste el *portal de clientes* (The customer portal is a secure, Stripe-hosted page that lets your customers manage their subscriptions and billing details) y activaste los códigos de promoción, los clientes pueden aplicar un descuento al cambiar sus suscripciones existentes a un nivel superior o inferior en el portal. > Las suscripciones aplican actualizaciones de precios y códigos de promoción por separado, lo que puede provocar actualizaciones inesperadas. Por ejemplo, un error en el pago puede provocar que falle una actualización de precio, pero el código de promoción incluido con la actualización de precio se efectúa correctamente. El portal de clientes muestra los códigos de promoción que se han aplicado a una suscripción. Si no deseas permitir que los clientes apliquen el código de promoción ellos mismos o que lo compartan con otras personas, debes [establecer límites en el código de promoción](https://docs.stripe.com/billing/subscriptions/coupons.md#promo-code-config) o [aplicar un cupón](https://docs.stripe.com/billing/subscriptions/coupons.md#discount-subscriptions) directamente. Personaliza los controles y los límites de los códigos de promoción, especificando los clientes elegibles, los primeros pedidos, los valores mínimos de los pedidos, las fechas de vencimiento y los límites de canje. ### Restricciones Hay algunas restricciones en cuanto a los códigos de promoción. - No puedes aplicar un código de promoción con restricciones de importe a: - [Objetos Subscription Item](https://docs.stripe.com/api/subscription_items/object.md) - [Objetos de partida de factura](https://docs.stripe.com/api/invoiceitems/object.md) - [Objetos Subscriptions](https://docs.stripe.com/api/subscriptions/object.md) cuando haces una actualización - Fases futuras en [objetos Subscription Schedule](https://docs.stripe.com/api/subscription_schedules/object.md) ### Crear códigos de promoción #### Dashboard Puedes crear un código de promoción en el Dashboard cuando [creas un cupón](https://docs.stripe.com/billing/subscriptions/coupons.md#create-a-coupon). El **Código** reconoce mayúsculas y minúsculas y es único entre los códigos de promoción activos para cualquier cliente. Por ejemplo: - Puedes crear múltiples códigos de promoción restringidos a un cliente con el mismo **código**, pero no puedes reutilizar ese **código** para un código de promoción que cualquier cliente pueda canjear. - Si creas un código de promoción que pueda canjear cualquier cliente, no podrás crear otro código de promoción activo con el mismo **código**. - Puedes crear un código de promoción con un **Código**, [desactivarlo](https://docs.stripe.com/billing/subscriptions/coupons.md#deactivate) y, luego, crear un nuevo código de promoción con el mismo **Código**. 1. En el Dashboard, en la página [Crear un cupón](https://dashboard.stripe.com/test/coupons/create), haz clic en el botón **Usar códigos de promoción para los clientes**. 2. Ingresa un código. Este es el código que ingresa un cliente durante el pago para canjear el descuento. Si no configuras un código, Stripe genera uno para ti. 3. Selecciona requisitos para el código de promoción. Por ejemplo, puedes restringir el cupón para que solo sea válido en los primeros pedidos. #### API El `code` distingue mayúsculas y minúsculas y es único entre todos los códigos de promoción activos para clientes. Por ejemplo: - Puedes crear múltiples códigos de promoción restringidos a un cliente con el mismo `code`, pero no puedes reutilizar ese `code` para un código de promoción que cualquier cliente pueda canjear. - Si creas un código de promoción canjeable por cualquier cliente, no podrás crear otro código de promoción activo con el mismo `code`. - Puedes crear un código de promoción con `code: NEWUSER`, inactivarlo especificando `active: false` y luego crear un nuevo código de promoción con `code: NEWUSER`. Para crear un [código de promoción](https://docs.stripe.com/api/promotion_codes.md), especifica un `cupón` existente y cualquier restricción (p. ej., habilitado solo para un ID de `cliente` específico). Puedes especificar la cadena de código (p. ej., `FALL25OFF`) en el parámetro `code`. Si no proporcionas una cadena de código, Stripe generará una aleatoria. #### Accounts v2 ```curl curl https://api.stripe.com/v1/promotion_codes \ -u "<>:" \ -d "coupon={{COUPON_ID}}" \ -d code=ALICE20 \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/promotion_codes \ -u "<>:" \ -d "coupon={{COUPON_ID}}" \ -d code=ALICE20 \ -d "customer={{CUSTOMER_ID}}" ``` Al crear un código de promoción, este hereda la configuración del cupón asociado. ### Configuraciones del código de promoción Al configurar los ajustes del código de promoción, puedes personalizar lo siguiente: - Qué clientes cumplen los requisitos para usar un código de promoción - Cuántas veces puede canjear un código de promoción un cliente - Cuando vence un código de promoción - Establece el importe mínimo al que se puede aplicar un código de promoción ### Limitar por cliente #### Dashboard Para limitar un código de promoción a un cliente en particular, sigue estos pasos: 1. En la página [Crear un cupón](https://dashboard.stripe.com/test/coupons/create), selecciona **Limitar a un cliente específico**. 2. Selecciona el cliente correspondiente. Si no especificas un cliente, cualquier cliente puede canjear el código de promoción. #### API Para limitar un código de promoción a un determinado cliente, especifica una `customer_account` o `customer` cuando crees el código de promoción. Si no especificas un cliente, cualquiera podrá canjear el código. ### Limitar por primer pedido Limita el uso de un cupón a los clientes que no tienen un historial previo de transacciones en tu plataforma. Esta configuración impide que los clientes utilicen un cupón si: - Se inició un PaymentIntent, incluso si el pago nunca se completó. - Se suscribió a un período de prueba, incluso si posteriormente se canceló. #### Dashboard Para limitar un código de promoción a los clientes nuevos, en la página [Crear un cupón](https://dashboard.stripe.com/test/coupons/create), selecciona **Apto solo para pedidos nuevos**. #### API Configura el parámetro `first_time_transaction` del atributo `restrictions` para limitar el código promocional a los clientes nuevos. ### Definir un importe mínimo #### Dashboard Para establecer un importe mínimo apto para un código de promoción, en la página [Crear un cupón](https://dashboard.stripe.com/test/coupons/create), selecciona **Requerir un valor mínimo de pedido** e ingresa el valor mínimo. Debido a que las restricciones del código de promoción se verifican en el momento del canje, el importe mínimo de transacción solo se aplica al pago inicial de una suscripción. Si el cupón admite varias monedas, el importe mínimo puede ser diferente según la moneda. #### API Con códigos de promoción, puedes definir el importe mínimo de la transacción para aplicar el descuento configurando las propiedades `minimum_amount` y `minimum_amount_currency`. Dado que las restricciones del código de promoción se controlan en el momento del canje, el importe mínimo de transacción solo se aplica al pago inicial de una suscripción. Si vendes en varias monedas, fija el importe mínimo de la transacción para diferentes monedas configurando la propiedad `currency_options`. ### Personalizar los vencimientos #### Dashboard Para establecer una fecha de vencimiento para un código de promoción, en la página [Crear un cupón](https://dashboard.stripe.com/test/coupons/create), selecciona **Agregar una fecha de vencimiento** y la fecha y hora en que vence el código de promoción. Si el cupón subyacente ya tiene una fecha de vencimiento establecida, la fecha de vencimiento del código de promoción no puede ser posterior a la del cupón. Supongamos que planeas aceptar un cupón por un año, pero quieres que solo sea canjeable durante una semana a partir de que el cliente lo recibe. Debes establecer la fecha de vencimiento del cupón en un año a partir de ahora y la fecha de vencimiento de cada código de promoción a una semana a partir de su creación. #### API Define la fecha de vencimiento del código de promoción con `expires_at`. Si el cupón subyacente ya tiene definido `redeem_by`, la fecha de vencimiento del código de promoción no puede ser posterior a la del cupón. Si no se especifica `promotion_code[expires_at]`, el valor `redeem_by` del cupón automáticamente se completa como `expires_at`. - Supongamos que planeas aceptar un cupón por un año, pero quieres que solo sea canjeable durante una semana a partir de que el cliente lo recibe. Debes establecer `coupon[redeem_by]` en un año a partir de ahora y cada `promotion_code[expires_at]` a una semana a partir de su creación. ### Limitar los canjes #### Dashboard Para establecer la cantidad total de veces que tus clientes pueden canjear un código de promoción, selecciona **Limitar la cantidad de veces que este código puede ser canjeado** en la página [Crear un cupón](https://dashboard.stripe.com/test/coupons/create) e ingresa el número. Consulta [Límites de canje](https://docs.stripe.com/billing/subscriptions/coupons.md#redemption-limits) para obtener más información. Si el cupón subyacente ya tiene configurado un número máximo de veces, los canjes máximos del código de promoción no pueden ser mayores que los del cupón. #### API Limita la cantidad total de veces que tus clientes pueden canjear un código de promoción usando `max_redemptions`, que funciona de manera similar a los cupones. Si el cupón correspondiente ya tiene un `max_redemptions` definido, el `max_redemptions` del código de promoción no puede ser mayor que el del cupón. Consulta los [límites de canje](https://docs.stripe.com/billing/subscriptions/coupons.md#redemption-limits) para obtener más información. ### Desactivar códigos de promoción #### Dashboard Para desactivar un código de promoción, sigue estos pasos: 1. En el Dashboard, abre la página [Productos](https://dashboard.stripe.com/test/products?active=true). 2. Haz clic en **Cupones**. 3. Haz clic en el cupón cuyo código de promoción deseas desactivar. 4. En la fila del código de promoción correspondiente, haz clic en el menú de contenido adicional (⋯). 5. Haz clic en **Archivar código de promoción**. Sin embargo, si el cupón subyacente de un código de promoción pierde su validez, todos sus códigos de promoción quedarán inactivos de forma permanente. Del mismo modo, si un código de promoción alcanza su límite máximo de canje o su fecha de vencimiento, queda inactivo de forma permanente. Estos códigos de promoción no se pueden reactivar. #### API Establece si un código de promoción es canjeable en un determinado momento usando el parámetro `active`. Sin embargo, si el cupón subyacente de un código de promoción pierde su validez, todos sus códigos de promoción quedarán inactivos de forma permanente. Del mismo modo, si un código de promoción alcanza su `max_redemptions` o `expires_at`, quedará inactivo de forma permanente. Estos códigos de promoción no se pueden reactivar. ### Aplicar códigos de promoción a las suscripciones Después de crear un código de promoción, canjea un descuento aplicando el código de promoción a una suscripción. Puedes aplicar códigos de promoción de dos maneras: - Cuando [creas una suscripción](https://docs.stripe.com/api.md#create_subscription) - Cuando [actualizas la suscripción existente de un cliente](https://docs.stripe.com/api.md#update_subscription) #### Dashboard 1. En el Dashboard, ve a **Billing** > **Suscripciones**. 2. Haz clic en la suscripción correspondiente. 3. Haz clic en **Acciones** > **Actualizar suscripción** > **Agregar cupón**. 4. Haz clic en un código de promoción desde el menú desplegable y luego haz clic en **Enviar**. #### API 1. [Enumera tus PromotionCodes](https://docs.stripe.com/api/promotion_codes/list.md) y proporciona la cadena de código que tu cliente ingresó en el parámetro [code](https://docs.stripe.com/api/promotion_codes/list.md#list_promotion_code-code) para recuperar el `PromotionCode` correspondiente. 2. Para aplicar el código de promoción, usa el ID del código de promoción en la siguiente llamada de API: #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "discounts[0][promotion_code]={{PROMOTIONCODE_ID}}" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "discounts[0][promotion_code]={{PROMOTIONCODE_ID}}" ``` ### Agrega códigos de promoción a Checkout Habilita los códigos de promoción con la API si configuras el parámetro [allow_promotion_codes](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-allow_promotion_codes) en Checkout Sessions. Cuando se habilita `allow_promotion_codes` en una Checkout Session, Checkout incluye un cuadro de canje de códigos de promoción para que lo usen tus clientes. ![Campo de código de promoción en Checkout](https://b.stripecdn.com/docs-statics-srv/assets/promo_code_checkout.c07ef6d4f0b1b3f9a8a7e4bbba83d56f.png) Campo de código de promoción en Checkout ## Cupones acumulables y códigos de promoción Puedes agregar varios cupones, códigos de promoción o [descuentos](https://docs.stripe.com/api/.md#discounts) canjeables a la lista de cargos de un cliente. Puedes hacerlo [creando una suscripción](https://docs.stripe.com/api.md#create_subscription) o [actualizando la suscripción existente de un cliente](https://docs.stripe.com/api.md#update_subscription). Admitimos varios descuentos tanto en suscripciones como en artículos de suscripción. Cuando creas una suscripción con descuentos acumulables, cada descuento se aplica a todos los ítems de la suscripción. El orden de los descuentos es importante si usas `amount_off` y `percent_off`. Por ejemplo, los siguientes descuentos acumulados se aplican de forma diferente: - 20 % de descuento *luego* USD 5 de descuento - USD 5 de descuento *luego* 20 % de descuento #### Dashboard 1. En el Dashboard, ve a **Billing** > **Suscripciones**. 2. Haz clic en la suscripción correspondiente. 3. Haz clic en **Acciones** > **Actualizar suscripción** > **Agregar cupón**. 4. Haz clic en los cupones desde los menús desplegables y haz clic en **Enviar**. 5. Haz clic en el producto correspondiente. 6. Haz clic en **Agregar cupones**. 7. Haz clic en los cupones desde los menús desplegables y haz clic en **Enviar**. #### API #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "items[0][discounts][0][coupon]=item-coupon" \ -d "items[0][discounts][1][promotion_code]=item-promo" \ -d "discounts[0][coupon]=sub-coupon" \ -d "discounts[1][promotion_code]=sub-promo" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "items[0][discounts][0][coupon]=item-coupon" \ -d "items[0][discounts][1][promotion_code]=item-promo" \ -d "discounts[0][coupon]=sub-coupon" \ -d "discounts[1][promotion_code]=sub-promo" ``` ### Restricciones Existen algunas restricciones en cuanto al uso de descuentos múltiples. - Puedes configurar hasta 20 entradas en el parámetro `discounts`. - Cada entrada en `discounts` tiene que ser única. - No puedes pasar un cupón y un código de promoción creados a partir del mismo cupón. - No puedes pasar un cupón y un descuento que se genera a partir del mismo cupón. - Los descuentos canjeados ya deben estar asociados al cliente o a la suscripción que estás actualizando. ### Actualizar una suscripción No es necesario que establezcas `discounts` si no tienes intención de hacer cambios en los descuentos existentes. Al actualizar `discounts`, debes especificar cualquier `coupon`, `promotion_code` o `discount` previamente configurado que quieras mantener en la suscripción. Especifica `discounts = ""` para eliminar todos los descuentos de la suscripción. Cuando una suscripción no tiene descuentos, el descuento del cliente, si lo hubiera, se aplica a las facturas. Si ya estableciste más de un descuento en una suscripción con el nuevo parámetro `descuentos`, no puedes actualizar la suscripción con el parámetro `cupón` o `promotion_code` obsoleto. Del mismo modo, no puedes actualizar las fases de un calendario con el parámetro `cupón` o `promotion_code` obsoleto si estableciste más de un descuento en una fase anterior. La actualización de `discounts` no implica prorrateos ni genera facturas por sí solas. Los nuevos descuentos se aplican la próxima vez que la suscripción crea una factura. > Actualizar los códigos de promoción, cupones o descuentos de las suscripciones por sí mismos no crea partidas de factura prorrateadas. Solo los cambios que afectan a los importes facturables del ciclo de facturación actual crean prorrateos, por ejemplo, cambiar el `price` o la `quantity` de una partida de suscripción, agregar o eliminar partidas de suscripción o cambiar las delimitaciones del ciclo de facturación. > > Sin embargo, cuando combinas un cambio de descuento con una actualización que activa el prorrateo (como cambiar la cantidad de una partida y modificar un descuento en la misma llamada API), Stripe calcula los importes del prorrateo utilizando los precios actualizados y el estado de descuento de la suscripción. El débito o crédito por prorrateo refleja los descuentos modificados. ## Métodos de descuento alternativos Si bien los cupones son la forma más común de aplicar descuentos a una suscripción, también puedes hacer lo siguiente: - Agrega un [saldo de cliente](https://docs.stripe.com/api.md#customer_object-balance) negativo al cliente. - Agrega [partidas de factura](https://docs.stripe.com/billing/invoices/subscription.md#adding-draft-invoice-items) negativas. - Agrega un [segundo precio](https://docs.stripe.com/products-prices/manage-prices.md#create-price) que sea una versión más barata del precio habitual del producto. De estos métodos, las partidas de factura negativas proporcionan información más detallada sobre qué descuento se creó, cuándo y por qué. ## See also - [Cómo modificar las suscripciones](https://docs.stripe.com/billing/subscriptions/change.md) - [Prorrateos](https://docs.stripe.com/billing/subscriptions/prorations.md) - [Cómo trabajar con facturas](https://docs.stripe.com/billing/invoices/subscription.md) - [API de cupones](https://docs.stripe.com/api.md#coupons) - [API de códigos de promoción](https://docs.stripe.com/api.md#promotion_codes)