Get user's active subscription

GET https://api.veriko.mx/v1/billing/subscription

Audience: public
Auth: API key
Permission: billing:read_self

Returns the authenticated user's active subscription with the current plan, billing model, current cycle dates, effective limit, and quota summary. The source field indicates the origin: stripe (Stripe payment), admin_granted (manually granted), or system_default (default free plan). Every user always has exactly one active subscription — the response never includes data: null. The usage summary (used, remaining, resets_at, limit) lives at meta.quota so clients reading only the slug from data.attributes are not forced to parse the quota. Accepts API key authentication. If the billing module is disabled responds 503 with code billing_disabled. To see the available plans to switch to use GET /v1/plans; for current-cycle usage use GET /v1/usage/summary — its resets_at matches current_period_end from this subscription.

Request

cURLPython•JavaScript•PHP•

curl -X GET 'https://api.veriko.mx/v1/billing/subscription' \
  -H 'Authorization: Bearer mxcep_••••'

Python example — coming soon.

JavaScript example — coming soon.

PHP example — coming soon.

**Response 200** `BillingSubscriptionResponse` — User's active subscription with plan, cycle, and quota.
Field	Type	Description
`type` *	`string`
`id` *	`string`	Local subscriptions row ID (integer as string). NOT the Stripe ID — that lives in `attributes.stripe_subscription_id`.
`attributes` *	`object`	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.
`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` nullable	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` nullable	Stripe subscription ID. `null` when `source != "stripe"`.
`grant_reason`	`string \| null` nullable	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` nullable	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` nullable	Timestamp when cancellation has already taken effect. `null` while the subscription is active.
`trial_start`	`string \| null` nullable	Trial period start, `null` if no trial.
`trial_end`	`string \| null` nullable	Trial period end, `null` if no trial.

**Response status codes** `GET /v1/billing/subscription`
Status	Class	Description	Body
200	`2xx`	User's active subscription with plan, cycle, and quota.	`BillingSubscriptionResponse`
401	`4xx`	Authentication is required or the provided credentials are invalid.	`ErrorResponse`
503	`5xx`	`billing_disabled` — billing module is disabled.	`ErrorResponse`

**Errors from `GET /v1/billing/subscription`**
Status	Code	Detail
401	`unauthorized`	Invalid or missing authentication credentials. Envelope meta.request_id `c4d5e6f7a8b9`