API Reference

Base URL

https://api.boxbilling.com/v1

Authentication

All API endpoints (except organization creation) require a Bearer token in the Authorization header:

curl https://api.boxbilling.com/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:

Parameter	Default	Range	Description
skip	0	>= 0	Number of records to skip
limit	100	1–1000	Maximum records to return

The total count is returned in the X-Total-Count response header:

curl "https://api.boxbilling.com/v1/customers?skip=0&limit=25" \
  -H "Authorization: Bearer $API_KEY"

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

Error responses

Status	Description
400	Bad request — validation error or invalid state transition
401	Unauthorized — missing, invalid, revoked, or expired API key
404	Not found — resource does not exist
409	Conflict — duplicate resource (unique constraint violation)
422	Unprocessable entity — validation error
429	Rate 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.com/openapi.json

OpenAPI Specification View the complete OpenAPI spec