`BillingSubscriptionResponse`

Respuesta de `GET /v1/billing/subscription`. La suscripción activa se expone en `data`; el resumen de uso vive en `meta.quota` para que clientes legacy que ya leían `effective_plan_slug` no se vean afectados.

Propiedades

Campo	Tipo	Descripción
`data`	`object`	Payload principal de la respuesta. La forma varía según el endpoint (objeto, array, o envelope JSON:API con `type`, `id`, `attributes`).
`type`*	`string`	Tipo del recurso, fijo para esta operación. Forma parte de la identidad del recurso en la envoltura JSON:API. Siempre `billing_subscription`.
`id`*	`string`	ID local de la fila de suscripciones (entero como string). NO es el ID de Stripe — ese va en `attributes.stripe_subscription_id`.
`attributes`*	`object`	Suscripción activa del usuario. Cada usuario tiene exactamente una fila activa: el origen viene en `source`. Los campos `trial_`, `cancel_` y `stripe_subscription_id` son nulos cuando no aplican (planes gratuitos por defecto, concesiones de administrador o estados estables). Todos los timestamps están en UTC con sufijo `Z`.
`plan_slug`	`string`	Slug del plan activo (`free`, `basic`, `pro`, …).
`plan_name`	`string`	Nombre legible del plan para mostrar en UI.
`billing_model`	`string`	Modelo de facturación del plan. `free` — sin cobro; `tiered` — cuota fija; `metered` — se cobra por consumo; `hybrid` — cuota fija más consumo.
`source`	`string`	Origen de la suscripción. `stripe` = pago Stripe activo. `admin_granted` = otorgado manualmente por un administrador. `system_default` = plan gratuito por defecto, creado automáticamente para usuarios sin facturación activa.
`status`	`string`	Estado del ciclo de vida de la suscripción. `active`, `trialing` y `past_due` cuentan como "acceso habilitado". `past_due` es periodo de gracia: Stripe Smart Retries está reintentando el cobro. `canceled` — terminada; `unpaid` — con cobros fallidos y sin gracia; `incomplete` e `incomplete_expired` — el primer pago nunca se completó; `paused` — en pausa.
`current_period_start`	`string (date-time)`	Timestamp ISO 8601 en UTC con sufijo `Z` explícito. Ejemplo: `"2026-05-01T05:14:38Z"`. Cada campo `_at`, `_end`, `_start`, `_date` de la API usa esta forma. El descriptor compañero en `meta.datetime` permite afirmar el contrato en tiempo de ejecución sin volver a leer este spec. El `new Date(value)` nativo del navegador, el `datetime.fromisoformat` (≥3.11) de Python y el `time.Parse(time.RFC3339)` de Go parsean este formato directamente.
`current_period_end`	`string (date-time)`	Timestamp ISO 8601 en UTC con sufijo `Z` explícito. Ejemplo: `"2026-05-01T05:14:38Z"`. Cada campo `_at`, `_end`, `_start`, `_date` de la API usa esta forma. El descriptor compañero en `meta.datetime` permite afirmar el contrato en tiempo de ejecución sin volver a leer este spec. El `new Date(value)` nativo del navegador, el `datetime.fromisoformat` (≥3.11) de Python y el `time.Parse(time.RFC3339)` de Go parsean este formato directamente.
`currency`	`string`	Moneda del ciclo activo. `MXN` son pesos mexicanos y `USD`, dólares estadounidenses.
`billing_interval`	`string`	Cadencia de facturación. `once` se usa para concesiones de administrador o ciclos sin renovación automática. `month` cobra cada mes y `year`, cada año.
`overage_enabled`	`boolean`	`true` si el usuario aceptó cobro por excedente en un plan `hybrid`. Cuando es `true`, `effective_limit` salta de `included_validations` a `monthly_validation_limit`.
`included_validations`	`integer \| null`	Validaciones incluidas en el plan antes del overage. `null` para planes sin distinción incluido/overage.
`monthly_validation_limit`	`integer`	Tope mensual del plan. En `hybrid` con `overage_enabled=true` actúa como tope duro; en planes `tiered`/`metered`/`free` es el límite principal.
`beneficiaries_max`	`integer`	Tope de beneficiarios del plan activo. `-1` = ilimitado (default de todos los planes hasta que pricing fije un valor); `>=0` actúa como tope duro.
`effective_limit`	`integer`	Límite efectivo de validaciones para el ciclo actual, ya aplicado la corrección administrativo (si existe) y la regla de `overage_enabled`. Es el número contra el que se decide si una validación se atiende o se rechaza.
`is_stripe`	`boolean`	Atajo: equivale a `source == "stripe"`.
`stripe_subscription_id`	`string \| null`	ID de la suscripción Stripe. `null` cuando `source != "stripe"`.
`grant_reason`	`string \| null`	Motivo registrado cuando la suscripción fue otorgada por un administrador. `null` si `source != "admin_granted"`.
`cancel_at_period_end`	`boolean`	`true` cuando la suscripción está programada para cancelarse al cierre del ciclo (vía POST `/billing/subscription/cancel` o portal Stripe legacy).
`cancel_at`	`string \| null`	Timestamp explícito de cancelación programada (formato moderno del Stripe Customer Portal). Mutuamente excluyente con `cancel_at_period_end` a nivel API de Stripe, pero ambos pueden aparecer reflejados localmente.
`canceled_at`	`string \| null`	Timestamp de cancelación ya consumada. `null` mientras la suscripción está activa.
`trial_start`	`string \| null`	Inicio del periodo de prueba, `null` si no hay trial.
`trial_end`	`string \| null`	Fin del periodo de prueba, `null` si no hay trial.
`meta`	`object`	Metadatos de la respuesta, incluyendo versión de la API, prefijo de ruta, identificador único de la petición y marca temporal del servidor en UTC.
`version`	`string`	Versión de la API que procesó la petición.
`api_version`	`string`	Versión del prefijo de ruta de la API (ej. `v1`).
`request_id`	`string`	Identificador único de la petición (hex).
`datetime`	`object`	Descriptor compañero presente en el bloque `meta` de cada respuesta (y en el `meta` del cuerpo de los webhooks salientes). Permite a los clientes afirmar el contrato de zona horaria sin releer el spec.
`timezone`*	`string`	Siempre `UTC` — la zona canónica para cada campo datetime del cuerpo.
`format`*	`string`	Siempre `ISO 8601` — sufijo `Z` explícito en cada datetime.
`links`	`object`	Enlaces de paginación o relacionados, presentes solo cuando el endpoint devuelve una colección paginada.

Usado en operaciones

GET /v1/billing/subscription