Subscriptions - Dodo Payments Documentation

Subscriptions let you sell ongoing access with automated renewals. Use flexible billing cycles, free trials, plan changes, and add‑ons to tailor pricing for each customer.

Upgrade & Downgrade

Control plan changes with proration and quantity updates.

On‑Demand Subscriptions

Authorize a mandate now and charge later with custom amounts.

Customer Portal

Let customers manage plans, billing, and cancellations.

Subscription Webhooks

React to lifecycle events like created, renewed, and canceled.

What Are Subscriptions?

Subscriptions are recurring products customers purchase on a schedule. They’re ideal for:

SaaS licenses: Apps, APIs, or platform access
Memberships: Communities, programs, or clubs
Digital content: Courses, media, or premium content
Support plans: SLAs, success packages, or maintenance

Key Benefits

Predictable revenue: Recurring billing with automated renewals
Flexible cycles: Monthly, annual, custom intervals, and trials
Plan agility: Proration for upgrades and downgrades
Add‑ons and seats: Attach optional, quantifiable upgrades
Seamless checkout: Hosted checkout and customer portal
Developer-first: Clear APIs for creation, changes, and usage tracking

Creating Subscriptions

Create subscription products in your Dodo Payments dashboard, then sell them through checkout or your API. Separating products from active subscriptions lets you version pricing, attach add‑ons, and track performance independently.

Subscription product creation

Configure the fields in the dashboard to define how your subscription sells, renews, and bills. The sections below map directly to what you see in the creation form.

Product details

Product Name (required): The display name shown in checkout, customer portal, and invoices.
Product Description (required): A clear value statement that appears in checkout and invoices.
Product Image (required): PNG/JPG/WebP up to 3 MB. Used on checkout and invoices.
Brand: Associate the product with a specific brand for theming and emails.
Tax Category (required): Choose the category (for example, SaaS) to determine tax rules.

Pick the most accurate tax category to ensure correct tax collection per region.

Pricing

Tipo de precio: Elige Subscription (esta guía). Las alternativas son Single Payment y Usage Based Billing.
Precio (obligatorio): Precio recurrente base con moneda. El precio debe ser de al menos $1 (o el equivalente en la moneda elegida). No se admiten importes inferiores a este mínimo y la suscripción no funcionará.
Descuento aplicable (%): Descuento porcentual opcional aplicado al precio base; se refleja en el checkout y las facturas.
Repetir pago cada (obligatorio): Intervalo de las renovaciones, por ejemplo, cada 1 Month. Selecciona la frecuencia (meses o años) y la cantidad.
Periodo de suscripción (obligatorio): Plazo total durante el que la suscripción permanece activa (por ejemplo, 10 Years). Una vez finalizado este periodo, las renovaciones se detienen salvo que se amplíe.
Días del periodo de prueba (obligatorio): Define la duración de la prueba en días. Usa 0 para desactivar las pruebas. El primer cobro se realiza automáticamente cuando termina la prueba.
Importe de prueba: Cargo inicial opcional para una prueba de pago. Déjalo sin establecer para una prueba gratuita. Consulta Pruebas de pago.
Seleccionar complemento: Añade hasta 10 complementos que los clientes pueden comprar junto con el plan base.

Changing pricing on an active product affects new purchases. Existing subscriptions follow your plan‑change and proration settings.

Add‑ons are ideal for quantifiable extras such as seats or storage. You can control allowed quantities and proration behavior when customers change them.

Advanced settings

Tax Inclusive Pricing: Display prices inclusive of applicable taxes. Final tax calculation still varies by customer location.
Generate license keys: Issue a unique key to each customer after purchase. See the License Keys guide.
Digital Product Delivery: Deliver files or content automatically after purchase. Learn more in Digital Product Delivery.
Metadata: Attach custom key–value pairs for internal tagging or client integrations. See Metadata.

Use metadata to store identifiers from your system (e.g., accountId) so you can reconcile events and invoices later.

Subscription Trials

Las pruebas permiten a los clientes evaluar una suscripción antes de pagar el precio recurrente completo. Una prueba puede ser gratuita, sin ningún cargo hasta que finalice, o de pago, con un importe reducido cobrado por adelantado. En ambos casos, el precio completo comienza en la primera renovación después de que termina la prueba.

Configuring Trials

Set Trial Period Days in the product pricing section (use 0 to disable). You can override this when creating subscriptions:

// Via subscription creation
const subscription = await client.subscriptions.create({
  customer: { customer_id: 'cus_123' },
  billing: { country: 'US' },
  product_id: 'pdt_monthly',
  quantity: 1,
  trial_period_days: 14  // Overrides product's trial period
});

// Via checkout session
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_monthly', quantity: 1 }],
  subscription_data: { trial_period_days: 14 }
});

