Planes
Precios por ciclo, pruebas y cuotas para suscripciones.
Crear un plan
{
"name": "Pro",
"currency": "USD",
"prices": [
{"months": 1, "amount": 1000},
{"months": 12, "amount": 10000}
],
"gracePeriodDays": 3
}Los ciclos disponibles son 1, 3, 6, 9 y 12 meses. La gracia admite 0, 1, 3 o 7 días. Puedes añadir trialDays, features, highlights y taxBehavior.
Puestos y respaldo
Los puestos son opcionales. seats: { mode: "included", limit: null } es el valor predeterminado: puestos ilimitados incluidos en el precio. Un límite entero restringe los miembros habilitados. Para cobrar por puesto usa { mode: "per_seat", min: 1, max: 100 } (máximo 10 000); cada precio es unitario y la suscripción guarda los puestos comprados en quantity. No se puede cambiar de modo si el plan tiene suscripciones (plan_seats_locked).
Los puestos de un cliente son los de todas sus suscripciones vigentes sumados (ilimitados si alguna lo es): así un plan por puesto como «Puestos extra» funciona como complemento de otro plan. Quien compra elige los puestos en el checkout o en el enlace de pago cuando no los fijas, y después los cambia con un cambio de suscripción, tu aplicación o el portal.
fallbackPlanId apunta a un plan activo de la misma moneda, con un ciclo gratuito, puestos incluidos y sin respaldo propio (si no, fallback_plan_not_free); un plan que ya es respaldo de otro no puede tener respaldo (fallback_plan_nested). Al cancelar o expirar se usa ese ciclo sin crear otra suscripción. Los miembros que se quedan sin puesto permanecen registrados, sin acceso (primero conservan el suyo los prioritarios); al ampliar los puestos se habilitan de nuevo.
En vez de respaldo, un plan puede suspender: suspensionDays (0, el valor predeterminado, 7, 14, 30, 60 o 90) deja la suscripción sin pago en suspended durante esos días, sin acceso pero pagable para reactivarla, antes de expirar. Un plan no tiene las dos cosas (suspension_with_fallback). Mira suspensión.
Tu clave para el plan
lookupKey es tu propio nombre para el plan (plus): minúsculas, números, _ y -, empezando por una letra, y único entre tus planes de cada entorno (si no, lookup_key_in_use). Encuéntralo con GET /v1/plans?lookupKey=plus y cámbialo o quítalo (null) con PATCH. A diferencia de metadata, es público: cada ítem del checkout en el navegador lo trae, para que tu checkout propio sepa qué vende sin guardar IDs.
| Método | Ruta | Acción |
|---|---|---|
| POST / GET | /v1/plans | Crear / listar planes |
| GET / PATCH / DELETE | /v1/plans/:plan | Consultar / actualizar / eliminar plan |
active: false desactiva un plan: no acepta suscripciones nuevas, y las que ya tiene siguen igual. Eliminarlo es definitivo y solo se puede si ninguna suscripción está en curso en él y no es el respaldo de otro plan; si no, responde 409 con plan_in_use. Elimina también sus enlaces de pago, libera su lookupKey y lo deja con deletedAt: sale de las listas, pero se sigue consultando por su ID.
Precios y cuotas
Cambiar los precios del plan afecta a nuevas suscripciones; las existentes conservan el precio contratado. Cambiar sus features sí modifica inmediatamente las cuotas de sus suscriptores.