Habilita un comportamiento flexible para las suscripciones
Usa el modo de gestión de cobros para controlar cómo se calculan y organizan los prorrateos y las facturas de las suscripciones.
Actualmente, Stripe calcula los importes de prorrateo de créditos en función del valor del precio actual, los impuestos, la cantidad y los últimos descuentos utilizados del artículo de la suscripción.
Puedes configurar billing_ para habilitar una lógica de prorrateo diferente que calcule los prorrateos de crédito en función del importe original debitado previamente al cliente.
Vista previa pública
Para habilitar la nueva lógica de cálculo de prorrateo configurando billing_ debes actualizar tu versión de API a 2025-04-30. o posterior.
El comportamiento actual puede dar lugar a prorrateos inesperados si cambian las tasas impositivas de un cliente, deshabilitas los prorrateos de débito o usas importes complejos de cupones. La lógica de prorrateo mejorada calcula los prorrateos de crédito basándose únicamente en el importe original debitado previamente a un cliente. Cuando un cliente realiza un cambio en su suscripción que genera un crédito, Stripe calcula el prorrateo usando el importe que se le facturó anteriormente. Este cálculo se realiza independientemente de los cambios posteriores que se realicen en la suscripción. Stripe recomienda usar billing_ si no se aplican las limitaciones de la vista previa pública.
Limitaciones de la versión preliminar pública Public preview
Durante la versión preliminar pública, billing_ no es compatible con todas las funcionalidades de Stripe Billing.
Cuando configuras billing_:
- El Modelo de cobro por consumo no se admite.
- El Cálculo automático de impuestos no se admite.
- Las Pruebas no se admiten.
- Los puntos de conexión de Quotes no se admiten.
- No puedes crear suscripciones con fecha anterior.
- No puedes pausar el cobro de pagos en las suscripciones.
Si usas estas funcionalidades con billing_ se devuelve un código de error 400.
Configura el modo de gestión de cobros Public preview
Puedes establecer billing_ en suscripciones específicas y tener varias suscripciones con diferentes configuraciones de billing_mode. No puedes cambiar el billing_ de flexible a classic. Así se garantiza que la lógica y el comportamiento sean coherentes a lo largo del ciclo de vida de cada suscripción. Puedes migrar las suscripciones existentes de billing_ a billing_.
Al configurar billing_, también se actualiza subscription.trial_start para reflejar la fecha de inicio de prueba más reciente.
Migra las suscripciones al modo de facturación flexible Public preview
Puedes migrar las suscripciones existentes de billing_ a billing_ usando el punto de conexión de migración de suscripciones. La migración al modo de facturación flexible es un proceso unidireccional. Después de migrar una suscripción al modo flexible, no puedes revertirla al modo classic. De este modo, se garantiza una lógica de prorrateo coherente a lo largo del ciclo de vida de la suscripción.
Al migrar una suscripción, la marca de tiempo billing_ se actualiza para mostrar cuándo cambia el billing_.
Cambios en el modo de gestión de cobros flexible
Establecer billing_ en una suscripción cambia el comportamiento de los objetos Subscription a lo largo de su ciclo de vida y en respuesta a cambios a planes superiores o inferiores, y cancelaciones.
Lógica de cálculo sin prorrateos
En el siguiente escenario, actualizas una suscripción mensual de 10 USD a 20 USD con el proration_ establecido en none durante 10 días. No hay un débito previo en el que basarse. Luego, cambias la suscripción a 10 USD por mes con el proration_ establecido en always_.
Para configurar este escenario, primero creas una suscripción por 10 USD/mes el 01/04/2025:
La respuesta incluye la factura creada para esta suscripción:
{ id: "sub_123", latest_invoice: { id: "in_123", total: 10_00, currency: "usd" } }
Luego, el 11/04/2025, cambias a una suscripción superior de 20 USD/mes sin crear prorrateos:
La última factura no se modifica porque proration_ es none:
{ id: "sub_123", latest_invoice: { id: "in_123" } }
Por último, el 21/04/2025, cambias a un plan de suscripción inferior a 10 USD/mes y creas prorrateos:
La lógica de cálculo del prorrateo predeterminada crea un prorrateo del crédito basado en el precio actual, aunque el cliente nunca haya pagado la tasa de 20 USD/mes. En la última factura, se acredita un tercio del mes para 20 USD (-6.67 USD), aunque el cliente nunca pagó el precio price_. También debita un tercio del mes por 10 USD (3.33 USD).
La lógica de cálculo que se habilita con billing_ crea un prorrateo del crédito basado en el último precio facturado por el ítem de suscripción. En este caso, en la última factura se acredita un tercio de mes por el precio 10 USD/mes facturado el 01/04/2025 (3.33 USD) y se debita un tercio del mes por el 10 USD precio (3.33 USD). El crédito y el débito se cancelan, por lo que el total de la factura es 0 USD.
# Default behavior # billing_mode = classic { id: "sub_123", latest_invoice: { id: "in_456", total: -3_34, currency: "usd" } }
# New behavior # billing_mode=flexible { id: "sub_123", latest_invoice: { id: "in_456", total: 0, currency: "usd" } }
Lógica de cálculo para cupones aplicados a varios ítems de suscripción
Stripe pondera el cupón amount_ en el prorrateo del crédito para evitar la sobrefacturación.
En el siguiente escenario, un cupón de 5 USD se asigna de manera desigual a una suscripción mensual de 25 USD para un ítem de 10 USD y un ítem de 20 USD.
Para configurar este escenario, creas una suscripción con varios ítems y un cupón el 01/02/2025:
Lo que devuelve esta respuesta:
{ id: "sub_123", latest_invoice: { id: "in_123", total: 25_00, currency: "usd", lines: { data: [ { id: "ili_1", amount: 10_00, price: "price_10_monthly", discount_amounts: [{ discount: "di_a", amount: 1_66 }] }, { id: "ili_2", amount: 20_00, price: "price_20_monthly", discount_amounts: [{ discount: "di_a", amount: 3_34 }] }, ] } } }
Para cancelar el ítem de suscripción 10 USD/mes usando billing_:
Para cancelar el mismo ítem usando billing_:
El comportamiento predeterminado distribuye un cupón de 5 USD a cada artículo (2.5 USD cada uno), cancela el artículo más económico (5 USD) y da como resultado un reembolso de 2.5 USD. Stripe calcula el total con la fórmula -0..
El nuevo comportamiento refleja el descuento proporcional aplicado al ítem cancelado, en lugar de aplicar potencialmente el importe total del descuento al cálculo del prorrateo. Stripe calcula el total usando la fórmula -0..
# Default behavior # billing_mode = classic { "id": "sub_123", "latest_invoice": { "id": "in_456", "total": -250, "currency": "usd" } }
# New behavior # billing_mode = flexible { "id": "sub_123", "latest_invoice": { "id": "in_789", "total": -417, "currency": "usd" } }
Restablecimientos de delimitación del ciclo de facturación
Cuando realizas cambios en una suscripción, el billing_cycle_anchor no se restablece de manera implícita. Por ejemplo, cambiar una suscripción a un precio diferente con un intervalo recurrente diferente o mover cancel_at a una fecha anterior a la próxima vez que se produzca el ciclo de suscripción no restablece el billing_.
Fechas de inicio y finalización de la prueba
subscription. usa la fecha de inicio de prueba más reciente para las suscripciones con períodos de prueba posteriores.