The trial_period_days value must be between 0 and 10,000 days.

Pruebas de pago

Las pruebas no tienen que ser gratuitas. Define un Importe de prueba en el precio recurrente de un producto de suscripción para cobrar una tarifa inicial reducida durante el periodo de prueba. El precio recurrente completo se aplica en la primera renovación.

Formulario de precios de suscripción con una duración de prueba y un importe de prueba opcional para una prueba de pago

Las pruebas de pago se configuran en el precio del producto, no por suscripción ni por sesión de checkout:

Campo	Tipo	Descripción
`trial_amount`	entero	Importe cobrado hoy por la prueba, en las unidades menores de la moneda del precio (por ejemplo, `500` para $5.00). Requiere `trial_period_days > 0`. Omítelo o establécelo en `null` para una prueba gratuita.
`trial_apply_discounts`	booleano	Indica si los códigos de descuento del checkout reducen el cargo de la prueba. El valor predeterminado es `false`, por lo que el importe de prueba se cobra íntegramente incluso cuando se aplica un descuento al precio recurrente.

const product = await client.products.create({
  name: 'Pro Plan',
  tax_category: 'saas',
  price: {
    type: 'recurring_price',
    price: 2900,                      // $29.00 per month after the trial
    currency: 'USD',
    discount: 0,
    purchasing_power_parity: false,
    payment_frequency_count: 1,
    payment_frequency_interval: 'Month',
    subscription_period_count: 1,
    subscription_period_interval: 'Year',
    trial_period_days: 14,            // A paid trial requires a positive trial period
    trial_amount: 500,                // $5.00 charged today
    trial_apply_discounts: false      // Discounts apply to the recurring price only
  }
});

Las pruebas de pago también pasan por el checkout. El importe de prueba está sujeto a impuestos, aparece en los cálculos de la sesión de checkout y en los precios de los payment links, y se aplica el recargo de Adaptive Currency por moneda. El endpoint de vista previa devuelve trial_amount y trial_period_days para que puedas mostrar el importe adeudado hoy antes de crear la suscripción.

Las pruebas gratuitas no cambian. Dejar Importe de prueba sin establecer mantiene el comportamiento existente: el primer cargo es 0 y el precio completo se cobra cuando termina la prueba.

Prevención del uso indebido de pruebas

Prevenir el uso indebido de pruebas impide que los clientes reclamen pruebas repetidamente para el mismo negocio. Cuando está activado, un cliente que ya haya canjeado una prueba pasa automáticamente a una compra de pago sin prueba, en lugar de recibir una prueba nueva.

Actívalo desde la pestaña Subscriptions en Settings. Una vez activado:

Los clientes se comparan mediante un correo electrónico normalizado, eliminando los alias con signo más, por lo que user+trial@example.com y user@example.com se consideran la misma persona.
Los canjes se registran en la activación de la prueba, por lo que un cliente que cancele el mismo día igualmente habrá consumido su prueba.
Los clientes existentes se incorporan usando sus pruebas históricas por correo electrónico, de modo que los usuarios de pruebas anteriores se reconocen inmediatamente.

La configuración está desactivada de forma predeterminada. Consulta Configuración de suscripciones para ver la lista completa de controles de suscripciones a nivel empresarial.

Detección del estado de una prueba

Actualmente no existe ningún campo directo para detectar el estado de una prueba. La siguiente es una solución alternativa que requiere consultar los pagos, lo cual resulta ineficiente. Estamos trabajando en una solución más eficiente.

Para determinar si una suscripción de prueba gratuita está en periodo de prueba, recupera la lista de pagos de la suscripción. Si existe exactamente un pago con importe 0, la suscripción está en periodo de prueba:

const subscription = await client.subscriptions.retrieve('sub_123');
const payments = await client.payments.list({
  subscription_id: subscription.subscription_id
});

// Check if subscription is in trial
const isInTrial = payments.items.length === 1 && 
                  payments.items[0].total_amount === 0;

Esta comprobación de importe cero solo funciona para pruebas gratuitas. En una prueba de pago, el primer pago equivale al importe de prueba, no a 0. Compara el primer pago con trial_amount de la suscripción o comprueba si next_billing_date sigue dentro del periodo de prueba.

Actualización del periodo de prueba

Amplía la prueba actualizando next_billing_date:

await client.subscriptions.update('sub_123', {
  next_billing_date: '2025-02-15T00:00:00Z'  // New trial end date
});

No puedes establecer next_billing_date en un momento pasado. La fecha debe estar en el futuro.

Cambios del plan de suscripción

Los cambios de plan permiten mejorar o reducir suscripciones, ajustar cantidades o migrar a productos diferentes. Según el modo de prorrateo que selecciones, un cambio puede activar un cargo inmediato, crear un crédito o no aplicar ningún ajuste de facturación.

