Billutant API

Create invoices from external tools

The External API connects your own systems, automations, and integrations with Billutant. One token is enough to manage customers, items, templates, and invoices for the connected tenant.

View endpoints Create token in Billutant

Quick start

POST /invoices
Authorization: Bearer bt_live_...
Content-Type: application/json

{
  "customerId": "customer_123",
  "itemIds": ["item_setup", "item_monthly"],
  "draft": false,
  "send": true,
  "emailTemplateId": "template_invoice"
}

Quick start

Reach your first API request in minutes

The integration needs no OAuth flow and no local SDK installation. A secret, a base URL, and JSON are enough for the first test.

1. Create token

Create an API token in Billutant and store it as a secret in the external system.

2. Use the test host

Start against the test environment until payload, status, and sending work cleanly.

3. Send request

Send JSON with customerId and itemIds to /invoices. Production later only needs the other base URL.

Access

Base URLs and authentication

Tokens are created in Billutant settings. Every request uses the header Authorization: Bearer TOKEN and is automatically rate-limited.

API hosts

Production and test use the same path under /api/v1.

Productionhttps://app.billutant.com/api/v1

Testhttps://test.billutant.com/api/v1

Bearer token

The token is only visible once. Store it as a secret in your external tool.

Header

Authorization: Bearer bt_live_...

JSON requests

Write requests use application/json. GET endpoints do not need a body.

Header

Content-Type: application/json

Rate limit

By default, 60 requests per minute and token are planned. If exceeded, the API responds with 429.

Endpoints

Invoices, customers, items, and templates

The invoice API is intentionally lean: customers and items are referenced by ID, and Billutant sets the invoice date automatically.

POST

/invoices

Create invoice

Creates an invoice from an existing customer ID and item IDs. Optionally sends it right away.

GET

/invoices

List invoices

Returns the invoices for the connected Billutant tenant.

GET

/invoices/{id}

Retrieve invoice

Reads a single invoice when it belongs to the tenant connected to the token.

PATCH

/invoices/{id}

Update draft

Updates only invoices in draft status. Finalized invoices stay locked.

POST

/invoices/{id}/send

Send invoice

Sends an existing invoice that is not saved as a draft with emailTemplateId.

DELETE

/invoices/{id}

Not allowed

Invoices cannot be deleted through the API.

Invoice payload

Minimal request

customerId and itemIds are required. send automatically sends the invoice when a valid emailTemplateId is provided and the customer has a valid email address.

createDate is not accepted and is set by Billutant.

draft: true creates a draft.

draft and send cannot both be true.

PATCH /invoices/{id} can change drafts, but cannot send them.

POST /invoices/{id}/send only needs emailTemplateId in the body.

DELETE /invoices/{id} is blocked.

curl

curl -X POST https://test.billutant.com/api/v1/invoices \
  -H "Authorization: Bearer bt_live_..." \
  -H "Content-Type: application/json" \
  -d '{"customerId":"customer_123","itemIds":["item_setup"],"send":false}'

Response

{
  "success": true,
  "data": {
    "id": "invoice_123",
    "invoiceNumber": "2026-0012",
    "status": "pending",
    "customerId": "customer_123",
    "files": ["2026-0012.pdf"],
    "sent": true,
    "draft": false
  }
}

Error handling

Handle status codes first

For robust integrations, the client should evaluate the HTTP status first and only then process the JSON response.

200 / 201

Successful

The request was processed. For POST /invoices, data contains the created invoice.

400

Check payload

Required fields are missing or rules such as draft and send were violated.

401

Check token

The bearer token is missing, invalid, or stored incorrectly in the external tool.

403

Enable feature

The External Invoice API has not yet been enabled for the connected tenant.

404

Check resource

The requested ID does not exist or does not belong to the tenant connected to the token.

405

Change method

The route exists, but the HTTP method is not allowed there, for example DELETE /invoices/{id}.

429

Retry later

The rate limit was reached. Clients should retry with a delay.

Fetch example

