Docs
ES

← Back to schema index

BillingSubscriptionAttributes

User's active subscription resolved by `SubscriptionResolver::resolveActive`. Each user has exactly one active row; the origin is in `source`. The `trial_*`, `cancel_*` and `stripe_subscription_id` fields are null when not applicable (default free plans, admin grants, or steady-state subscriptions). All timestamps are UTC with `Z` suffix.

Properties

Field Type Description
plan_slug string Active plan slug (`free`, `basic`, `pro`, …).
plan_name string Display name of the plan for UI.
billing_model string Plan billing model.
source string Subscription origin. `stripe` = active Stripe payment. `admin_granted` = manually granted by an admin. `system_default` = default free plan, auto-created for users with no active billing.
status string Subscription lifecycle status. `active`, `trialing` and `past_due` count as "access granted". `past_due` is a grace period: Stripe Smart Retries is retrying the charge.
current_period_start string (date-time) ISO 8601 timestamp in UTC with explicit `Z` suffix. Example: `"2026-05-01T05:14:38Z"`. Every datetime field uses this shape. The descriptor at `meta.datetime` makes the contract runtime-assertable.
current_period_end string (date-time) ISO 8601 timestamp in UTC with explicit `Z` suffix. Example: `"2026-05-01T05:14:38Z"`. Every datetime field uses this shape. The descriptor at `meta.datetime` makes the contract runtime-assertable.
currency string Currency of the active cycle.
billing_interval string Billing cadence. `once` is used for admin grants or cycles without automatic renewal.
overage_enabled boolean `true` if the user has opted into overage billing on a `hybrid` plan. When `true`, `effective_limit` jumps from `included_validations` to `monthly_validation_limit`.
included_validations integer | null Validations included in the plan before overage. `null` for plans with no included/overage distinction.
monthly_validation_limit integer Plan monthly cap. In `hybrid` with `overage_enabled=true` it acts as hard cap; in `tiered`/`metered`/`free` plans it is the primary limit.
beneficiaries_max integer Beneficiary cap of the active plan. `-1` = unlimited (every plan's default until pricing sets a value); `>=0` acts as a hard cap.
effective_limit integer Effective validation limit for the current cycle, after applying any admin override and the `overage_enabled` rule. This is the number `QuotaMiddleware` uses to gate access.
is_stripe boolean Shortcut: equivalent to `source == "stripe"`.
stripe_subscription_id string | null Stripe subscription ID. `null` when `source != "stripe"`.
grant_reason string | null Reason recorded when the subscription was granted by an admin. `null` if `source != "admin_granted"`.
cancel_at_period_end boolean `true` when the subscription is scheduled to cancel at cycle end (via POST `/billing/subscription/cancel` or legacy Stripe portal).
cancel_at string | null Explicit scheduled-cancellation timestamp (modern Stripe Customer Portal format). Mutually exclusive with `cancel_at_period_end` at the Stripe API level, but both may appear locally.
canceled_at string | null Timestamp when cancellation has already taken effect. `null` while the subscription is active.
trial_start string | null Trial period start, `null` if no trial.
trial_end string | null Trial period end, `null` if no trial.

Used in operations

  • 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

Referenced by schemas