Puedes cambiar los planes de suscripción y actualizar directamente la próxima fecha de facturación desde el dashboard de Dodo Payments. Esto ofrece una forma rápida de ajustar las suscripciones para solicitudes de soporte, mejoras promocionales o migraciones de plan sin realizar llamadas a la API.

Activar cambios de plan de autoservicio: ¿Quieres que los clientes mejoren o reduzcan sus propias suscripciones mediante el Customer Portal? Añade tus productos de suscripción a una colección de productos y activa “Allow Subscription Updates” en la configuración de suscripciones.

Product Collections

Agrupa productos relacionados en colecciones para habilitar rutas fluidas de mejora y reducción en el Customer Portal.

Modos de prorrateo

Elige cómo se factura a los clientes cuando cambian de plan:

Comparación rápida de los cuatro modos de prorrateo:

	`prorated_immediately`	`difference_immediately`	`full_immediately`	`do_not_bill`
Mejora	Cargo prorrateado por los días restantes	Se cobra la diferencia total de precio	Se cobra el precio completo del nuevo plan	Sin cargo: cambio inmediato
Reducción	Crédito prorrateado por los días restantes	Diferencia total de precio como crédito	Sin crédito, cargo completo	Sin crédito: cambio inmediato
Ciclo de facturación	Se reinicia hoy	Se reinicia hoy	Se reinicia hoy	Se mantiene igual
Ideal para	Facturación justa basada en el tiempo	Cambios de nivel sencillos	Reinicios del ciclo de facturación	Migraciones gratuitas o cambios de cortesía

`prorated_immediately`

Cobra un importe prorrateado según el tiempo restante del ciclo de facturación actual. Ideal para una facturación justa que tenga en cuenta el tiempo no utilizado.

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

`difference_immediately`

Cobra inmediatamente la diferencia de precio (mejora) o añade crédito para futuras renovaciones (reducción). Ideal para situaciones sencillas de mejora o reducción.

// Upgrade: charges $50 (difference between $30 and $80)
// Downgrade: credits remaining value, auto-applied to renewals
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});

Los créditos de las reducciones que usan difference_immediately están vinculados al ámbito de la suscripción y se aplican automáticamente a futuras renovaciones. Son distintos de las ventajas de Credit-Based Billing.

Cuando un cliente reduce su plan con difference_immediately, el valor no utilizado se convierte en un crédito vinculado a la suscripción que compensa automáticamente futuras renovaciones:

`full_immediately`

Cobra inmediatamente el importe completo del nuevo plan, ignorando el tiempo restante. Ideal para reiniciar los ciclos de facturación.

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_monthly',
  quantity: 1,
  proration_billing_mode: 'full_immediately'
});

`do_not_bill`

Cambia al nuevo plan sin ningún ajuste de facturación. No hay cargos de prorrateo ni créditos: el cliente simplemente pasa al nuevo plan. Ideal para migraciones de cortesía, cambios a planes gratuitos o situaciones en las que quieras asumir la diferencia de coste.

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_new_plan',
  quantity: 1,
  proration_billing_mode: 'do_not_bill'
});

Example: Prorated upgrade calculation

Escenario: Un cliente del plan Basic (

30/mes) mejora a Pro (

80/mes) el día 16 de un ciclo de 30 días usando prorated_immediately.

Unused credit from Basic = $30 × (15 remaining / 30 total) = $15.00
Prorated cost of Pro     = $80 × (15 remaining / 30 total) = $40.00
────────────────────────────────────────────────────────────────────
Immediate charge         = $40.00 − $15.00 = $25.00

Próxima renovación el 15 de febrero (16 de enero + 30 días): $80.00/mes.

Para ver ejemplos de cálculo más detallados y casos límite, consulta nuestra guía completa de mejoras y reducciones.

Example: Downgrade credit calculation

Escenario: Un cliente del plan Pro (

80/mes) reduce a Starter (

20/mes) usando difference_immediately.

Credit = Old plan − New plan = $80 − $20 = $60.00

El crédito de $60 se aplica automáticamente a futuras renovaciones:

Renovación 1: $20 −$ 20 (crédito) = ** $0.00** (quedan$ 40 de crédito)
Renovación 2: $20 −$ 20 (crédito) = ** $0.00** (quedan$ 20 de crédito)
Renovación 3: $20 −$ 20 (crédito) = $0.00 (crédito agotado)
Renovación 4: $20.00 (precio completo)

Obtén más información sobre la gestión de créditos en la guía de mejoras y reducciones.

Cambiar de plan con complementos

