Billing and Plans

Billing access model#

Checkout and billing management are handled through the frontend experience. Payment collection, renewals, taxes, and dunning are processed by Paddle.

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.

Plan pricing is controlled by the VertexY admin portal. The backend sends the current monthly amount and currency to Paddle when it creates a checkout, so the frontend never hard-codes billing prices.

Subscription endpoints#

Get your active subscription#

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

Get current monthly usage#

curl "https://api.getvertexy.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.