Billing API Endpoints
REST API reference for all billing proxy routes. These endpoints are called from your application with the user's session token, not directly from your server with an API key.
Authentication
All billing proxy endpoints require the user's session token in the Authorization header:
Authorization: Bearer <session_token>
The session token is the JWT returned by AuthGate after authentication. Billing operations are scoped to the user identified by this token — users can only access their own subscription, invoices, and entitlements.
List plans
Returns all publicly available plans and their prices for the project.
Response 200
{
"plans": [
{
"id": "plan_starter",
"name": "Starter",
"description": "For individuals and small teams",
"features": ["basic_analytics", "5_seats"],
"recommended": false,
"prices": [
{
"id": "price_starter_monthly",
"amount": 900,
"currency": "usd",
"interval": "month",
"model": "recurring"
},
{
"id": "price_starter_annual",
"amount": 8640,
"currency": "usd",
"interval": "year",
"model": "recurring"
}
]
}
]
}
Plans marked as hidden in the dashboard are excluded from this response.
Get subscription
Returns the current user's active or trialing subscription.
Response 200
{
"subscription": {
"id": "sub_abc123",
"plan": {
"id": "plan_pro",
"name": "Pro"
},
"price": {
"id": "price_pro_monthly",
"amount": 2900,
"interval": "month"
},
"status": "active",
"current_period_start": "2025-04-01T00:00:00Z",
"current_period_end": "2025-05-01T00:00:00Z",
"cancel_at_period_end": false,
"trial_end": null
}
}
Returns { "subscription": null } when the user has no active subscription.
Create checkout session
Creates a checkout session and returns a URL to redirect the user to, or an embedded payment intent for use with <CheckoutForm />.
Request body
- Name
price_id- Type
- string
- Description
The price to check out.
- Name
success_url- Type
- string
- Description
Where to redirect after a successful payment.
- Name
cancel_url- Type
- string
- Description
Where to redirect if the user cancels.
- Name
promotion_code- Type
- string
- Description
Optional promotion code to apply.
- Name
trial_days- Type
- integer
- Description
Override trial days for this checkout. Requires the plan to have trials enabled.
Response 200
{
"checkout_url": "https://your-authgate-instance.com/billing/checkout/sess_abc123",
"session_id": "sess_abc123"
}
Redirect the user to checkout_url. AuthGate renders the payment collection UI and redirects to success_url or cancel_url on completion.
Cancel subscription
Cancels the current user's active subscription.
Request body
- Name
at_period_end- Type
- boolean
- Description
If true, access continues until the end of the current billing period. If false, the subscription is canceled immediately.
Response 200
{
"subscription": {
"id": "sub_abc123",
"status": "active",
"cancel_at_period_end": true,
"current_period_end": "2025-05-01T00:00:00Z"
}
}
Fires a subscription.canceled webhook on success.
Resume subscription
Resumes a subscription that was canceled with at_period_end: true or is currently paused. The cancellation or pause is reversed and the subscription continues as normal.
Response 200
{
"subscription": {
"id": "sub_abc123",
"status": "active",
"cancel_at_period_end": false
}
}
Returns 400 if the subscription is already active and not pending cancellation. Fires a subscription.updated webhook on success.
Get entitlements
Returns the current user's plan and feature entitlements.
Response 200
{
"plan": "pro",
"status": "active",
"features": ["basic_analytics", "advanced_analytics", "api_access", "25_seats"]
}
Returns { "plan": null, "status": null, "features": [] } when the user has no active subscription.
Usage summary
Returns aggregated usage for the current billing period.
Query parameters
- Name
metric- Type
- string
- Description
The metric name to query (e.g.
api_calls,storage_gb).
Response 200
{
"metric": "api_calls",
"quantity": 8423,
"period_start": "2025-04-01T00:00:00Z",
"period_end": "2025-05-01T00:00:00Z",
"limit": 10000
}
limit is the usage cap configured on the plan, if any. null means unlimited.
List invoices
Returns the current user's invoice history, most recent first.
Query parameters
- Name
limit- Type
- integer
- Description
Number of invoices to return. Maximum 100.
- Name
starting_after- Type
- string
- Description
Cursor-based pagination. Pass the ID of the last invoice from the previous page.
Response 200
{
"invoices": [
{
"id": "inv_abc123",
"amount_due": 2900,
"amount_paid": 2900,
"currency": "usd",
"status": "paid",
"period_start": "2025-04-01T00:00:00Z",
"period_end": "2025-05-01T00:00:00Z",
"created_at": "2025-04-01T00:00:05Z",
"pdf_url": "/api/proxy/billing/invoices/inv_abc123/pdf"
}
],
"has_more": false
}
Download invoice PDF
Returns the PDF for a specific invoice as a binary stream.
Response 200
Binary PDF data with Content-Type: application/pdf and Content-Disposition: attachment; filename="invoice_{id}.pdf".
Returns 404 if the invoice does not belong to the authenticated user.
Download example
curl https://your-authgate-instance.com/api/proxy/billing/invoices/inv_abc123/pdf \
-H "Authorization: Bearer <session_token>" \
--output invoice.pdf