Otorgar Acceso Temporal a un Plan

Un Plan Grant amplía temporalmente el acceso de una suscripción activa. No cambia el plan, el precio, la moneda, el billing anchor, el período, las invoices, el método de pago ni el estado de la suscripción.

Usá un Plan Grant cuando un customer seleccionado necesite límites superiores o features adicionales durante una evaluación, migración, excepción de soporte o período negociado, sin cambiar lo que se le cobra.

Cómo se resuelve el acceso

La suscripción conserva el contrato inmutable de su plan base. El grant fija una release inmutable de un plan superior y combina ambos contratos:

• una feature booleana queda habilitada si cualquiera de los dos contratos la habilita;
• el uso incluido y los límites de quota o seats toman el valor más alto;
• el acceso ilimitado se aplica si cualquiera de los contratos es ilimitado; y
• el grant nunca incorpora overage pago.

Cuando termina el grant, Commet vuelve a evaluar el acceso contra la suscripción base de inmediato. Los seats existentes y el uso registrado no se eliminan. Si el customer ya supera un límite estricto del plan base, se bloquea el uso adicional hasta que el consumo se reinicie, la capacidad vuelva a estar debajo del límite o la suscripción se actualice mediante el flujo normal.

Elegibilidad

La suscripción base debe estar activa y ser recurrente. El plan de destino debe pertenecer al mismo Plan Group y tener un sortOrder superior al del plan base.

La primera versión admite planes Metered con features booleanas y límites estrictos de uso, quota o seats. Commet rechaza el grant si cualquiera de los planes usa:

• consumo mediante Credits o Balance;
• overage pago;
• precios por modelo de AI; o
• add-ons activos en la suscripción.

El plan de destino puede ser gratis o pago. Sus precios e intervalos no participan porque el grant no los utiliza.

Elegir la duración

Crear o actualizar un grant nunca reinicia el ciclo de facturación.

Otorgar acceso

Creá el grant con los IDs públicos del customer, la suscripción activa y el plan de destino:

curl -X POST https://commet.co/api/v1/customers/cus_xxx/plan-grants \
  -H "x-api-key: $COMMET_API_KEY" \
  -H "commet-version: 2026-07-31" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptionId": "sub_xxx",
    "planId": "pln_pro",
    "duration": "cycles",
    "durationCycles": 2,
    "reason": "Evaluación de un customer seleccionado"
  }'

El acceso se amplía de inmediato. No se crea checkout, invoice, cargo, crédito ni cambio de plan de la suscripción.

Actualizar la duración

Usá el ID público del grant para cambiar la duración restante:

curl -X PATCH https://commet.co/api/v1/customers/cus_xxx/plan-grants/grt_xxx \
  -H "x-api-key: $COMMET_API_KEY" \
  -H "commet-version: 2026-07-31" \
  -H "Content-Type: application/json" \
  -d '{
    "duration": "until_date",
    "expiresAt": "2026-10-31T23:59:59.999Z",
    "reason": "Evaluación extendida"
  }'

También podés enviar until_revoked, o cycles con un nuevo durationCycles. La nueva cantidad de ciclos se calcula desde el período actual y el billing anchor original de la suscripción.

Revocar el acceso

La revocación restaura inmediatamente el acceso del plan base:

curl -X POST https://commet.co/api/v1/customers/cus_xxx/plan-grants/grt_xxx/revoke \
  -H "x-api-key: $COMMET_API_KEY" \
  -H "commet-version: 2026-07-31" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Terminó la evaluación"}'

La revocación no crea una obligación a precio completo, no modifica el billing anchor y no cambia la suscripción a pending_payment.

Plan Grants, Offers, trials e Invoice Credit

Mantener el acceso sincronizado

Escuchá customer.state_changed. plan_access_granted informa la activación, mientras que plan_access_ended informa el vencimiento o la revocación.

Listá los grants del customer para consultar su estado y la línea de cambios de duración:

curl https://commet.co/api/v1/customers/cus_xxx/plan-grants \
  -H "x-api-key: $COMMET_API_KEY" \
  -H "commet-version: 2026-07-31"

Consultá la referencia de la API de Plan Grants para ver los schemas exactos de request y response.

Relacionado

• Administrar suscripciones
• Introductory Offers
• Customer State Changed