---
title: "Formats and pagination · EenFactuurMaken.nl"
description: "The conventions of the EenFactuurMaken.nl REST API. JSON, amounts in cents, decimals as strings, dates, lists and pagination, filtering, sorting and PATCH."
url: "https://eenfactuurmaken.nl/en/docs/api/conventions"
markdown_url: "https://eenfactuurmaken.nl/en/docs/api/conventions.md"
language: "en-GB"
---

# Formats and pagination

The conventions of the EenFactuurMaken.nl REST API. JSON, amounts in cents, decimals as strings, dates, lists and pagination, filtering, sorting and PATCH.

## 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:

```json
{
  "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:

| Parameter | Values |
| --- | --- |
| `status` | `draft`, `issued`, `sent`, `paid`, `cancelled`, `overdue` (unpaid and late), `open` (issued or sent, unpaid) |
| `kind` | `invoice` or `credit_note` |
| `customerId` | Invoices for one customer |
| `q` | Search by number, customer or reference |
| `from`, `to` | Invoice date from / up to and including (`YYYY-MM-DD`) |
| `sort` | `issueDate`, `number`, `total`, `dueDate`, `createdAt`; prefix with `-` for descending. Default `-createdAt` |

Example: all overdue invoices, oldest due date first:

```bash
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](https://eenfactuurmaken.nl/en/docs/credit-notes).

## 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](https://eenfactuurmaken.nl/en/docs/vat/treatments#suggestion).

## 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](https://eenfactuurmaken.nl/en/docs/invoices/checks) (drafts only);
- `publicUrl`: the [online invoice](https://eenfactuurmaken.nl/en/docs/invoices/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.

Last updated on 13 October 2026