BillingSubscriptionAttributes
User's active subscription. 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. `free` — no charge; `tiered` — flat fee; `metered` — charged by usage; `hybrid` — flat fee plus usage. |
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. `canceled` — ended; `unpaid` — failed charges with no grace left; `incomplete` and `incomplete_expired` — the first payment never completed; `paused` — paused. |
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. `MXN` is Mexican pesos and `USD`, US dollars. |
billing_interval | string | Billing cadence. `once` is used for admin grants or cycles without automatic renewal. `month` bills monthly and `year`, yearly. |
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 a validation is checked against before it is served or refused. |
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/subscriptionPOST /v1/billing/subscription/refreshGET /v1/admin/billing/subscriptions/{user_id}POST /v1/billing/overage/enableDELETE /v1/billing/overage/disable