GET https://api.veriko.mx/v1/billing/subscription

Consultar suscripción activa del usuario

Audiencia
public
Autenticación
API key
Permiso
billing:read_self

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).

Petició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.

Respuesta 200 BillingSubscriptionResponse — Suscripción activa del usuario con plan, ciclo y cuota.
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ódigos de respuesta GET /v1/billing/subscription
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
Errores de GET /v1/billing/subscription
Código Clave Detalle
401 unauthorized

Invalid or missing authentication credentials.

Envelope
meta.request_id
c4d5e6f7a8b9