Modifica los complementos al cambiar de plan. Los complementos se incluyen en los cálculos de prorrateo:

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [{ addon_id: 'addon_extra_seats', quantity: 2 }]  // Add add-ons
  // addons: []  // Empty array removes all existing add-ons
});

De forma predeterminada (effective_at: 'immediately'), los cambios de plan generan cargos inmediatos. Pasa effective_at: 'next_billing_date' para programar el cambio para la próxima fecha de facturación; el cambio pendiente se devuelve en la suscripción como scheduled_change, y puedes cancelarlo con Cancelar cambio de plan programado. Los cargos fallidos pueden cambiar la suscripción al estado on_hold, a menos que pases on_payment_failure: 'prevent_change', lo que mantiene la suscripción en su plan actual hasta que el pago se complete correctamente. Realiza un seguimiento de los cambios mediante eventos de webhook subscription.plan_changed.

Vista previa de los cambios de plan

Antes de confirmar un cambio de plan, previsualiza el cargo exacto y la suscripción resultante:

const preview = await client.subscriptions.previewChangePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

// Show customer the charge before confirming
console.log('You will be charged:', preview.immediate_charge.summary);

Preview Change Plan API

Previsualiza los cambios de plan antes de confirmarlos.

Pausar y reanudar suscripciones

Pausar congela una suscripción en lugar de finalizarla. La facturación se detiene, el acceso se revoca y la suscripción conserva su plan y su historial para que el cliente pueda continuar exactamente donde lo dejó. Úsalo como alternativa de retención a la cancelación. Abre cualquier suscripción activa en Ventas → Suscripciones y haz clic en Pausar suscripción. El estado cambia a paused y las renovaciones se detienen hasta que se reanude la suscripción.

Qué ocurre al pausar

Las renovaciones se detienen. No se genera ninguna factura ni se intenta realizar ningún cargo de renovación mientras la suscripción está pausada.
El acceso se revoca inmediatamente. Pausar revoca todos los otorgamientos de derechos entregados y pendientes de la suscripción, lo que deshabilita sus claves de licencia y evita que se emitan nuevas URL de descarga de productos digitales. Al reanudar, se vuelven a otorgar, del mismo modo que al recuperarse de on_hold.
El reloj de facturación se congela. next_billing_date y expires_at avanzan ambos exactamente durante la duración de la pausa, para que el cliente conserve el tiempo que ya pagó.
No hay un límite de duración de la pausa. Una suscripción pausada permanece pausada hasta que alguien la reanuda. No se establece por adelantado la duración de la pausa.

Pausar revoca el acceso de inmediato, no al final del periodo de facturación. Si una suscripción controla el acceso a tu producto, comunícaselo claramente al cliente antes de que confirme.

Reanudar devuelve la suscripción a active y restaura sus derechos. Como el reloj estuvo congelado, la próxima renovación ocurre más tarde de lo programado originalmente, exactamente por la duración de la pausa; una suscripción pausada durante 12 días se renueva 12 días más tarde.

Pausar suscripciones basadas en uso

Una suscripción basada en uso puede tener uso registrado pero aún no facturado en el momento en que se pausa. Facturar uso al pausar, en Configuración → Suscripciones, determina qué ocurre con él:

Configuración	Comportamiento
Activado (predeterminado)	Dodo Payments emite una factura por el uso acumulado desde la última fecha de facturación y lo cobra inmediatamente.
Desactivado	El uso adeudado se transfiere y se factura en la próxima factura habitual de la suscripción.

Solo el uso medido se liquida de esta forma; la tarifa base recurrente nunca se cobra al pausar. Las suscripciones estándar y bajo demanda no tienen nada que liquidar, por lo que esta configuración no les afecta.

Facturar uso al pausar se registra por ciclo de facturación. Cambiarlo a mitad del ciclo no modifica la forma en que se liquida el ciclo que ya está en curso; el nuevo valor se aplica a partir del siguiente ciclo.

La factura de liquidación se cobra como cualquier otra factura, por lo que puede fallar. Si permanece impagada después del periodo de gracia de dunning, la suscripción pasa a on_hold y sigue marcada como pausada.

Una suscripción en ese estado tiene dos formas de salir, que se diferencian en quién absorbe el uso adeudado:

Salida	Resultado
Se paga la factura de liquidación	La suscripción vuelve a `paused`, no a `active`. Reanúdala explícitamente cuando el cliente esté listo.
La reanudas directamente	La suscripción pasa directamente a `active` y la factura de liquidación impagada se anula, junto con sus reintentos pendientes. El uso adeudado se da de baja contablemente.

Reanudar es una salida válida de esta retención; no tienes que cobrar primero la factura de liquidación. Ten en cuenta que reanudar perdona el uso pendiente en lugar de aplazarlo.

Permitir que los clientes pausen sus propias suscripciones

