Overview
Billing endpoints manage your Contox subscription, usage tracking, and credit purchases. Contox uses Stripe for payment processing.
Create checkout session
Creates a Stripe checkout session for upgrading or subscribing to a plan.
POST /api/billing/checkout
Request body
| Field | Type | Required | Description |
|---|---|---|---|
planId | string | Yes | The plan to subscribe to |
seats | number | No | Number of seats (for team plans) |
successUrl | string | No | Redirect URL after successful checkout |
cancelUrl | string | No | Redirect URL if checkout is cancelled |
Response
{
"url": "https://checkout.stripe.com/c/pay/..."
}
Redirect the user to the returned URL to complete the checkout.
Open billing portal
Creates a Stripe billing portal session for managing payment methods, viewing invoices, and updating subscriptions.
POST /api/billing/portal
Response
{
"url": "https://billing.stripe.com/p/session/..."
}
Cancel subscription
Cancels the current subscription at the end of the billing period.
POST /api/billing/cancel
Response
{
"status": "cancelled",
"cancelAt": "2025-02-15T00:00:00Z"
}
The subscription remains active until the end of the current billing period.
Get usage
Retrieves current usage statistics for your account.
GET /api/billing/usage
Response
{
"plan": "team",
"period": {
"start": "2025-01-01T00:00:00Z",
"end": "2025-02-01T00:00:00Z"
},
"usage": {
"sessions": { "used": 45, "limit": 200 },
"events": { "used": 1250, "limit": 10000 },
"enrichments": { "used": 32, "limit": 100 },
"storage": { "used": 52428800, "limit": 536870912 }
}
}
Get credits
Retrieves the current credit balance and transaction history.
GET /api/billing/credits
Response
{
"balance": 5200000,
"autoRecharge": {
"enabled": true,
"threshold": 500000,
"packId": "credits_2_5m",
"spendingLimit": 5000
},
"transactions": [
{
"id": "txn_abc123",
"type": "purchase",
"amount": 2500000,
"price": 1000,
"createdAt": "2025-01-15T10:00:00Z"
},
{
"id": "txn_def456",
"type": "usage",
"amount": -300000,
"description": "Enrichment - session sess_xyz",
"createdAt": "2025-01-20T12:00:00Z"
}
]
}
Credit amounts are in token units. Prices are in cents (EUR).
Purchase credits
Purchases a credit pack.
POST /api/billing/credits/purchase
Request body
| Field | Type | Required | Description |
|---|---|---|---|
packId | string | Yes | The credit pack ID |
Available packs
| Pack ID | Tokens | Price |
|---|---|---|
credits_1m | 1,000,000 | 5.00 EUR |
credits_2_5m | 2,500,000 | 10.00 EUR |
credits_7m | 7,000,000 | 25.00 EUR |
credits_15m | 15,000,000 | 50.00 EUR |
Response
{
"transactionId": "txn_ghi789",
"balance": 7700000,
"purchased": 2500000
}
Auto-recharge
Credits can be set to auto-recharge when the balance falls below a threshold. Configure this in the dashboard under Billing > Credits. The default spending limit is 50.00 EUR per billing period. Credits never expire.
Next steps
- Credits Guide -- Detailed credit system documentation
- Dashboard Billing -- Manage billing in the UI
- Pricing -- Plan comparison