Billing API
With the billing API einvo keeps your customers and products, numbers invoices without gaps per company, generates the PINT AE UBL,
validates it, sends it and renders the bilingual (English/Arabic) PDF. Scope: billing.
Flow
GET /api/v1/billing/sellers: your companies (legalEntityId).POST /api/v1/billing/customers: the buyer, once.POST /api/v1/billing/invoices: a draft (editable withPUT, deletable).POST /api/v1/billing/invoices/{id}/issue: number, UBL, validation, Peppol delivery and FTA reporting in one step.GET /api/v1/billing/invoices/{id}/pdf: the PDF; payments withPOST …/payments, corrections withPOST …/credit-note.
curl https://api.einvo.ae/api/v1/billing/customers -H "Authorization: Bearer $EINVO_API_KEY" -H "Content-Type: application/json" -d '{
"legalName": "Noor Electronics LLC",
"endpointScheme": "0235", "endpointId": "1345678901",
"trn": "100134567890103",
"street": "Corniche Road 5", "city": "Abu Dhabi", "emirate": "AE-AZ", "countryCode": "AE",
"email": "ap@noor.example", "paymentTermsDays": 30
}'
curl https://api.einvo.ae/api/v1/billing/invoices -H "Authorization: Bearer $EINVO_API_KEY" -H "Content-Type: application/json" -d '{
"legalEntityId": "<seller id>",
"customerId": "<customer id>",
"buyerReference": "PO-7781",
"lines": [
{ "name": "Laptop", "itemType": "G", "quantity": 2, "unitCode": "H87", "unitPrice": 1000.00,
"taxCategory": "S", "taxRate": 5, "hsCode": "847130" },
{ "name": "Installation", "itemType": "S", "quantity": 3, "unitCode": "HUR", "unitPrice": 150.00,
"taxCategory": "S", "taxRate": 5 }
]
}'
curl -X POST https://api.einvo.ae/api/v1/billing/invoices/$INVOICE_ID/issue -H "Authorization: Bearer $EINVO_API_KEY"
# {"id":"...","number":"INV-2026-00017","status":"ISSUED","documentId":"...","totals":{...}}
Line fields: itemType G (goods) or S (services), unitCode (UN/ECE Rec. 20, e.g. H87 piece,
HUR hour, KGM), taxCategory S standard, Z zero rated, E exempt
(with exemptionCode/exemptionText), AE reverse charge, O out of scope, N margin scheme.
POST /api/v1/billing/preview returns the totals of a set of lines with the same rounding as issuing.
PINT AE scenarios
The UAE transaction type is the 8-position transactionFlags string (PINT AE ProfileExecutionID); positions, left to right:
| # | Flag | Also needed | Example |
|---|---|---|---|
| 1 | Free zone | beneficiaryId (BTAE-01) | 10000000 |
| 2 | Deemed supply | buyer = seller's own endpoint | 01000000 |
| 3 | Margin scheme | every line taxCategory: "N" | 00100000 |
| 4 | Summary invoice | periodStart, periodEnd | 00010000 |
| 5 | Continuous supply | periodStart, periodEnd recommended | 00001000 |
| 6 | Disclosed agent billing | principalId (BTAE-14, e.g. the principal's TRN) | 00000100 |
| 7 | E-commerce | delivery address | 00000010 |
| 8 | Export | delivery country, usually taxCategory: "Z" | 00000001 |
Flags can be combined (a free zone summary invoice is 10010000). Missing data is refused at draft or issue time with a
message naming the PINT AE rule (e.g. ibr-138-ae).
Foreign currency
{ "legalEntityId": "...", "customerId": "...",
"currency": "USD", "exchangeRate": 3.6725,
"lines": [ { "name": "Consulting", "itemType": "S", "quantity": 10, "unitCode": "HUR", "unitPrice": 200, "taxCategory": "S", "taxRate": 5 } ] }
Amounts are in the document currency; exchangeRate (AED per unit, at most 6 decimals) is mandatory for any currency other than AED and einvo adds the VAT amount in AED (ibr-159-ae).
Summary invoice
{ "legalEntityId": "...", "customerId": "...", "transactionFlags": "00010000",
"periodStart": "2026-11-01", "periodEnd": "2026-11-30",
"lines": [ { "name": "Deliveries November", "itemType": "G", "quantity": 42, "unitCode": "H87", "unitPrice": 85, "taxCategory": "S", "taxRate": 5 } ] }
Free zone supply
{ "legalEntityId": "...", "customerId": "...", "transactionFlags": "10000000",
"beneficiaryId": "JAFZA-123456",
"lines": [ { "name": "Steel coils", "itemType": "G", "quantity": 5, "unitCode": "TNE", "unitPrice": 2900, "taxCategory": "S", "taxRate": 5 } ] }
Margin scheme
{ "legalEntityId": "...", "customerId": "...", "transactionFlags": "00100000",
"lines": [ { "name": "Used car, VIN ...", "itemType": "G", "quantity": 1, "unitCode": "H87", "unitPrice": 48000, "taxCategory": "N", "taxRate": 0 } ] }
Disclosed agent billing
{ "legalEntityId": "...", "customerId": "...", "transactionFlags": "00000100", "principalId": "100555666700003",
"lines": [ { "name": "Hotel booking on behalf of principal", "itemType": "S", "quantity": 1, "unitCode": "C62", "unitPrice": 1200, "taxCategory": "S", "taxRate": 5 } ] }
Export of goods
{ "legalEntityId": "...", "customerId": "...", "transactionFlags": "00000001",
"deliveryStreet": "12 Harbour Road", "deliveryCity": "Mumbai", "deliveryCountry": "IN", "incoterms": "FOB",
"lines": [ { "name": "Dates, 10 kg cartons", "itemType": "G", "quantity": 200, "unitCode": "H87", "unitPrice": 95, "taxCategory": "Z", "taxRate": 0, "hsCode": "080410" } ] }
Reverse charge on goods
Domestic reverse charge goods (e.g. mobile phones, precious metals) use taxCategory: "AE", taxRate: 0, the goods type in
natureCode (DL8.48.3.1–3 or DL8.48.8.1–3) and the item's gtin.
Advance payments and retention
Issue the advance payment invoice first; on the final invoice list it in advanceInvoiceIds (GET /api/v1/billing/invoices/advance-candidates
lists the eligible ones) and einvo deducts it. POST /api/v1/billing/invoices/{id}/retention-release creates the draft that releases a retention.
VAT group members
Customers flagged vatGroupMember: true belong to the seller's VAT group: until the end of the grace period their invoices are validated and kept
(NOT_EXCHANGED) instead of being sent over Peppol and reported.
Credit notes
curl -X POST https://api.einvo.ae/api/v1/billing/invoices/$INVOICE_ID/credit-note -H "Authorization: Bearer $EINVO_API_KEY" \
-H "Content-Type: application/json" -d '{"reasonCode":"DL8.61.1.B"}'
# returns a credit note draft with the invoice lines; edit, then POST .../issue
See the API reference for payments, reminders, quotes, recurring invoices, delivery notes, purchase orders and reports.
With a sandbox key, issue validates without numbering or sending.