Permitir pausar suscripciones, en Configuración → Suscripciones, controla si los clientes pueden pausar y reanudar desde el Customer Portal. Está desactivado de forma predeterminada, por lo que la pausa de autoservicio debe habilitarse explícitamente.

Esta configuración solo controla el Customer Portal. Siempre puedes pausar y reanudar desde el dashboard o la API, independientemente de cómo esté configurado el interruptor. Desactivarla impide que los clientes realicen nuevas pausas, pero no deja atrapado a un cliente que ya está pausado: todavía puede reanudar una pausa que inició por sí mismo. Las pausas que iniciaste permanecen bajo tu control.

Pausing from the Customer Portal

Consulta lo que ve el cliente, incluido el diálogo de confirmación.

Pausar mediante la API

Pausar y reanudar se realizan mediante un único campo pause en el endpoint de actualización de suscripciones. No existe un endpoint de pausa separado.

// Pause
await client.subscriptions.update('sub_123', { pause: true });

// Resume
await client.subscriptions.update('sub_123', { pause: false });

pause es exclusivo respecto a cualquier otro campo: enviarlo junto con cualquier otra cosa se rechaza con 422. Establecer status en paused no pausa una suscripción; utiliza en su lugar el campo pause.

Pausar emite subscription.paused y reanudar emite subscription.unpaused. Ambos incluyen el objeto completo de la suscripción, con paused_at establecido mientras está pausada y null una vez reanudada.

Pausas y otras acciones de suscripción

La cancelación sigue funcionando. Puedes cancelar una suscripción pausada exactamente igual que una activa. Cualquier factura de liquidación abierta derivada de la pausa se anula al hacerlo.
Los cambios de plan programados se retrasan, no se descartan. Un cambio de plan programado para la próxima fecha de facturación permanece intacto mientras la suscripción está pausada y se aplica en la fecha de facturación desplazada una vez que se reanuda. Su scheduled_change.effective_at es una instantánea del momento en que se programó y no se ajusta por la pausa, por lo que puede mostrar una fecha pasada; interprétalo como «estaba programado para», no como una fecha garantizada. Para descartar el cambio en lugar de mantenerlo, utiliza Cancelar cambio de plan programado.

Estados de las suscripciones

Una suscripción pasa por un conjunto definido de estados durante su ciclo de vida. Esta tabla sirve de referencia para cada estado, qué lo provoca y cómo (o si) puedes recuperarlo.

Estado	Significado	¿Se puede recuperar?	Ruta de recuperación / siguiente paso
`pending`	La suscripción se está creando o procesando	—	Espera a `subscription.active` (o `subscription.failed`)
`active`	La suscripción está activa y se renovará automáticamente	—	No se necesita ninguna acción
`on_hold`	Falló un pago de renovación (o un cargo por cambio de plan); las renovaciones se han detenido	Sí	Actualiza el método de pago para reactivarla, automáticamente mediante Payment Retries y Dunning, o manualmente mediante la API de actualización del método de pago
`paused`	Tú o el cliente pausaron deliberadamente la suscripción; la facturación está congelada y el acceso revocado	Sí	Reanúdala con `pause: false` o desde el Customer Portal cuando la pausa de autoservicio esté habilitada; consulta Pausar y reanudar suscripciones
`cancelled`	La suscripción se canceló y no se renovará	Solo volver a comprar	El cliente debe iniciar una nueva suscripción; Dunning puede impulsar una nueva compra
`failed`	Falló la creación de la suscripción (el mandato o pago inicial no se completó correctamente)	No — terminal	El cliente debe crear una nueva suscripción con un método de pago válido
`expired`	La suscripción llegó al final de su plazo	—	El cliente debe iniciar una nueva suscripción si lo desea

on_hold e failed suelen confundirse. on_hold es un estado recuperable para una suscripción ya activa cuya renovación falló. failed es un estado terminal que solo ocurre cuando falla la creación inicial de la suscripción; no se puede reactivar.

on_hold e paused también son distintos. on_hold es involuntario: falló un pago. paused es deliberado: tú o el cliente decidieron congelar la suscripción, y no se intenta ninguna renovación mientras permanezca pausada. Una suscripción basada en uso todavía puede adeudar una factura de liquidación única en el momento en que se pausa; consulta Pausar suscripciones basadas en uso.

Máquina de estados

Estado retenido

Una suscripción entra en el estado on_hold cuando:

Falla un pago de renovación (fondos insuficientes, tarjeta caducada, etc.)
Falla un cargo por cambio de plan
Falla la autorización del método de pago
Una factura de liquidación de pausa de una suscripción basada en uso queda impagada

Cuando una suscripción está en el estado on_hold, no se renovará automáticamente. Debes actualizar el método de pago para reactivarla.

