Main response payload. Shape varies by endpoint (object, array, or JSON:API envelope with type, id, attributes).

Resource type, fixed for this operation. Part of the resource identity in the JSON:API envelope. Always billing_subscription.

Local subscriptions row ID (integer as string). NOT the Stripe ID — that lives in attributes.stripe_subscription_id.

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.

Active plan slug (free, basic, pro, …).

Display name of the plan for UI.

Plan billing model. free — no charge; tiered — flat fee; metered — charged by usage; hybrid — flat fee plus usage.

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.

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.

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.

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 of the active cycle. MXN is Mexican pesos and USD, US dollars.

Billing cadence. once is used for admin grants or cycles without automatic renewal. month bills monthly and year, yearly.

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.

Validations included in the plan before overage. null for plans with no included/overage distinction.

Plan monthly cap. In hybrid with overage_enabled=true it acts as hard cap; in tiered/metered/free plans it is the primary limit.

Beneficiary cap of the active plan. -1 = unlimited (every plan's default until pricing sets a value); >=0 acts as a hard cap.

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.

Shortcut: equivalent to source == "stripe".

Stripe subscription ID. null when source != "stripe".

Reason recorded when the subscription was granted by an admin. null if source != "admin_granted".

true when the subscription is scheduled to cancel at cycle end (via POST /billing/subscription/cancel or legacy Stripe portal).

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.

Timestamp when cancellation has already taken effect. null while the subscription is active.

Trial period start, null if no trial.

Trial period end, null if no trial.

Response metadata including API version, route prefix, unique request identifier, and the server timestamp in UTC.

API version that processed the request.

API route prefix version (e.g. v1).

Unique request identifier (hex).

Companion descriptor present in every response's meta block (and in outgoing webhook payloads). Lets clients assert the timezone contract without re-reading the spec.

Always UTC — the canonical timezone for every datetime field in the body.

Always ISO 8601 — explicit Z suffix on every datetime.

Pagination or related links, present only when the endpoint returns a paginated collection.