https://api.veriko.mx/v1/billing/subscription Consultar suscripción activa del usuario
Devuelve la suscripción activa del usuario autenticado con el plan vigente, el modelo de facturación, las fechas del ciclo actual, el límite efectivo y el resumen de cuota. El campo source indica el origen: stripe (pago Stripe), admin_granted (otorgada manualmente) o system_default (plan gratuito por defecto). Cada usuario tiene siempre exactamente una suscripción activa: la respuesta nunca incluye data: null. El resumen de uso (used, remaining, resets_at, limit) vive en meta.quota para que clientes que solo leen el slug por data.attributes no se vean obligados a parsear la cuota. Acepta autenticación por API key. Si el módulo de facturación está deshabilitado responde 503 con código billing_disabled. Para ver los planes disponibles a los que cambiar usa GET /v1/plans; para el consumo del ciclo actual usa GET /v1/usage/summary (la resets_at que devuelve es el mismo current_period_end de esta suscripción).
curl -X GET 'https://api.veriko.mx/v1/billing/subscription' \
-H 'Authorization: Bearer mxcep_••••'
Ejemplo en Python — próximamente.
Ejemplo en JavaScript — próximamente.
Ejemplo en PHP — próximamente.
| Campo | Tipo | Descripción |
|---|---|---|
type * | string | |
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 resuelta por `SubscriptionResolver::resolveActive`. 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. |
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. |
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. |
billing_interval | string | Cadencia de facturación. `once` se usa para concesiones de administrador o ciclos sin renovación automática. |
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 anulable | 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 el override administrativo (si existe) y la regla de `overage_enabled`. Es el número que `QuotaMiddleware` usa para bloquear o permitir. |
is_stripe | boolean | Atajo: equivale a `source == "stripe"`. |
stripe_subscription_id | string | null anulable | ID de la suscripción Stripe. `null` cuando `source != "stripe"`. |
grant_reason | string | null anulable | 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 anulable | 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 anulable | Timestamp de cancelación ya consumada. `null` mientras la suscripción está activa. |
trial_start | string | null anulable | Inicio del periodo de prueba, `null` si no hay trial. |
trial_end | string | null anulable | Fin del periodo de prueba, `null` si no hay trial. |
| Código | Clase | Descripción | Cuerpo |
|---|---|---|---|
| 200 | 2xx | Suscripción activa del usuario con plan, ciclo y cuota. | BillingSubscriptionResponse |
| 401 | 4xx | Se requiere autenticación o las credenciales son inválidas | ErrorResponse |
| 503 | 5xx | `billing_disabled` — el módulo de facturación está desactivado. | ErrorResponse |
| Código | Clave | Detalle |
|---|---|---|
| 401 | unauthorized | Invalid or missing authentication credentials. Envelope
|