Billing and Plans

Understand subscription state, usage metrics, and how billing is handled through the frontend experience.

Billing access model

Checkout and billing management are handled through the frontend experience.

Users should not call backend checkout endpoints directly.

Recommended pattern:

  1. Let users choose a plan in the frontend billing UI.
  2. Start checkout from the frontend or a backend-for-frontend layer you control.
  3. Let the backend process provider webhooks and update subscription state.

Subscription endpoints

Get your active subscription

bash
curl https://api.vertexY.com/api/subscriptions/me \
  -H "Authorization: Bearer $VERTEXY_ACCESS_TOKEN"

Get current monthly usage

bash
curl "https://api.vertexY.com/api/subscriptions/me/usage?year=2026&month=4" \
  -H "Authorization: Bearer $VERTEXY_ACCESS_TOKEN"

Usage records are grouped by metric, such as:

  • fraud_events_ingested

Subscription statuses

  1. pending Checkout has started, but the subscription is not fully active yet.
  2. active The subscription is live.
  3. payment_failed The most recent billing step failed.
  4. canceled The subscription was canceled.
  5. expired The subscription ended.

Checkout and billing operations

The following actions are frontend-managed and should not be documented as public backend API workflows for end users:

  • starting a checkout session
  • upgrading a plan
  • canceling a subscription
  • refund operations

If your team needs a custom billing integration, implement it through a trusted server-side layer rather than exposing billing endpoints directly to client applications.

Feature gates and limits

Plans may control:

  • available UI modules
  • access to advanced analytics
  • graph explorer
  • reviews
  • audit logs
  • threat-intel tools
  • monthly usage ceilings

Common billing questions

Why do I get 402 Payment Required?

Usually one of these is true:

  • your company has no active subscription
  • the plan is pending or failed
  • usage exceeded the plan’s hard limit

Why can access still be limited after billing starts?

Because checkout initiation and subscription activation are separate events. A pending subscription may exist before the billing provider confirms activation.