Subscriptions - Dodo Payments Documentation

Las suscripciones automatizan los ingresos recurrentes. Crea ciclos de facturación flexibles, pruebas gratuitas o de pago, cambios de plan con prorrateo y complementos. Los clientes renuevan automáticamente hasta que cancelan o finaliza el plazo.

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?

Una suscripción es un producto recurrente que cobra a los clientes según un calendario. Es ideal para SaaS, membresías, contenido digital y planes de soporte.

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

Ingresos predecibles: Facturación recurrente con renovaciones automatizadas
Ciclos flexibles: Intervalos mensuales, anuales, personalizados y pruebas
Agilidad de los planes: Prorrateo para mejoras y reducciones de plan
Complementos y plazas: Añade mejoras opcionales y cuantificables
Checkout alojado: Páginas de checkout y Customer Portal
Orientado a desarrolladores: APIs claras para creación, cambios y seguimiento del uso

Creating Subscriptions

Crea productos de suscripción en tu panel de Dodo Payments y luego véndelos mediante checkout o tu API. Separar los productos de las suscripciones activas te permite versionar los precios, añadir complementos y realizar un seguimiento independiente del rendimiento.

Creación de productos de suscripción

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.

Detalles del producto

Nombre del producto (obligatorio): El nombre que se muestra en el checkout, el Customer Portal y las facturas.
Descripción del producto (opcional): Una declaración clara del valor que aparece en el checkout y las facturas.
Imagen del producto (opcional): PNG/JPG/WebP de hasta 3 MB. Se utiliza en el checkout y las facturas.
Marca: Asocia el producto con una marca específica para aplicar temas y enviar correos electrónicos.
Categoría fiscal (obligatoria): Elige la categoría (por ejemplo, SaaS) para determinar las reglas fiscales.

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.
Price (obligatorio): Precio recurrente base con moneda. Un precio distinto de cero debe ser de al menos $1 (o su equivalente en la moneda elegida); no se admiten importes inferiores a este mínimo. Un precio exactamente de $0 es un caso independiente y compatible; consulta Card-Optional at Zero Price.
Discount Applicable (%): Descuento porcentual opcional aplicado al precio base; se refleja en el checkout y las facturas.
Repeat payment every (obligatorio): Intervalo de las renovaciones, por ejemplo, cada 1 Month. Selecciona la frecuencia (meses o años) y la cantidad.
Subscription Period (obligatorio): Plazo total durante el que la suscripción permanece activa (por ejemplo, 10 Years). Cuando finaliza este periodo, las renovaciones se detienen salvo que se amplíe.
Trial Period Days (obligatorio): Define la duración de la prueba en días. Usa 0 para desactivar las pruebas. El primer cargo se realiza automáticamente cuando termina la prueba.
Trial Amount: Cargo inicial opcional para una prueba de pago. Déjalo sin definir para una prueba gratuita. Consulta Paid Trials.
Card-optional at $0 Price: Permite que los clientes inicien la suscripción sin añadir una tarjeta cuando el precio es de $0 o un descuento deja el importe de hoy en cero. Una prueba gratuita tiene su propia casilla Start the trial without a card. Consulta Card-Optional at Zero Price.
Select add-on: Añade hasta 10 complementos que los clientes puedan comprar junto con el plan base.

Editar el precio de un producto activo cambia lo que pagan los clientes nuevos. Las suscripciones existentes nunca se vuelven a calcular: cada una conserva el precio con el que se creó y se renueva con ese precio mientras permanezca activa.Para pasar a un suscriptor existente a otro precio, cambia su plan explícitamente con Change Plan, o permite que lo cambie mediante el Customer Portal si has habilitado los cambios de plan de autoservicio. La configuración de prorrateo se aplica a ese cambio de plan, no a las ediciones del precio del producto.

Los complementos son ideales para extras cuantificables, como plazas o almacenamiento. Puedes controlar las cantidades permitidas y el comportamiento del prorrateo cuando los clientes los modifican.

Configuración avanzada