Reactivar desde el estado retenido

Para reactivar una suscripción desde el estado on_hold, actualiza el método de pago. Esto automáticamente:

Crea un cargo por las cuotas restantes
Genera una factura
Procesa el pago utilizando el nuevo método de pago
Reactiva la suscripción al estado active cuando el pago se realiza correctamente

La única excepción es una retención causada por una factura de liquidación de pausa impagada. Saldar esa factura devuelve la suscripción a paused, no a active, porque la pausa era el estado anterior al fallo del pago. Reanúdala explícitamente una vez liquidada la factura.

// Reactivate subscription from on_hold
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

// For on_hold subscriptions, a charge is automatically created
if (response.payment_id) {
  console.log('Charge created:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
  // Monitor webhooks for payment.succeeded and subscription.active
}

Después de actualizar correctamente el método de pago de una suscripción on_hold, recibirás los eventos webhook payment.succeeded seguidos de subscription.active.

Eventos webhook por transición

Cada transición emite un webhook para que puedas gestionar la lógica de derechos sin sondeos:

Transición	Evento
Suscripción activada	`subscription.active`
Renovación correcta	`subscription.renewed`
Renovación fallida → retenida	`subscription.on_hold`
Suscripción pausada	`subscription.paused`
Suscripción pausada reanudada	`subscription.unpaused`
Creación fallida	`subscription.failed`
Plan actualizado o degradado	`subscription.plan_changed`
Cancelada	`subscription.cancelled`
Plazo finalizado	`subscription.expired`
Cambios en cualquier campo	`subscription.updated`

Subscription Webhook Payloads

Consulta el esquema completo de carga útil para los eventos del ciclo de vida de las suscripciones.

Gestión mediante API

Create subscriptions

Usa POST /checkouts para crear suscripciones mediante programación a partir de productos, con pruebas opcionales (subscription_data.trial_period_days) y complementos (product_cart[].addons).

POST /subscriptions está obsoleto. Las integraciones existentes siguen funcionando, pero las nuevas deben usar Checkout Sessions.

API Reference

Consulta la API para crear una sesión de checkout.

Update subscriptions

Usa PATCH /subscriptions/{subscription_id} para cancelar en la próxima fecha de facturación, ampliar el periodo de la suscripción, actualizar los datos de facturación o modificar los metadatos. Para cambiar la cantidad, utiliza la API de cambio de plan; PATCH no acepta quantity.

API Reference

Aprende a actualizar los datos de una suscripción.

Pause and resume subscriptions

La pausa y la reanudación utilizan el mismo endpoint PATCH /subscriptions/{subscription_id} mediante el campo pause: pause: true pausa una suscripción activa y pause: false la reanuda. El campo no se puede combinar con ningún otro campo en la misma solicitud. Para conocer el comportamiento completo, los efectos de facturación y la configuración empresarial relacionada, consulta Pausar y reanudar suscripciones.

API Reference

Consulta la API de actualización de suscripciones, incluido el campo pause.

Change plans (proration)

Cambia el producto activo y las cantidades con controles de prorrateo.

API Reference

Revisa las opciones de cambio de plan.

On‑demand charges

Para suscripciones bajo demanda, cobra importes específicos bajo demanda.

API Reference

Cobra una suscripción bajo demanda.

List and retrieve

Usa GET /subscriptions para enumerar todas las suscripciones y GET /subscriptions/{id} para recuperar una.

API Reference

Consulta las API de listado y recuperación.

Usage history

Obtén el uso registrado para modelos de precios medidos o híbridos.

API Reference

Consulta la API del historial de uso.

Update payment method

Actualiza el método de pago de una suscripción. En las suscripciones activas, esto actualiza el método de pago para futuras renovaciones. En las suscripciones en estado on_hold, reactiva la suscripción al crear un cargo por las cuotas restantes.Al generar un nuevo enlace de método de pago (el tipo de solicitud New), puedes pasar allowed_payment_method_types para limitar los métodos de pago que el cliente ve en esa página. Los clientes nunca verán un método que no esté en la lista, aunque incluir un método no garantiza que aparezca (la disponibilidad también depende de factores como la ubicación del cliente y la configuración de tu empresa).

API Reference

Aprende a actualizar métodos de pago y reactivar suscripciones.

Casos de uso habituales

SaaS y API: Acceso por niveles con complementos para puestos o uso
Contenido y medios: Acceso mensual con pruebas introductorias
Planes de soporte B2B: Contratos anuales con complementos de soporte premium
Herramientas y plugins: Claves de licencia y versiones publicadas

Ejemplos de integración

Checkout Sessions (suscripciones)

Al crear sesiones de checkout, incluye tu producto de suscripción y los complementos opcionales:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_subscription',
      quantity: 1
    }
  ]
});

