Skip to main content

​
Base URL

https://api.boxbilling.org/v1

​
Authentication

All API endpoints (except organization creation) require a Bearer token in the Authorization header: 
curl https://api.boxbilling.org/v1/customers \
  -H "Authorization: Bearer bxb_live_abc123..."
API keys are created when you set up an organization. Each key is associated with a single organization and scopes all requests to that organization’s data.

​
Creating an API key

POST /v1/organizations/current/api_keys
{
  "name": "Production Key"
}
The response includes raw_key — save this immediately, it’s only shown once. Subsequent API calls return only the key prefix.

​
Key management

  • Keys can be revoked via DELETE /v1/organizations/current/api_keys/{id}
  • Keys can have optional expiration dates
  • The last_used_at timestamp is updated on each successful authentication

​
Pagination

List endpoints support pagination via query parameters:
ParameterDefaultRangeDescription
skip0>= 0Number of records to skip
limit1001–1000Maximum records to return
The total count is returned in the X-Total-Count response header: 
curl "https://api.boxbilling.org/v1/customers?skip=0&limit=25" \
  -H "Authorization: Bearer $API_KEY"

# Response headers:
# X-Total-Count: 142

​
Error responses

StatusDescription
400Bad request — validation error or invalid state transition
401Unauthorized — missing, invalid, revoked, or expired API key
404Not found — resource does not exist
409Conflict — duplicate resource (unique constraint violation)
422Unprocessable entity — validation error
429Rate limited — too many requests (events endpoint)

​
Rate limiting

The events endpoint (/v1/events) is rate-limited per organization. Default: 1000 requests per minute. Returns 429 when exceeded. All other endpoints are not rate-limited.

​
OpenAPI specification

The full OpenAPI 3.x specification is available at: 
https://demo-api.boxbilling.org/openapi.json

OpenAPI Specification

View the complete OpenAPI spec