Precios con impuestos incluidos: Muestra los precios con los impuestos aplicables incluidos. El cálculo final de impuestos sigue variando según la ubicación del cliente.
Generar claves de licencia: Emite una clave única para cada cliente después de la compra. Consulta la guía de License Keys.
Entrega de productos digitales: Entrega archivos o contenido automáticamente después de la compra. Obtén más información en Digital Product Delivery.
Metadata: Adjunta pares clave-valor personalizados para etiquetado interno o integraciones con clientes. Consulta Metadata.

Usa metadata para almacenar identificadores de tu sistema (por ejemplo, accountId) y poder conciliar eventos y facturas posteriormente.

Pruebas de Subscription

Las pruebas permiten que los clientes evalúen una suscripción antes de pagar el precio recurrente completo. Una prueba puede ser gratuita (sin cargos hasta que finalice) o de pago (se cobra por adelantado un importe reducido). Después de la prueba, el precio completo se cobra en la primera renovación.

Configurar pruebas

Define Trial Period Days en la sección de precios del producto (usa 0 para desactivarlo). Sobrescríbelo al crear una suscripción:

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

// Via subscription creation (deprecated)
// Note: POST /subscriptions is deprecated — prefer checkout sessions
const subscription = await client.subscriptions.create({
  customer: { customer_id: 'cus_123' },
  billing: { country: 'US' },
  product_id: 'pdt_monthly',
  quantity: 1,
  trial_period_days: 14
});

trial_period_days debe estar entre 0 y 10.000 días.

Pruebas de pago

Cobra por adelantado un importe reducido durante el periodo de prueba. Define Trial Amount en el precio del producto. El precio recurrente completo se cobra en la primera renovación.

Formulario de precios de una suscripción con la duración de la 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 checkout session:

