Skip to main content

​
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

TierMonthly RequestsBurst Limit (per min)Consultation Number
Free50020No
Business10,00060Yes
Scale50,000120Yes

​
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

StatusMeaning
activeSubscription is active and paid
trialingSubscription is in trial period
past_duePayment failed, retrying — tier remains unchanged
unpaidPayment failed after retries — tier remains unchanged
canceledSubscription 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

MethodPathAuthDescription
POST/admin/billing/checkoutClerk JWTCreate checkout session
POST/admin/billing/portalClerk JWTCreate billing portal session
GET/admin/billing/subscriptionClerk JWTGet subscription status
POST/webhooks/stripeStripe signatureStripe webhook receiver