BillingSubscriptionAttributes
The user's active subscription, including its source, state, cycle, and limits. Each user has exactly one. The `trial_*`, `cancel_*`, and `stripe_subscription_id` fields are null when not applicable.
Properties
| Field | Type | Description |
|---|---|---|
plan_slug | string | Unique, human-readable plan identifier. It corresponds to the user's active plan. |
plan_name | string | Plan name shown in the interfaces. |
billing_model | string | Plan billing model. `free`: No charge; `tiered`: Flat fee; `metered`: Charged by usage; `hybrid`: Flat fee plus usage. |
source | string | Subscription source — `stripe`: Payment through Stripe; `admin_granted`: Admin grant; `system_default`: Plan assigned by the system. |
status | string | Subscription lifecycle state — `active`: Active; `trialing`: In a trial period; `past_due`: Payment overdue with access still enabled; `canceled`: Ended; `unpaid`: Failed payments with no access; `incomplete`: First payment pending; `incomplete_expired`: First payment expired; `paused`: Paused. |
current_period_start | string (date-time) | ISO 8601 timestamp in UTC with an explicit `Z` suffix; for example, `"2026-05-01T05:14:38Z"`. The `*_at`, `*_end`, `*_start`, and `*_date` fields follow this format. `meta.datetime` describes the same contract in the response. |
current_period_end | string (date-time) | ISO 8601 timestamp in UTC with an explicit `Z` suffix; for example, `"2026-05-01T05:14:38Z"`. The `*_at`, `*_end`, `*_start`, and `*_date` fields follow this format. `meta.datetime` describes the same contract in the response. |
currency | string | Currency of the active cycle. `MXN` is Mexican pesos and `USD`, US dollars. |
billing_interval | string | Billing cadence — `once`: One cycle with no automatic renewal; `month`: Monthly; `year`: Yearly. |
overage_enabled | boolean | `true` when the user has opted into overage billing on a `hybrid` plan. When so, `effective_limit` jumps from `included_validations` to `monthly_validation_limit`. |
included_validations | integer | null | Validations included in the base quota before overage charges. `null` when the plan has no base quota. |
monthly_validation_limit | integer | Validation cap per subscription cycle. `0` allows no validations. On `hybrid` plans, it is the hard cap when `overage_enabled` is `true`; when it is `false`, `effective_limit` uses `included_validations`. On other models, it is the effective limit unless an admin override applies. |
beneficiaries_max | integer | Cap on registered beneficiaries per account. `-1` means uncapped; from `0`, the value is enforced as the limit. |
bulk_validations_max | integer | Maximum number of validations per import job. `0` allows no validation imports. |
effective_limit | integer | Effective validation limit for the current cycle. It includes admin overrides and, on `hybrid` plans, the `overage_enabled` rule. This is the value used to decide whether a validation is served or rejected. |
is_stripe | boolean | `true` when `source` is `stripe`. |
stripe_subscription_id | string | null | Stripe subscription identifier (`sub_...`). `null` when `source` is not `stripe`. |
grant_reason | string | null | Reason recorded when the subscription was granted by an admin. `null` when `source` is not `admin_granted`. |
cancel_at_period_end | boolean | `true` when the subscription is scheduled to cancel at the end of the current cycle. |
cancel_at | string | null | Date and time the cancellation is scheduled for, in ISO 8601 UTC. `null` when no cancellation is scheduled through `cancel_at`. |
canceled_at | string | null | Date and time the cancellation took effect, in ISO 8601 UTC. `null` while the subscription is active. |
trial_start | string | null | Date and time the trial period starts, in ISO 8601 UTC. `null` when there is no trial period. |
trial_end | string | null | Date and time the trial period ends, in ISO 8601 UTC. `null` when there is no trial period. |
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