Campo	Tipo	Descripción
`trial_amount`	integer	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`	boolean	Indica si los códigos de descuento del checkout reducen el cargo de la prueba. De forma predeterminada es `false`, por lo que el importe de la prueba se cobra íntegramente aunque se aplique 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_bps: 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,
    trial_amount: 500,                // $5.00 charged today
    trial_apply_discounts: false
  }
});

El importe de la prueba está sujeto a impuestos y se incluye en los cálculos del checkout y en los precios de los payment links. El recargo de Adaptive Currency se aplica por moneda. El endpoint de previsualización devuelve trial_amount y trial_period_days para que puedas mostrar el importe a pagar hoy antes de crear la suscripción.

Card-Optional at Zero Price

Permite que los clientes inicien una suscripción sin añadir un método de pago cuando no deben pagar nada hoy. Actívalo por precio en la sección de precios del producto, con una casilla para cada caso indicado a continuación.

Formulario de precios de suscripción con la casilla Card-Optional at $0 Price junto a Trial Period y Default Discount

En dos casos no se debe pagar nada hoy:

Una prueba gratuita: trial_period_days está configurado sin trial_amount, por lo que el primer cargo es de $0 mientras dura la prueba. Marca Start the trial without a card en Trial Period (Days).
Un precio recurrente de $0: El precio es de $0 o un descuento lo reduce a $0 (el Default Discount (%) del producto o un código de descuento aplicado en el checkout). Marca Card-optional at $0 Price.

Una prueba de pago siempre requiere una tarjeta. Definir un Trial Amount significa que hay un importe pendiente, por lo que el requisito de tarjeta permanece activado.

Cada casilla corresponde a su propio campo de API: trial_payment_method_optional (caso de prueba gratuita) y zero_amount_payment_method_optional (caso de precio de $0). Puedes activar cualquiera de ellas de forma independiente.

Qué ocurre sin una tarjeta

Una suscripción con tarjeta opcional se crea y activa inmediatamente sin ningún método de pago registrado. La respuesta de creación devuelve payment_method_required: false y el objeto de suscripción muestra has_payment_method: false. Después:

Se envía un correo de recordatorio antes de que comience la facturación. El número de días se define en Settings → Subscriptions → Payment Method Reminder (consulta Subscription Settings). El correo Add Payment Method Reminder (consulta Customer Emails) dirige al cliente al Customer Portal para añadir una tarjeta.
Si no se añade una tarjeta a tiempo, la suscripción pasa a on_hold cuando finaliza la prueba o el periodo de descuento y se debe realizar un cargo real. El cliente recibe el correo Subscription On Hold, No Payment Method.
Añadir un método de pago reactiva la suscripción (consulta Reactivating from On Hold). Se crea un cargo por el importe pendiente y la suscripción vuelve a active si el pago se realiza correctamente.

Pestaña de configuración de suscripciones que muestra el campo de días de Payment Method Reminder

Añadir una tarjeta antes de que termine la prueba o el periodo de descuento evita la suspensión. La siguiente renovación carga esa tarjeta.

Prevención del uso indebido de pruebas

Evita que los clientes reclamen repetidamente pruebas del mismo producto. Cuando esta opción está activada, un cliente que ya haya canjeado una prueba de un producto obtiene una suscripción de pago en lugar de una nueva prueba de ese producto.

Interruptor Prevent Trial Misuse en la pestaña de configuración de suscripciones

Actívalo desde Settings → Subscriptions. Una vez activado:

Los clientes se comparan mediante el correo electrónico normalizado (sin los alias con signo más), por lo que user+trial@example.com e user@example.com se consideran la misma persona.
Los canjes se registran al activar la prueba, por lo que un cliente que cancela ese mismo día ya ha consumido su prueba.
Los clientes existentes se completan retroactivamente a partir de las pruebas históricas por correo electrónico, de modo que los usuarios anteriores de pruebas se reconocen de inmediato.
Pasar trial_period_days explícitamente en una sesión de checkout o suscripción omite la comprobación y concede esa prueba.

Desactivado de forma predeterminada. Consulta Subscription Settings para conocer todos los controles de suscripción a nivel empresarial.

Detección del estado de prueba

El objeto de suscripción no tiene un campo de estado de prueba. Para una prueba gratuita, recupera los pagos de la suscripción: si existe exactamente un pago con un total_amount de 0, la suscripción está en periodo de prueba. Esta comprobación no funciona para pruebas de pago, en las que el primer pago es el trial_amount.

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

const isInTrial = payments.items.length === 1 && 
                  payments.items[0].total_amount === 0;

Esta comprobación solo funciona para pruebas gratuitas. En una prueba de pago, el primer pago equivale al importe de la prueba. Compara el primer pago con trial_amount de la suscripción o comprueba si next_billing_date todavía está 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 de plan de suscripción

Mejora o reduce suscripciones, ajusta cantidades o migra a otros productos. El modo de prorrateo controla si el cambio genera un cargo inmediato, crea crédito o no aplica ningún ajuste de facturación. Puedes cambiar planes y actualizar la siguiente fecha de facturación desde el panel, o cambiar planes con la API. Para permitir que los clientes cambien sus planes por sí mismos, añade productos de suscripción a una Product Collection y activa Allow Subscription Updates en Settings → Subscriptions.

Product Collections

Agrupa productos relacionados para activar rutas de mejora y reducción de plan en el Customer Portal.

Modos de prorrateo

Elige cómo se factura a los clientes al cambiar de plan:

Modo	Mejora	Reducción	Ciclo de facturación	Ideal para
`prorated_immediately`	Acredita el tiempo no utilizado y cobra el ciclo nuevo completo	Acredita el tiempo no utilizado y cobra el ciclo nuevo completo	Se restablece a hoy	Facturación justa basada en el tiempo
`difference_immediately`	Cobra la diferencia de precio	Acredita la diferencia de precio	Se restablece a hoy	Cambios de nivel sencillos
`full_immediately`	Cobra el precio completo del plan nuevo	Cobra el precio completo del plan nuevo	Se restablece a hoy	Restablecimiento del ciclo de facturación
`do_not_bill`	Cambia inmediatamente, sin cargo	Cambia inmediatamente, sin cargo	Permanece igual	Migraciones gratuitas

`prorated_immediately`

Acredita la parte no utilizada del ciclo de facturación actual y después cobra un ciclo completo del nuevo plan. El nuevo plan nunca se cobra como una fracción de su precio. Cargo inmediato neto = (ciclo nuevo completo) menos (fracción restante × ciclo antiguo completo). Si el crédito supera el cargo del ciclo nuevo, la diferencia se conserva como crédito asociado a la suscripción para futuras renovaciones. El ciclo de facturación se vuelve a anclar a la fecha del cambio.

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).

// Upgrade: charges $50 (difference between $30 and $80)
// Downgrade: credits the price difference, 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 están asociados a 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 asociado a la suscripción que compensa automáticamente futuras renovaciones:

`full_immediately`

Cobra inmediatamente el importe completo del nuevo plan, ignorando el tiempo restante. Es ideal para restablecer 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 inmediatamente al nuevo plan sin ningún ajuste de facturación. No hay cargos ni créditos. El nuevo plan queda activo en cuanto la llamada se completa correctamente, pero no se cobra hasta la siguiente renovación. El cliente disfruta del plan mejorado de forma gratuita durante el resto del ciclo actual. Se conserva la fecha de renovación original y el precio del nuevo plan se aplica en esa renovación.

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 con Basic ($30/mes) mejora a Pro ($80/mes) el día 16 de un ciclo de 30 días usando prorated_immediately.

Credit for unused time on Basic = $30 × (15 remaining / 30 total) = $15.00
Full cycle of Pro               = $80.00 (never prorated)
────────────────────────────────────────────────────────────────────
Immediate charge                = $80.00 − $15.00 = $65.00

El cliente comienza hoy un mes completo nuevo de Pro, por lo que Pro se cobra íntegramente y solo se acredita el tiempo no utilizado de Basic.Siguiente renovación el 15 de febrero (16 de enero + 30 días): $80.00/mes.

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

Example: Downgrade credit calculation

Escenario: Un cliente con 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 de plan.

Cambio de planes 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 }]
  // 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 siguiente fecha de facturación; el cambio pendiente se devuelve en la suscripción como scheduled_change y puedes cancelarlo con Cancel Scheduled Plan Change. Los cargos fallidos pueden mover la suscripción al estado on_hold, salvo que pases on_payment_failure: 'prevent_change', que mantiene la suscripción en su plan actual hasta que el pago se realice correctamente. Realiza un seguimiento de los cambios mediante eventos de webhook subscription.plan_changed. Los cambios de plan se rechazan mientras una suscripción está en past_due; consulta Grace Period.

Previsualización de cambios de plan

Previsualiza el cargo exacto antes de confirmarlo:

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

console.log('You will be charged:', preview.immediate_charge.summary.total_amount, preview.immediate_charge.summary.currency);

Preview Change Plan API

Previsualiza los cambios de plan antes de confirmarlos.

Pausar y reanudar suscripciones

Pausa una suscripción para congelarla en lugar de finalizarla. La facturación se detiene, el acceso se revoca y la suscripción conserva su plan y su historial. Úsala como alternativa de retención a la cancelación. Abre cualquier suscripción activa en Sales → Subscriptions y haz clic en Pause subscription. El estado cambia a paused y las renovaciones se detienen hasta que se reanude.

Qué ocurre al pausar

Las renovaciones se detienen. No se genera ninguna factura ni se intenta realizar ningún cargo de renovación mientras está pausada.
El acceso se revoca inmediatamente. Pausar revoca todas las concesiones de derechos entregadas y pendientes, lo que desactiva las claves de licencia y detiene las nuevas URL de descarga de productos digitales. Al reanudar, se vuelven a conceder.
El reloj de facturación se congela. next_billing_date e expires_at avanzan exactamente durante la duración de la pausa, por lo que el cliente conserva el tiempo que ya había pagado.
No hay límite de duración de la pausa. Una suscripción pausada permanece pausada hasta que se reanuda. No defines por adelantado la duración de la pausa.

Pausar revoca el acceso inmediatamente, no al final del periodo de facturación. Comunícaselo claramente al cliente antes de que confirme.

Al reanudar, la suscripción vuelve a active y se restauran las concesiones. Como el reloj estaba congelado, la siguiente renovación se produce más tarde de lo programado originalmente, exactamente por la duración de la pausa.

Pausar suscripciones basadas en el uso

Una suscripción basada en el uso puede tener uso registrado pero todavía no facturado cuando se pausa. Bill Usage at Pause en Settings → Subscriptions controla lo que ocurre:

Configuración	Comportamiento
On (predeterminado)	Dodo Payments genera una factura por el uso acumulado desde la última fecha de facturación y la cobra inmediatamente.
Off	El uso pendiente se arrastra y se factura en la siguiente factura habitual.

Solo se liquida de esta forma el uso medido. La tarifa base recurrente nunca se cobra al pausar. Las suscripciones estándar y bajo demanda no tienen nada que liquidar.

Bill Usage at Pause se registra por ciclo de facturación. Cambiarlo a mitad del ciclo no afecta al ciclo 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 posibles salidas:

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é preparado.
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 pendiente se da de baja.

Reanudar es una salida válida de esta suspensión. No es necesario cobrar primero la factura de liquidación. Al reanudar, se perdona el uso pendiente en lugar de aplazarlo.

Permitir que los clientes pausen sus propias suscripciones

Allow Subscription Pause en Settings → Subscriptions 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 activarse explícitamente.

Esta configuración solo controla el Customer Portal. Siempre puedes pausar y reanudar desde el panel o la API. Desactivarla impide nuevas pausas de clientes, pero no afecta a un cliente que ya está en pausa. Este aún puede reanudar la pausa que inició. Las pausas que tú iniciaste siguen bajo tu control.

Pausing from the Customer Portal

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

Pausar mediante la API

La pausa y la reanudación se realizan mediante el campo status del endpoint de actualización de suscripciones:

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

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

Envía paused o active por separado. Combinar cualquiera de ellos con otro campo se rechaza con 422. El antiguo campo booleano pause se eliminó y siempre falla con 422, por lo que un cliente que todavía lo utilice recibe un error explícito en lugar de una operación sin efecto.

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.
Los cambios de plan programados se retrasan, no se descartan. Un cambio de plan programado para la siguiente fecha de facturación permanece intacto mientras la suscripción está pausada y se aplica en la fecha de facturación desplazada una vez reanudada. Su scheduled_change.effective_at es una instantánea del momento en que se programó y no se ajusta por la pausa. Para descartar el cambio, usa Cancel Scheduled Plan Change.

Estados de la suscripción

Una suscripción pasa por estados definidos durante su ciclo de vida:

Estado	Significado	¿Se puede recuperar?	Recuperación
`pending`	Se está creando o procesando	—	Espera a `subscription.active` o `subscription.failed`
`active`	Activa y se renovará automáticamente	—	No se requiere ninguna acción
`past_due`	El pago de renovación falló y el periodo de gracia está abierto; el cliente conserva el acceso completo	Sí	Liquida la deuda de renovación antes de la fecha límite (consulta Grace Period)
`on_hold`	Falló el cargo de renovación o cambio de plan; las renovaciones se detuvieron y el acceso se revocó	Sí	Recupera automáticamente mediante Payment Retries y Dunning, o actualiza el método de pago (consulta Reactivating from On Hold)
`paused`	Pausada deliberadamente por ti o por el cliente; la facturación está congelada y el acceso revocado	Sí	Reanuda con `status: active` o desde Customer Portal (consulta Pausing and Resuming Subscriptions)
`cancelled`	Cancelada y no se renovará	Solo mediante una nueva compra	El cliente debe iniciar una nueva suscripción; Dunning puede solicitar una nueva compra
`failed`	Falló la creación (el mandato inicial o el pago no se completó correctamente)	No — terminal	El cliente debe crear una nueva suscripción con un método de pago válido
`expired`	Llegó al final de su plazo	—	El cliente debe iniciar una nueva suscripción si lo desea

on_hold y failed suelen confundirse. on_hold se puede recuperar para una suscripción ya activa cuya renovación falló. failed es terminal y solo ocurre cuando falla la creación inicial de la suscripción.

past_due e on_hold son estados involuntarios, pero se diferencian en un aspecto: past_due conserva el acceso del cliente, mientras que on_hold lo elimina. Una suscripción solo llega a past_due cuando activas un periodo de gracia. Sin uno, una renovación fallida pasa directamente a on_hold.

on_hold e paused son distintos. on_hold es involuntario (el pago falló). paused es deliberado (tú o el cliente decidieron congelarlo). Una suscripción basada en el uso aún puede tener una factura de liquidación pendiente en el momento de pausarse (consulta Pausing Usage-Based Subscriptions).

Máquina de estados

Estado suspendido

Una suscripción entra en on_hold cuando:

Falla un pago de renovación (fondos insuficientes, tarjeta caducada, etc.)
Falla un cargo de 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 el uso queda impagada
Finaliza un periodo de gracia con deuda de renovación impagada y la acción de expiración es on_hold
Finaliza la prueba gratuita o el periodo de $0 de una suscripción Card-Optional at Zero Price sin que se haya añadido ningún método de pago

Si defines un periodo de gracia, una renovación fallida mueve primero la suscripción a past_due. Solo llega a on_hold cuando termina el periodo.

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

Reactivación desde el estado suspendido

Actualiza el método de pago para reactivar una suscripción desde on_hold. Esto automáticamente:

Crea un cargo por los importes pendientes
Genera una factura
Procesa el pago mediante el nuevo método de pago
Reactiva la suscripción a active cuando el pago se completa correctamente

La única excepción es una suspensión causada por una factura de liquidación de pausa impagada. Liquidar 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.

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

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 eventos de webhook payment.succeeded seguidos de subscription.active.

Periodo de gracia

Un periodo de gracia es una ventana entre una renovación fallida y la pérdida de acceso. La suscripción pasa a past_due en lugar de on_hold, y el cliente conserva todo lo que compró hasta que termina el periodo. Esto le da tiempo para solucionar el problema de una tarjeta sin perder tu producto. Desactivado de forma predeterminada. Actívalo desde Settings → Subscriptions → Subscription Grace Period.

Configuración

Configuración	Valores	Descripción
Subscription Grace Period	on / off	Activa el periodo de gracia para el negocio. Desactivado de forma predeterminada.
Number of days of grace period	1 to 30 days	Duración de la ventana. El valor predeterminado es de 3 días.
Status of subscription after grace period	`on_hold` or `cancel_subscription`	Qué ocurre cuando la ventana termina sin que se haya pagado.

Qué ocurre durante la ventana

Mientras una suscripción está en past_due:

El cliente conserva el acceso. Las concesiones de derechos, las claves de licencia y las descargas de productos digitales permanecen activas.
La facturación basada en el uso sigue registrando el uso.
La suscripción no se renueva.
La suscripción no se puede pausar.
Se envían correos de Dunning y continúan los reintentos de pago.
subscription.past_due se emite al entrar en este estado.

El webhook subscription.past_due incluye la fecha límite como past_due_ends_at. Guárdala cuando llegue el evento; la API de suscripciones no devuelve este campo. Cada webhook de suscripción mientras la ventana está abierta incluye el mismo valor, junto a un status de past_due.

La ventana queda fijada cuando la suscripción entra en ella. Si cambias después la duración o la acción de expiración, una ventana ya abierta conserva sus valores originales. Los valores nuevos se aplican a la siguiente suscripción que entre en una ventana.

Recuperación

La ventana se cierra cuando la deuda de renovación se liquida mediante un reintento correcto o cuando el cliente actualiza el método de pago. La suscripción vuelve a active y se envía un webhook subscription.active. Solo la renovación fallida abre una ventana. Un cargo independiente del comercio que queda impagado no mueve una suscripción a past_due.

Cuando termina la ventana

Si la deuda de renovación sigue impagada en la fecha límite, la suscripción pasa a on_hold o a cancelled, según la configuración. Al mismo tiempo:

Se cancela cualquier cambio de plan programado en la suscripción.
Se cancela cualquier cambio de plan pendiente cuya factura siga impagada.

Si la acción de expiración es cancel_subscription, las facturas abiertas también se anulan y se detienen sus reintentos de pago.

Un cambio de plan pendiente cuya factura se pagó se aplica mientras la ventana sigue abierta, no en la fecha límite. Una factura pagada liquida el cambio independientemente del estado de la suscripción.

Los cambios de plan se rechazan mientras una suscripción está en past_due. Liquida primero la deuda de renovación.

Eventos de webhook por transición

Cada transición emite un webhook para que puedas gestionar la lógica de concesión de derechos sin realizar consultas periódicas:

Transición	Evento
Suscripción activada	`subscription.active`
Renovación correcta	`subscription.renewed`
Renovación fallida, se abre el periodo de gracia	`subscription.past_due`
Renovación fallida → suspendida	`subscription.on_hold`
Suscripción pausada	`subscription.paused`
Suscripción pausada reanudada	`subscription.unpaused`
Creación fallida	`subscription.failed`
Plan mejorado o reducido	`subscription.plan_changed`
Cancelada	`subscription.cancelled`
Plazo finalizado	`subscription.expired`
Cualquier cambio de campo	`subscription.updated`

Subscription Webhook Payloads

Consulta el esquema completo de la carga útil de los eventos del ciclo de vida de la suscripción.

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 siguiente fecha de facturación, ampliar el periodo de suscripción, actualizar los datos de facturación o modificar los metadatos. Para cambiar la cantidad, usa la API de cambio de plan.

API Reference

Obtén información sobre cómo actualizar los detalles de una suscripción.

Pause and resume subscriptions

La pausa y la reanudación se realizan mediante el campo status en PATCH /subscriptions/{subscription_id}: status: paused pausa una suscripción activa y status: active la reanuda. Ninguno de los dos valores puede combinarse con otro campo en la misma solicitud. Consulta Pausing and Resuming Subscriptions para conocer todo el comportamiento y los efectos de facturación.

API Reference

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

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 e GET /subscriptions/{id} para recuperar una.

API Reference

Consulta las APIs 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 on_hold, reactiva la suscripción creando un cargo por los importes pendientes.Al generar un nuevo enlace de método de pago, puedes pasar allowed_payment_method_types para restringir los métodos de pago que ve el cliente. 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 depende de factores como la ubicación del cliente y la configuración de tu negocio).

API Reference

Obtén información sobre cómo actualizar métodos de pago y reactivar suscripciones.

Casos de uso habituales

SaaS y APIs: Acceso por niveles con complementos para plazas 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)

Crea una sesión de checkout con un producto de suscripción y complementos opcionales:

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

Cambios de plan con prorrateo

Mejora o reduce 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 siguiente fecha de facturación

Programa una cancelación que entre en vigor al final del periodo de facturación actual:

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

Ampliar el periodo de 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 expiración de la suscripción se recalcula a partir de la nueva cantidad y el intervalo:

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

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

Suscripciones bajo demanda

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

// Note: POST /subscriptions is deprecated — prefer checkout sessions
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:

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ó suspendida debido a un pago fallido:

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 de UPI y tarjetas indias funcionan conforme a las normativas 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 límite del mandato (₹15,000 de forma predeterminada): Creamos un mandato bajo demanda por el importe del límite. El importe de la suscripción se cobra periódicamente según su frecuencia, hasta alcanzar el límite del mandato.
Cargos iguales o superiores al límite del mandato: Creamos un mandato de suscripción (o un mandato bajo demanda) por el importe exacto de la suscripción.

El límite del mandato se puede configurar por comercio 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 límite se convierte efectivamente en el techo de autorización que ve el cliente cuando la facturación es inferior. Consulta India Payment Methods para obtener información detallada sobre los mandatos compatibles con RBI y el límite configurable del mandato.

Consideraciones sobre mejoras y reducciones de plan

Al mejorar o reducir suscripciones, ten en cuenta los límites de los mandatos:

Si una mejora o reducción de plan genera un importe de cargo que supera el límite mínimo del mandato (₹15,000 de forma predeterminada) y excede el límite de pago existente bajo demanda, el cargo de la transacción puede fallar.
Es posible que el cliente deba 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 de cargos de importe elevado

Para cargos de suscripción de ₹15,000 o más:

El banco solicitará al cliente que autorice la transacción.
Si el cliente no la autoriza, la transacción falla y la suscripción queda suspendida.

Retraso de procesamiento de 48 horas

Los cargos recurrentes de tarjetas indias y suscripciones de UPI siguen un patrón de procesamiento particular:

Los cargos se inician en la fecha programada según la frecuencia de la suscripción.
La deducción real de la cuenta del cliente solo se produce 48 horas después del inicio del pago.
Esta ventana de 48 horas puede ampliarse entre 2 y 3 horas adicionales según las respuestas de las APIs bancarias.

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 permanece activa (caso límite específico de las suscripciones AutoPay de tarjetas indias y UPI).
Sin embargo, la deducción real puede fallar y, en ese caso, pondremos la suscripción en suspensión.

Si proporcionas beneficios, créditos o uso de la suscripción a los clientes inmediatamente al iniciar el cargo, gestiona adecuadamente esta ventana de 48 horas:

Retrasa la activación de beneficios hasta confirmar el pago
Implementa periodos de gracia o acceso temporal
Supervisa el estado de la suscripción para detectar cancelaciones de mandatos
Gestiona los estados suspendidos de la suscripción en la lógica de tu aplicación

Supervisa los webhooks de suscripción para hacer seguimiento de los cambios en el estado del pago y gestionar los casos límite en los que se cancelan mandatos durante la ventana de 48 horas.

Prácticas recomendadas

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

Las suscripciones son una base flexible para los ingresos recurrentes. Empieza de forma sencilla, prueba exhaustivamente y realiza iteraciones según las métricas de adopción, abandono y expansión.

Última modificación el 26 de septiembre de 2026

Upgrade & Downgrade

On‑Demand Subscriptions

Customer Portal

Subscription Webhooks

​What Are Subscriptions?

​Key Benefits

​Creating Subscriptions

​Creación de productos de suscripción

​Detalles del producto

​Pricing

​Configuración avanzada

​Pruebas de Subscription

​Configurar pruebas

​Pruebas de pago

​Card-Optional at Zero Price

​Qué ocurre sin una tarjeta

​Prevención del uso indebido de pruebas

​Detección del estado de prueba

​Actualización del periodo de prueba

​Cambios de plan de suscripción

Product Collections

​Modos de prorrateo

​prorated_immediately

​difference_immediately

​full_immediately

​do_not_bill

​Cambio de planes con complementos

​Previsualización de cambios de plan

Preview Change Plan API

​Pausar y reanudar suscripciones

​Qué ocurre al pausar

​Pausar suscripciones basadas en el 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 la suscripción

​Máquina de estados

​Estado suspendido

​Reactivación desde el estado suspendido

​Periodo de gracia

​Configuración

​Qué ocurre durante la ventana

​Recuperación

​Cuando termina la ventana

​Eventos de 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 siguiente fecha de facturación

​Ampliar el periodo de 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 mejoras y reducciones de plan

​Autorización de 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

Creación de productos de suscripción

Detalles del producto

Pricing

Configuración avanzada

Pruebas de Subscription

Configurar pruebas

Pruebas de pago

Card-Optional at Zero Price

Qué ocurre sin una tarjeta

Prevención del uso indebido de pruebas

Detección del estado de prueba

Actualización del periodo de prueba

Cambios de plan de suscripción

Modos de prorrateo

`prorated_immediately`

`difference_immediately`

`full_immediately`

`do_not_bill`

Cambio de planes con complementos

Previsualización de cambios de plan

Pausar y reanudar suscripciones

Qué ocurre al pausar

Pausar suscripciones basadas en el uso

Permitir que los clientes pausen sus propias suscripciones

Pausar mediante la API

Pausas y otras acciones de suscripción

Estados de la suscripción

Máquina de estados

Estado suspendido

Reactivación desde el estado suspendido

Periodo de gracia

Configuración

Qué ocurre durante la ventana

Recuperación

Cuando termina la ventana

Eventos de 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 siguiente fecha de facturación

Ampliar el periodo de 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 mejoras y reducciones de plan

Autorización de cargos de importe elevado

Retraso de procesamiento de 48 horas

Ventana de cancelación del mandato

Prácticas recomendadas