async function createBillutantInvoice(token) {
  const response = await fetch('https://test.billutant.com/api/v1/invoices', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      customerId: 'customer_123',
      itemIds: ['item_setup'],
      send: false,
    }),
  });

  const payload = await response.json();

  if (!response.ok) {
    throw new Error(payload.error || `Billutant API request failed with ${response.status}`);
  }

  return payload.data;
}

Error response

{
  "success": false,
  "error": "emailTemplateId is required when send is true."
}

CRUD

Master data for external workflows

Customers, items, and email templates can be maintained directly via the API so external systems do not need manual preparation in Billutant.

GET

/customers

List customers

Lists existing customers for selection in external tools.

POST

/customers

Create customer

Creates a customer. Company, name, or email is required for identification.

GET

/customers/{id}

Retrieve customer

Reads a single customer when it belongs to the tenant connected to the token.

PATCH

/customers/{id}

Update customer

Changes master data for an existing customer.

DELETE

/customers/{id}

Delete customer

Deletes customers when external workflows explicitly need it.

GET

/items

List items

Reads products and services used as invoice line items.

POST

/items

Create item

Stores a service with name, description, price, tax, and unit.

GET

/items/{id}

Retrieve item

Reads a single product or service from the connected tenant.

PATCH

/items/{id}

Update item

Changes name, description, price, tax, or unit for an item.

DELETE

/items/{id}

Delete item

Deletes an item when external workflows no longer need it.

GET

/email-templates

List templates

Reads email templates used for automatic delivery.

POST

/email-templates

Create template

Creates a template with type, label, subject, and body for invoice delivery.

GET

/email-templates/{id}

Retrieve template

Reads a single email template from the connected tenant.

PATCH

/email-templates/{id}

Update template

Updates type, label, subject, body, or reminder parameters for a template.

DELETE

/email-templates/{id}

Delete template

Deletes an email template when it is no longer used.

Ready to start

Create a token and send the first test request

Use the test environment first. Once the payload and delivery work as expected, switch only the base URL to production in your external tool.

Go to settings

POST /invoices Authorization: Bearer bt_live_... Content-Type: application/json { "customerId": "customer_123", "itemIds": ["item_setup", "item_monthly"], "draft": false, "send": true, "emailTemplateId": "template_invoice" }

Minimal request

customerId and itemIds are required. send automatically sends the invoice when a valid emailTemplateId is provided and the customer has a valid email address.

createDate is not accepted and is set by Billutant.

draft: true creates a draft.

draft and send cannot both be true.

PATCH /invoices/{id} can change drafts, but cannot send them.

POST /invoices/{id}/send only needs emailTemplateId in the body.

DELETE /invoices/{id} is blocked.

curl -X POST https://test.billutant.com/api/v1/invoices \ -H "Authorization: Bearer bt_live_..." \ -H "Content-Type: application/json" \ -d '{"customerId":"customer_123","itemIds":["item_setup"],"send":false}'

{ "success": true, "data": { "id": "invoice_123", "invoiceNumber": "2026-0012", "status": "pending", "customerId": "customer_123", "files": ["2026-0012.pdf"], "sent": true, "draft": false } }

Handle status codes first

For robust integrations, the client should evaluate the HTTP status first and only then process the JSON response.

200 / 201

Successful

The request was processed. For POST /invoices, data contains the created invoice.

400

Check payload

Required fields are missing or rules such as draft and send were violated.

401

Check token

The bearer token is missing, invalid, or stored incorrectly in the external tool.

403

Enable feature

The External Invoice API has not yet been enabled for the connected tenant.

404

Check resource

The requested ID does not exist or does not belong to the tenant connected to the token.

405

Change method

The route exists, but the HTTP method is not allowed there, for example DELETE /invoices/{id}.

429

Retry later

The rate limit was reached. Clients should retry with a delay.

async function createBillutantInvoice(token) { const response = await fetch('https://test.billutant.com/api/v1/invoices', { method: 'POST', headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ customerId: 'customer_123', itemIds: ['item_setup'], send: false, }), }); const payload = await response.json(); if (!response.ok) { throw new Error(payload.error || `Billutant API request failed with ${response.status}`); } return payload.data; }