Cambios de plan con prorrateo

Actualiza o degrada una suscripción y controla el comportamiento del prorrateo:

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});

Cancelar en la próxima fecha de facturación

Programa una cancelación que surta efecto al final del periodo de facturación actual:

await client.subscriptions.update('sub_123', {
  cancel_at_next_billing_date: true
});

Ampliar el periodo de la suscripción

Amplía la duración de una suscripción pasando un nuevo subscription_period_count y subscription_period_interval a PATCH /subscriptions/{subscription_id}. La fecha de vencimiento de la suscripción se recalcula a partir del nuevo número y el intervalo; por ejemplo, para conceder tiempo adicional a un cliente en su plan actual:

await client.subscriptions.update('sub_123', {
  subscription_period_count: 5,
  subscription_period_interval: 'Month'
});

El periodo de una suscripción solo puede aumentarse, nunca acortarse.

Suscripciones bajo demanda

Crea una suscripción bajo demanda y cobra más adelante según sea necesario:

const onDemand = await client.subscriptions.create({
  customer: { customer_id: 'cus_123' },
  billing: { country: 'US' },
  product_id: 'pdt_on_demand',
  quantity: 1,
  on_demand: { mandate_only: true }
});

await client.subscriptions.charge(onDemand.subscription_id, {
  product_price: 4900,
  product_currency: 'USD',
  product_description: 'Extra usage for September'
});

Actualizar el método de pago de una suscripción activa

Actualiza el método de pago de una suscripción activa:

// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

// Or use existing payment method
await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'existing',
    payment_method_id: 'pm_abc123'
  }
});

Reactivar una suscripción desde on_hold

Reactiva una suscripción que quedó retenida debido a un pago fallido:

// Update payment method - automatically creates charge for remaining dues
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

if (response.payment_id) {
  // Charge created for remaining dues
  // Redirect customer to response.payment_link
  // Monitor webhooks: payment.succeeded → subscription.active
}

Suscripciones con mandatos compatibles con RBI

Las suscripciones UPI y con tarjetas de la India funcionan bajo las regulaciones de RBI (Reserve Bank of India), con requisitos específicos para los mandatos:

Límites de los mandatos

El tipo y el importe del mandato dependen del cargo recurrente de tu suscripción:

Cargos inferiores al mínimo del mandato (₹15.000 de forma predeterminada): Creamos un mandato bajo demanda por el importe mínimo. El importe de la suscripción se cobra periódicamente según la frecuencia de tu suscripción, hasta el límite del mandato.
Cargos iguales o superiores al mínimo del mandato: Creamos un mandato de suscripción (o un mandato bajo demanda) por el importe exacto de la suscripción.

El mínimo del mandato se puede configurar por comerciante o por solicitud mediante mandate_min_amount_inr_paise (paise de INR). El importe registrado en el banco es max(mandate_floor, billing_amount), por lo que el mínimo se convierte efectivamente en el límite de autorización visible para el cliente cuando la facturación es inferior. Para obtener información detallada sobre los mandatos compatibles con RBI y el mínimo configurable de los mandatos para métodos de pago de la India, consulta la página Métodos de pago de la India.

Consideraciones sobre actualizaciones y degradaciones

Importante: Al actualizar o degradar suscripciones, considera cuidadosamente los límites de los mandatos:

Si una actualización o degradación genera un importe superior a 15.000 Rs y supera el límite de pago bajo demanda existente, el cargo de la transacción puede fallar.
En estos casos, el cliente puede tener que actualizar su método de pago o volver a cambiar la suscripción para establecer un nuevo mandato con el límite correcto.

Autorización para cargos de importe elevado

Para cargos de suscripción de 15.000 Rs o más:

El banco solicitará al cliente que autorice la transacción.
Si el cliente no autoriza la transacción, esta fallará y la suscripción quedará retenida.

Retraso de procesamiento de 48 horas

Cronología del procesamiento: Los cargos recurrentes de las tarjetas de la India y las suscripciones UPI siguen un patrón de procesamiento particular:

Los cargos se inician en la fecha programada según la frecuencia de tu suscripción.
La deducción real de la cuenta del cliente solo ocurre después de 48 horas desde el inicio del pago.
Este periodo de 48 horas puede extenderse hasta 2-3 horas adicionales, según las respuestas de la API del banco.

Ventana de cancelación del mandato

Durante la ventana de procesamiento de 48 horas:

Los clientes pueden cancelar el mandato mediante sus aplicaciones bancarias.
Si un cliente cancela el mandato durante este periodo, la suscripción permanecerá activa (es un caso límite específico de las suscripciones AutoPay con tarjetas de la India y UPI).
Sin embargo, la deducción real puede fallar y, en ese caso, la suscripción quedará retenida.

