BillyouHelp

↑↓ select · ↵ open · Esc close

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

  1. Authenticate with an API key or an OAuth token.
  2. Take a client id from GET /api/clients.
  3. Take a series id from GET /api/series, or plan to send customSerialNumber. The two are mutually exclusive. Sending both returns 400 INVALID_SERIAL_CONFIG. Publishing without either returns 400 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:

ActionMethod and path
List and filterGET /invoices
Read oneGET /invoices/{id}
PDF URLGET /invoices/{id}/pdf
Issued e-Factura XMLGET /invoices/{id}/xml
EmailPOST /invoices/{id}/email
Payment statusGET /invoices/{id}/paymentstatus
Record a paymentPOST /invoices/{id}/payments
CancelPOST /invoices/{id}/cancel
DeleteDELETE /invoices/{id} (only the last invoice in the series; otherwise cancel)
Submit to e-FacturaPOST /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.