API keys and authentication
The REST API v1 is available at https://www.claribill.com/api/v1. Its machine-readable description is available at /openapi.json. See the API reference for all endpoints and fields.
Authentication
Send the API key in the Authorization header:
Authorization: Bearer sk_live_...
Create a key under Settings → API keys. This requires the “API keys” permission (owners and administrators by default).
A key is not bound to a user, a role or document categories: within its scopes it reaches every document of the company, regardless of the role and categories of the person who creates it.
Where an action needs an acting user (for example as the creator of a document), the company’s owner is used; with several owners, the one with the oldest membership. The audit log marks such actions as API actions and names the key used.
- Validate the Bearer header (401 for a missing/invalid header or unknown key).
- Check the apiAccess plan gate and reserve monthly quota as an ApiLog entry (403 code: "plan_no_access", 429 code: "quota_exceeded").
- Check the route's required scopes against the key's scopes (403 with requiredScopes if missing).
- Check the per-key rate limit (429, only with configured Upstash).
Plan access and monthly quota
API access requires the apiAccess feature (STARTER, PROFESSIONAL, ENTERPRISE). Monthly quota: STARTER: 10,000 calls/month, PROFESSIONAL: 50,000 calls/month, ENTERPRISE: 250,000 calls/month. When exhausted, the API responds with 429 and code: "quota_exceeded".
Rate limit
100 requests/minute per API key. Active only when Upstash (Redis) is configured. Quota reservations are released again for 403/429 responses.
Response envelope
All v1 endpoints that return data wrap the payload in { data: … }. List endpoints also return { data: [...], pagination: { total, limit, offset, hasMore } } (or meta for some resources). Successful actions without a return object respond with { success: true }. Blog routes under /api/v1/blog/** (platform admins only) are an exception: lists use their own key ({ posts }, { categories }, { tags }, { media }), individual objects have no envelope, AI jobs use { job } and deletions return { ok: true }.
Single object: { data: { id, ... } }List: { data: [ { id, ... }, ... ], pagination: { total, limit, offset, hasMore } }Action without a return object: { success: true }
Pagination
All list endpoints support the same pagination:
limit — Page size (Default: 50)offset — Offset (Default: 0)
Maximum limit: 100. { pagination: { total, limit, offset, hasMore } } (some older resources also include has_more or use the key meta instead of pagination; see the relevant endpoint).
Error format
{ error: string, code?: string, allowedValues?: string[] }| Status | Meaning |
|---|
| 400 | Invalid input: required field, enum value, number/date format or business rule. |
| 401 | Authorization header missing, not a Bearer header, or the key is invalid/inactive. |
| 403 | Missing scope (requiredScopes in the response), plan without API access (code: "plan_no_access"), or a plan limit is exhausted. |
| 404 | The record does not exist or belongs to another company. Other companies' data is never returned. |
| 409 | State conflict: incorrect status for the action, concurrent change, or a number/reference already taken. |
| 429 | Monthly quota exhausted (code: "quota_exceeded") or rate limit reached. |
| 500 | Unexpected internal error. |
| 502 | A dependent external service failed, such as email delivery or S3. |
Naming conventions
Request bodies generally accept both camelCase and snake_case for the same field, for example customerNumber = customer_number.
Responses using camelCase throughout: invoices (core routes, versions, corrections), quotes, order-confirmations, delivery-notes, orders, recurring-schedules, documents, products, company
Responses retaining snake_case for compatibility: customers (camelCase with individual snake_case aliases such as tax_id, created_at), credit-notes (snake_case throughout, with camelCase aliases for new fields), invoice payments & dunning (snake_case, with camelCase aliases for new fields), webhooks (snake_case)
Permissions (scopes)
Each API key is assigned individual scopes when created:
| Scope | Label | Description |
|---|
invoices:read | Read invoices | Read invoices, credit notes, payments and reminder status; retrieve PDFs |
invoices:write | Edit invoices | Create, update and send invoices and credit notes; record payments and reminders |
customers:read | Read customers | Access customer lists and details |
customers:write | Edit customers | Create, update, archive and delete customers |
products:read | Read products | Access product lists |
products:write | Edit products | Create and update products |
quotes:read | Read quotes | Read quotes and their PDFs |
quotes:write | Edit quotes | Create, update, send and convert quotes |
order-confirmations:read | Read order confirmations | Read order confirmations and their PDFs |
order-confirmations:write | Edit order confirmations | Create, update, send and convert order confirmations |
delivery-notes:read | Read delivery notes | Read delivery notes and their PDFs |
delivery-notes:write | Edit delivery notes | Create, update and send delivery notes; convert them to invoices |
orders:read | Read orders | Read orders, quantities and statistics |
orders:write | Edit orders | Create and update orders; manage quantities |
recurring:read | Read recurring invoices | Read recurring invoice schedules |
recurring:write | Edit recurring invoices | Create, update and pause schedules; generate invoices from them |
documents:read | Read documents | Read document storage and download files |
documents:write | Edit documents | Upload, update, archive and delete documents |
exports:read | Exports | Generate accounting exports (CSV, DATEV, BMD, VAT return) and customer CSV |
direct-debits:write | Create SEPA direct debits | Create SEPA batches and their direct debit files (PAIN.008); the invoices are blocked from further exports until the batch is discarded |
company:read | Read company details | Read company details, number ranges and plan features |
webhooks:read | Read webhooks | Read webhook endpoints and deliveries |
webhooks:write | Manage webhooks | Create, update and delete webhook endpoints |
The additional scopes blog:read, blog:write, blog:publish, blog:moderate belong to the internal blog CMS. They are reserved for platform admins and cannot be assigned to regular companies.
Webhook events (Enterprise plan)
Webhook endpoints can subscribe to the following events; WEBHOOK_TEST is only sent by the test delivery and cannot be subscribed to. See the Webhooks resource in the API reference for details.
| Event | Trigger |
|---|
| INVOICE_CREATED | Invoice created through a dashboard action or POST /api/v1/invoices. |
| INVOICE_UPDATED | Invoice changed without a status transition (PUT /api/v1/invoices/{id}). |
| INVOICE_SENT | Invoice emailed to the customer. |
| INVOICE_PAID | Payment recorded that settles an invoice in full. |
| INVOICE_OVERDUE | An unpaid invoice passes its due date. |
| INVOICE_CANCELLED | Invoice or credit note cancelled. |
| CREDIT_NOTE_CREATED | Credit note created. |
| CREDIT_NOTE_PAID | Credit note payout executed. |
| PAYOUT_APPROVED | Credit note payout approved for execution. |
| PAYOUT_EXECUTED | Payout executed successfully. |
| PAYOUT_FAILED | Payout execution failed. |
| PAYOUT_CANCELLED | Payout cancelled before execution. |
| CUSTOMER_CREATED | Customer created. |
| CUSTOMER_UPDATED | Customer updated. |
| CUSTOMER_DELETED | Customer deleted. |
| REMINDER_SENT | Payment reminder or formal reminder sent. |
| REMINDER_ESCALATED | Reminder escalated to the next stage. |
| BLOG_POST_CREATEDPlatform | Blog post created, platform blog only. |
| BLOG_POST_UPDATEDPlatform | Blog post updated, platform blog only. |
| BLOG_POST_PUBLISHEDPlatform | Blog post published or scheduled publication triggered, platform blog only. |
| BLOG_POST_UNPUBLISHEDPlatform | Blog post unpublished/archived, platform blog only. |
| BLOG_COMMENT_CREATEDPlatform | New blog comment submitted, platform blog only. |
| BLOG_COMMENT_APPROVEDPlatform | Blog comment approved/moderated, platform blog only. |
| WEBHOOK_TEST | Test event from POST /api/v1/webhooks/{id}/test, without a business object. Cannot be subscribed to; the receiver acknowledges it without processing. |
MCP / Codex plugin
An MCP plugin lets AI assistants such as Codex create invoice drafts in chat. See Claribill in Codex for details.