Gestión de casos límite: Si proporcionas beneficios, créditos o uso de la suscripción a los clientes inmediatamente después de iniciar el cargo, debes gestionar adecuadamente este periodo de 48 horas en tu aplicación. Considera lo siguiente:

Retrasar la activación de beneficios hasta la confirmación del pago
Implementar periodos de gracia o acceso temporal
Supervisar el estado de la suscripción para detectar cancelaciones de mandatos
Gestionar los estados de retención de suscripciones en la lógica de tu aplicación

Supervisa los webhooks de suscripciones para hacer seguimiento de los cambios en el estado de los pagos y gestionar casos límite en los que los mandatos se cancelan durante la ventana de 48 horas.

Prácticas recomendadas

Empieza con niveles claros: 2–3 planes con diferencias evidentes
Comunica los precios: Muestra los totales, el prorrateo y la próxima renovación
Usa las pruebas con criterio: Convierte clientes mediante la incorporación, no solo mediante el tiempo
Aprovecha los complementos: Mantén sencillos los planes base y ofrece extras como venta adicional
Prueba los cambios: Valida los cambios de plan y el prorrateo en modo de prueba

Las suscripciones son una base flexible para generar ingresos recurrentes. Empieza de forma sencilla, realiza pruebas exhaustivas y repite el proceso según las métricas de adopción, abandono y expansión.

Última modificación el 21 de agosto de 2026

Upgrade & Downgrade

On‑Demand Subscriptions

Customer Portal

Subscription Webhooks

​What Are Subscriptions?

​Key Benefits

​Creating Subscriptions

​Subscription product creation

​Product details

​Pricing

​Advanced settings

​Subscription Trials

​Configuring Trials

​Pruebas de pago

​Prevención del uso indebido de pruebas

​Detección del estado de una prueba

​Actualización del periodo de prueba

​Cambios del plan de suscripción

Product Collections

​Modos de prorrateo

​prorated_immediately

​difference_immediately

​full_immediately

​do_not_bill

​Cambiar de plan con complementos

​Vista previa de los cambios de plan

Preview Change Plan API

​Pausar y reanudar suscripciones

​Qué ocurre al pausar

​Pausar suscripciones basadas en uso

​Permitir que los clientes pausen sus propias suscripciones

Pausing from the Customer Portal

​Pausar mediante la API

​Pausas y otras acciones de suscripción

​Estados de las suscripciones

​Máquina de estados

​Estado retenido

​Reactivar desde el estado retenido

​Eventos webhook por transición

Subscription Webhook Payloads

​Gestión mediante API

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

​Casos de uso habituales

​Ejemplos de integración

​Checkout Sessions (suscripciones)

​Cambios de plan con prorrateo

​Cancelar en la próxima fecha de facturación

​Ampliar el periodo de la suscripción

​Suscripciones bajo demanda

​Actualizar el método de pago de una suscripción activa

​Reactivar una suscripción desde on_hold

​Suscripciones con mandatos compatibles con RBI

​Límites de los mandatos

​Consideraciones sobre actualizaciones y degradaciones

​Autorización para cargos de importe elevado

​Retraso de procesamiento de 48 horas

​Ventana de cancelación del mandato

​Prácticas recomendadas

What Are Subscriptions?

Key Benefits

Creating Subscriptions

Subscription product creation

Product details

Pricing

Advanced settings

Subscription Trials

Configuring Trials

Pruebas de pago

Prevención del uso indebido de pruebas

Detección del estado de una prueba

Actualización del periodo de prueba

Cambios del plan de suscripción

Modos de prorrateo

`prorated_immediately`

`difference_immediately`

`full_immediately`

`do_not_bill`

Cambiar de plan con complementos

Vista previa de los cambios de plan

Pausar y reanudar suscripciones

Qué ocurre al pausar

Pausar suscripciones basadas en uso

Permitir que los clientes pausen sus propias suscripciones

Pausar mediante la API

Pausas y otras acciones de suscripción

Estados de las suscripciones

Máquina de estados

Estado retenido

Reactivar desde el estado retenido

Eventos webhook por transición

Gestión mediante API

Casos de uso habituales

Ejemplos de integración

Checkout Sessions (suscripciones)

Cambios de plan con prorrateo

Cancelar en la próxima fecha de facturación

Ampliar el periodo de la suscripción

Suscripciones bajo demanda

Actualizar el método de pago de una suscripción activa

Reactivar una suscripción desde on_hold

Suscripciones con mandatos compatibles con RBI

Límites de los mandatos

Consideraciones sobre actualizaciones y degradaciones

Autorización para cargos de importe elevado

Retraso de procesamiento de 48 horas

Ventana de cancelación del mandato

Prácticas recomendadas