Docs
EN

← Volver al índice de esquemas

BillingSubscriptionAttributes

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

Propiedades

Campo Tipo Descripción
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 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 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.

Usado en operaciones

  • GET /v1/billing/subscription
  • POST /v1/billing/subscription/refresh
  • GET /v1/admin/billing/subscriptions/{user_id}
  • POST /v1/billing/overage/enable
  • DELETE /v1/billing/overage/disable

Referenciado por esquemas