API Reference
Complete API documentation for the Lumen billing platform
API Reference
Welcome to the Lumen API reference. This documentation covers all available endpoints for managing your billing, subscriptions, and usage-based pricing.
Authentication
All API requests require authentication using a Bearer token. Include your secret API key in the Authorization header:
curl -X GET "https://api.getlumen.dev/v1/customers" \
-H "Authorization: Bearer sk_live_..."Never expose your secret API key in client-side code. Use publishable keys for frontend integrations.
Base URL
All API endpoints are relative to:
https://api.getlumen.dev/v1Resources
Core Resources
| Resource | Description |
|---|---|
| Customers | Manage customer accounts |
| Plans | Define subscription plans with features |
| Prices | Configure pricing for plans |
| Subscriptions | Manage customer subscriptions |
Billing
| Resource | Description |
|---|---|
| Invoices | View and manage invoices |
| Payments | Track payment history |
| Payment Methods | Manage customer payment methods |
Usage & Metering
| Resource | Description |
|---|---|
| Events | Ingest usage events for metering |
| Metrics | Define and query usage metrics |
| Entitlements | Check feature access |
| Credits | Manage credit balances |
Features & Configuration
| Resource | Description |
|---|---|
| Features | Define product features |
| Pricing Tables | Configure embeddable pricing tables |
| Tax | Tax configuration |
| API Keys | Manage API keys |
Seat-Based Billing
| Resource | Description |
|---|---|
| Seats | Manage seat-based subscriptions |
| Enrollment | Auto-enrollment rules |
Merchant & Payment Providers
| Resource | Description |
|---|---|
| Merchants | Merchant account management |
| Stripe | Stripe configuration |
| Dodo | Dodo Payments configuration |
Integrations
Rate Limits
The API enforces rate limits to ensure stability:
- Standard: 100 requests per minute
- Events ingestion: 1000 events per minute
Error Handling
The API uses standard HTTP status codes:
| Code | Description |
|---|---|
200 | Success |
201 | Created |
400 | Bad Request - Invalid parameters |
401 | Unauthorized - Invalid or missing API key |
404 | Not Found - Resource doesn't exist |
429 | Too Many Requests - Rate limited |
500 | Internal Server Error |