Conventions
Amounts, dates, references, missing values and lists — the same everywhere in the API.
Requests and answers
JSON in UTF-8. Field names are English.
A field the API does not know is refused, not ignored: 422 validation_failed. A typo must not make a value
silently disappear from an invoice.
A value that is not known is null in an answer, never left out.
Amounts
Amounts are decimal strings in euros with up to two decimals, in requests and in answers: "1190.00". A number is
refused where an amount is expected — floating point has no place on an invoice. Quantities may be a number or a
decimal string with up to four decimals.
The API bills in EUR only, at VAT rates 0, 7 and 19. A cancellation invoice has negative amounts.
Revenue-share balances and statements are in cents (integers), as their field names say: net_cents.
Webhooks are different
In a webhook payload, amounts are JSON numbers with two decimals next to currency.
Dates and times
Dates are YYYY-MM-DD. Points in time are UTC: YYYY-MM-DDTHH:MM:SSZ.
Your references
You address what you keep in AlphaCount by your own ids:
| Pattern | Example | |
|---|---|---|
source — your product | ^[a-z0-9][a-z0-9_-]{0,49}$ | myapp |
external_ref — your id | ^[A-Za-z0-9][A-Za-z0-9._:@+-]{0,254}$ | cust-42, order:2026-1001 |
Both appear in URL paths, so neither contains a slash or a space. Per company there is at most one customer, product,
contract or partner for each (source, external_ref).
PUT …/by-ref/{source}/{external_ref} creates the record (201) or brings it to the state you send (200). A PUT
replaces: an optional field you leave out or send as null is cleared. What the API does not own — the customer
number, fields a person maintains in the app — stays as it is.
Lists
GET /invoices returns the most recently changed first, { "invoices": [...], "limit", "offset" }, with limit
1–500 (default 100) and offset. To keep a copy in sync, ask with changed_since for what moved since your last
run. The revenue-share lists take since.
Limits
AlphaCount does not publish a rate limit yet. Should one come, it will be in the changelog before it applies.