The Octobill API lets your own tools record metered usage and seat counts against a subscription, read back aggregated usage for a billing period, and receive signed webhook events.
Create an API key in Settings, record a metered usage event or seat count against a subscription, read back aggregated usage for a billing period, and receive signed webhook events.
Authenticate every request with an API key sent as an Authorization: Bearer ob_live_… header. Keys are scoped to a single merchant account.
The API is served under https://www.octobill.it/api/v1. The version is pinned in the path.
Errors return a JSON body with an error message and a stable code. Documented codes include API_KEY_MISSING, API_KEY_INVALID, VALIDATION_FAILED, USE_SEATS_ENDPOINT, INVALID_WINDOW, NO_BILLING_PERIOD, ACCOUNT_SUSPENDED, ACCOUNT_DELETED, ACCOUNT_PAUSED, SUBSCRIPTION_NOT_FOUND, IDEMPOTENCY_KEY_REUSED, RATE_LIMITED.
Requests are rate limited per API key. When the limit is exceeded the API returns 429 with a Retry-After header.
Send an idempotencyKey with write requests so retries are safe. Reusing a key with a different payload returns a 409 conflict.
Record usage (POST /subscriptions/:id/usage), set seat counts (POST /subscriptions/:id/seats), read aggregated usage for a billing period (GET /subscriptions/:id/usage), and identify the merchant for a key (GET /me).
Subscribe to signed webhook events delivered with an HMAC-SHA256 signature. Event types include usage.recorded, seats.updated, subscription.created, subscription.renewed, subscription.canceled, subscription.paused, invoice.paid, invoice.payment_failed.
Questions? Email support@octobill.it.