Formats and pagination

JSON

You send JSON with Content-Type: application/json and get JSON back. Exceptions: PDF (application/pdf), UBL (application/xml), ZIP exports and logo uploads (multipart/form-data with a file field).

Amounts in cents

All amounts are whole cents in fields ending in Cents: unitPriceCents: 8500 is €85.00. That way you never get rounding differences. Line prices are excluding VAT.

Credit notes store amounts as positive numbers. Make them negative yourself in reports.

Decimals as strings

Quantities, discounts, VAT rates and exchange rates are decimals. Send them as a string or a number: "2.5", 2.5 and "2,5" all work. You get them back as strings, for example "quantity": "2.5000", "vatRate": "21.00".

Dates

• Business dates (invoice date, due date, supply date) are YYYY-MM-DD, without a time. "Today" means today in the Netherlands.
• Timestamps (fields ending in At, like createdAt and paidAt) are ISO 8601 in UTC.

Ids

Ids are strings (uuids). You only see your own data: the id of something belonging to someone else simply returns 404 not_found.

Lists

Lists always return this:

{
  "data": [ { "id": "…", "number": "2026-0001" } ],
  "page": 1,
  "pageSize": 25,
  "total": 132
}

Page through them with page (from 1) and pageSize (default 25, maximum 100).

Filtering invoices

GET /invoices accepts these parameters:

Example: all overdue invoices, oldest due date first:

curl "https://eenfactuurmaken.nl/api/v1/invoices?status=overdue&sort=dueDate&pageSize=100" \
  -H "Authorization: Bearer $EENFACTUURMAKEN_API_KEY"

Search customers and products with q; include archived customers with includeArchived=true.

Creating and updating

• POST creates something and returns the new object (status 201). Actions like /issue and /mark-paid return the updated object (status 200).
• PATCH only changes the fields you send. Fields you leave out stay as they were. Send null (or "" for text) to clear a field.
• For invoices, lines in a PATCH replaces all lines. So send the complete list.
• DELETE returns a short response, like { "id": "…", "deleted": true }. A customer or product that's still used on invoices is archived instead of deleted.

You can no longer change a finalised invoice with PATCH (409 invoice_locked). Use a credit note.

Defaults

If you leave out fields when creating an invoice, we fill them in like the app does: today's dates, the payment term, currency, language and VAT treatment of the customer or your business, and supplyType from the customer or your business (default services). See Choosing a VAT treatment.

The invoice object

GET /invoices/{id} returns all the invoice's fields, plus:

• lines (in order) and the totals (subtotalCents, vatTotalCents, totalCents);
• displayStatus: the status, with overdue for late invoices;
• seller and customer: for a finalised invoice the frozen details, for a draft the current ones;
• compliance: the checks (drafts only);
• publicUrl: the online invoice, or null;
• firstViewedAt, viewedAt and viewCount: when your customer viewed it;
• creditNotes: credit notes for this invoice;
• creditedInvoiceNumber and creditedInvoiceDate on a credit note.

Lists return a short version: id, kind, status, displayStatus, number, dates, customer name, total, currency and paid date.