Billing & Subscriptions

Manage your Vatly subscription through Stripe-powered billing

Overview

Vatly uses Stripe for subscription billing. You can upgrade to a paid tier (Business or Scale), manage your subscription, and view billing details through the admin API.

Tiers & Pricing

Tier	Monthly Requests	Burst Limit (per min)	Consultation Number
Free	500	20	No
Business	10,000	60	Yes
Scale	50,000	120	Yes

Checkout

Create a Stripe Checkout session to subscribe to a paid tier.

curl -X POST \
  -H "Authorization: Bearer <clerk_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "price_id": "price_xxx",
    "success_url": "https://yourapp.com/billing/success",
    "cancel_url": "https://yourapp.com/billing/cancel"
  }' \
  "https://api.vatly.dev/admin/billing/checkout"

Response (201):

{
  "data": {
    "session_id": "cs_xxx",
    "url": "https://checkout.stripe.com/c/pay/cs_xxx"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Redirect your user to the url to complete payment.

Billing Portal

Let users manage their subscription (change plan, update payment method, cancel) through the Stripe Customer Portal.

curl -X POST \
  -H "Authorization: Bearer <clerk_jwt>" \
  -H "Content-Type: application/json" \
  -d '{"return_url": "https://yourapp.com/billing"}' \
  "https://api.vatly.dev/admin/billing/portal"

Response (200):

{
  "data": {
    "url": "https://billing.stripe.com/p/session/xxx"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Subscription Status

Check the current subscription status for your account.

curl -H "Authorization: Bearer <clerk_jwt>" \
  "https://api.vatly.dev/admin/billing/subscription"

Response (200):

{
  "data": {
    "customer_id": "cus_xxx",
    "subscription_id": "sub_xxx",
    "subscription_status": "active",
    "tier": "business"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Subscription Statuses

Status	Meaning
active	Subscription is active and paid
trialing	Subscription is in trial period
past_due	Payment failed, retrying — tier remains unchanged
unpaid	Payment failed after retries — tier remains unchanged
canceled	Subscription canceled — tier downgraded to Free

Webhooks

Vatly automatically processes Stripe webhook events to keep your tier in sync:

• subscription.created — Tier is set based on the subscribed price
• subscription.updated — Tier is updated on active/trialing status; kept unchanged on past_due/unpaid
• subscription.deleted — Account is downgraded to Free

All webhook handlers are idempotent and safe to replay.

Billing Endpoints

Method	Path	Auth	Description
POST	/admin/billing/checkout	Clerk JWT	Create checkout session
POST	/admin/billing/portal	Clerk JWT	Create billing portal session
GET	/admin/billing/subscription	Clerk JWT	Get subscription status
POST	/webhooks/stripe	Stripe signature	Stripe webhook receiver