Suscripciones
Consulta períodos, programa cancelaciones y gestiona renovaciones.
Usa billete.subscriptions desde tu servidor. Configura el cliente con el entorno y la clave de tu negocio.
Ejemplo
const subscription = await billete.subscriptions.retrieve("sub_ejemplo");
await billete.subscriptions.cancel(subscription.id,
{ atPeriodEnd: true },
{ idempotencyKey: "cancel-subscription-example-001" },
);Métodos
| Método | Qué hace |
|---|---|
create(input, options?) | Activar un plan gratuito o iniciar una prueba de pago. |
retrieve(id, options?) | Consultar su estado y período. |
update(id, input, options?) | Actualizar metadata. |
changes.preview(id, input, options?) | Cotizar sin modificar la suscripción. |
changes.create(id, input, options?) | Aplicar, cobrar o programar un cambio. |
list(query?, options?) | Filtrar por customer (ID de Billete o externalId), plan, status o search. |
iterate(query?) | Recorrer suscripciones. |
cancel(id, input?, options?) | Cancelar al terminar el período, por defecto. |
resume(id, options?) | Deshacer una cancelación programada. |
Qué debes tener en cuenta
Para cobrar el primer período usa un checkout de plan. create rechaza una segunda suscripción en curso al mismo plan (subscription_exists), igual que un checkout de ese plan al crearlo o pagarlo, pero a otro plan crea otra; para cambiar el plan de un cliente usa changes.create sobre su suscripción actual. La creación directa de un precio cero activa el plan sin prueba ni pago; para un precio positivo requiere días de prueba. atPeriodEnd: false cancela inmediatamente o pasa al plan de respaldo gratuito, si está configurado; agrega fallback: false para terminarla sin pasar por él. Con Pago Móvil el cliente inicia cada renovación.
Cambiar plan o puestos
const preview = await billete.subscriptions.changes.preview(subscription.id, {
plan: "plan_equipo", quantity: 5,
});
const result = await billete.subscriptions.changes.create(subscription.id, {
plan: "plan_equipo", quantity: 5, when: "now",
}, { idempotencyKey: "change-example-001" });
if (result.type === "checkout") {
// Envía result.checkout.url al cliente; conserva el acceso actual hasta el pago.
} else {
// result.subscription: type es applied o scheduled.
}
await billete.subscriptions.changes.create(subscription.id, {
quantity: 2, when: "renewal",
});La suscripción conserva su ID y expone unitAmount, quantity y version. Una reducción de puestos se programa para la renovación. Un cambio programado parte del que ya estaba programado, así que programar puestos conserva un ciclo programado antes. El crédito sobrante no queda como saldo: para perderlo debes enviar acceptUnusedCredit: true; normalmente conviene programar ese cambio.
Si el cambio deja menos puestos que miembros activos, falla con seats_in_use: quita antes a los miembros sobrantes, o envía disableExcessMembers: true para que se queden sin puesto (los prioritarios lo conservan primero). preview dice cuántos serían en excessMembers. Durante una prueba, un cambio now se aplica sin costo y la prueba sigue; endTrial: true la termina y cobra desde hoy:
// En prueba: pasa a 8 puestos sin cobrar; el primer cobro ya incluye los 8.
await billete.subscriptions.changes.create(subscription.id, { quantity: 8, when: "now" });
// Termina la prueba y cobra hoy, en un checkout.
await billete.subscriptions.changes.create(subscription.id, { when: "now", endTrial: true });Escucha subscription.updated, subscription.renewed, subscription.expired y subscription.change_failed. Cambiar metadata no invalida una cotización.