Invoice guide
On this page
Purpose
This is the shortest path to a valid invoice. Request and response fields that are not repeated here are in the invoice reference and the full API reference.
Before you create one
- Authenticate with an API key or an OAuth token.
- Take a client id from
GET /api/clients. - Take a series id from
GET /api/series, or plan to sendcustomSerialNumber. The two are mutually exclusive. Sending both returns400 INVALID_SERIAL_CONFIG. Publishing without either returns400 MISSING_SERIAL_CONFIG.
Create
POST /api/invoices
X-API-Key: bk_user_<key>
Content-Type: application/json
{
"clientId": "60f7b1b9c9e7b4a1e8d1c2b4",
"seriesId": "60f7b1b9c9e7b4a1e8d1c2b5",
"issueDate": "2026-03-15",
"dueDate": "2026-04-14",
"services": [
{
"description": "Servicii software",
"quantity": 1,
"unitPrice": 1000,
"unitOfMeasure": "buc",
"vatRate": 21
}
],
"language": "ro"
}
services allows 1 to 50 lines. description is at most 100 characters. For a Romanian client, vatRate must be one of 0, 9, 11, 21. Any other rate returns 400 INVALID_VAT_RATE.
Set draft to true to save a draft. A draft does not consume a series number until it is published. Unknown JSON properties are rejected with 400 VALIDATION_ERROR.
Currency defaults to RON. For another currency, send exchangeRate as RON per 1 unit of that currency. e-Factura uses that rate for the mandatory RON tax total.
A published invoice returns 201 with data.invoiceId and data.serialNumber.
Statuses
The invoice list filter in the published OpenAPI snapshot accepts unpaid, partial, paid, and canceled. The application also stores payment status storno, a document lifecycle (draft, published, sent, paid, overdue, cancelled), and an e-Factura status. Invoices that were sent to e-Factura include spvLifecycleState. The Romanian labels are documented in Statusurile facturilor.
paid means recorded payments cover totalWithVAT. Overpayment is detected.
After the invoice exists
The reference documents these operations. Paths are under https://app.billyou.ro/api:
| Action | Method and path |
|---|---|
| List and filter | GET /invoices |
| Read one | GET /invoices/{id} |
| PDF URL | GET /invoices/{id}/pdf |
| Issued e-Factura XML | GET /invoices/{id}/xml |
POST /invoices/{id}/email | |
| Payment status | GET /invoices/{id}/paymentstatus |
| Record a payment | POST /invoices/{id}/payments |
| Cancel | POST /invoices/{id}/cancel |
| Delete | DELETE /invoices/{id} (only the last invoice in the series; otherwise cancel) |
| Submit to e-Factura | POST /invoices/{id}/efactura/submissions |
Payments accept amount, paymentDate, and optionally paymentMethod (cash, bank_transfer, card, check, other), currency, exchangeRate (required when the currency is not RON), reference, and notes. You cannot record a payment on a draft or a cancelled invoice. A proforma is not payable; the app finalizes it into a fiscal invoice first.
Cancel and storno are different operations. Storno creates a reversal document and can emit invoice.storno.issued. See Webhooks. Release 2.3.3 includes storno and proforma finalization in the application. The OpenAPI snapshot published on the developer portal does not list those two routes, so this guide does not give paths for them.
e-Factura submission, polling, and sandbox modes are in the e-Factura reference and in Environments and sandboxes.