Receive invoices
Read the invoices your entities receive over the UAE Peppol network: list and fetch them, download each as a PDF, as the XML it came in, and its attachments. Read-only. To be told the moment one arrives, subscribe to the invoice.received webhook. Sending invoices is under Send invoices. Requires an access token.
What you get back
When a supplier sends an invoice to one of your entities over Peppol, it arrives in TaxStar on its own — there is nothing to call to receive it. Over this API received invoices are read-only: you list them, fetch one, and follow its status. Each one carries the whole document, so you can book it in your own system.
Keeping in sync
- Call
GET /oauth/invoices/received?date_from=with the time of your previous sync. It returns every invoice that arrived, or whose status moved, since then — newest first, 20 a page by default. Addsort=ascto process them oldest first. - Each item already carries the whole document in
invoice_data. Fetching it again by id only addsstatus_history. - Store the time you started this sync and use it as
date_fromnext time. Or register a webhook and be told when one arrives. A received-invoice event hasdirection: "received"and names the invoice byinvoice_numberand your entity'sreceiver_registry_code, not by id — pick it up from the list.
Example responses
A two-line standard-rated invoice from a supplier to an entity with no accounting system connected. Everything in it is invented; the shape is exactly what the API returns.
{
"invoice": {
"attachments": [ // the files the document came with; [] when none
{
"download_url": "https://dev-api.taxstar.app/einv/oauth/invoices/received/15231/attachments/0", // GET it with your access token
"filename": "delivery-note.pdf",
"index": 0, // position in this list, from 0
"mime_code": "application/pdf",
"size": 48213 // bytes
}
],
"date": "2026-10-18",
"deliveryDate": "",
"dueDate": "2026-11-17",
"fileType": "application/vnd.peppol.ubl-invoice+xml", // …ubl-credit-note+xml on a credit note
"final_status": "received", // received | sent (into your ERP) | failed | unknown
"id": 15231, // the gateway's id: a NUMBER. Use it in /received/{invoice_id}
"invoice_data": { // the document itself, in the gateway's layout
"E_Invoice": {
"Footer": {
"TotalAmount": "1102.5",
"TotalNumberInvoices": "1"
},
"Header": {
"AppId": "Peppol",
"Date": "2026-10-18",
"FileId": "15231",
"Version": "1.2"
},
"Invoice": {
"@invoiceId": "INV-2026-0418",
"@regNumber": "1009998887",
"@sellerRegnumber": "1007778889",
"AdditionalInformation": {
"CustomContent": {},
"InformationContent": null
},
"InvoiceInformation": {
"DocumentName": "Commercial Invoice", // the gateway's label; read InvoiceTypeCode instead
"DueDate": "2026-11-17",
"Extension": {
"@extensionId": "InvoiceInformationEN",
"CustomContent": {
"InvoiceInformationEN": {
"InvoiceTypeCode": "380", // 380 invoice, 381 credit note, 480 out of scope, 389 self-billed
"ProcessControl": {
"BusinessProcessType": "urn:peppol:bis:billing",
"SpecificationId": "urn:peppol:pint:billing-1@ae-1"
}
}
},
"InformationContent": null
},
"InvoiceDate": "2026-10-18",
"InvoiceNumber": "INV-2026-0418",
"PaymentMethod": "Credit transfer",
"Type": {
"@type": "DEB"
}
},
"InvoiceItem": {
"InvoiceItemGroup": {
"ItemEntry": [ // a LIST here; a single object when there is one line
{
"Description": "A4 copy paper",
"ItemDetailInfo": {
"ItemAmount": "10",
"ItemPrice": "45",
"ItemUnit": "EA"
},
"ItemReserve": {
"@extensionId": "ItemEntryEN",
"CustomContent": {
"ItemEntryEN": {
"ItemDetailedDescription": "A4 copy paper, 80gsm, box of 5 reams",
"ItemPriceInfo": null
}
},
"InformationContent": null
},
"ItemSum": "450",
"RowNo": "1",
"VAT": { // coarse (TAX / TAXEX / NOTTAX): use VATTreatment for the category
"@vatId": "TAX",
"SumBeforeVAT": "450",
"VATRate": "5",
"VATSum": "22.5"
},
"VATTreatment": { // this line's VAT treatment, read from the original UBL
"category": "S", // S, Z, E, O, AE or N
"description": "A4 copy paper, 80gsm, box of 5 reams",
"exemption_reason": "",
"exemption_reason_code": "",
"hs_code": "",
"index": 1,
"is_recognised_category": true,
"item_type": "",
"line_extension_amount": "450.0",
"line_id": "1",
"name": "A4 copy paper",
"percent": "5.0",
"quantity": "10.0",
"raw_category": "S",
"sac_code": "",
"sellers_item_id": "",
"standard_item_id": "",
"standard_item_scheme": "",
"vat_amount": ""
}
},
{
"Description": "Toner cartridge",
"ItemDetailInfo": {
"ItemAmount": "2",
"ItemPrice": "300",
"ItemUnit": "EA"
},
"ItemReserve": {
"@extensionId": "ItemEntryEN",
"CustomContent": {
"ItemEntryEN": {
"ItemDetailedDescription": "Black toner cartridge, high yield",
"ItemPriceInfo": null
}
},
"InformationContent": null
},
"ItemSum": "600",
"RowNo": "2",
"VAT": {
"@vatId": "TAX",
"SumBeforeVAT": "600",
"VATRate": "5",
"VATSum": "30"
},
"VATTreatment": {
"category": "S",
"description": "Black toner cartridge, high yield",
"exemption_reason": "",
"exemption_reason_code": "",
"hs_code": "",
"index": 2,
"is_recognised_category": true,
"item_type": "",
"line_extension_amount": "600.0",
"line_id": "2",
"name": "Toner cartridge",
"percent": "5.0",
"quantity": "2.0",
"raw_category": "S",
"sac_code": "",
"sellers_item_id": "",
"standard_item_id": "",
"standard_item_scheme": "",
"vat_amount": ""
}
}
]
}
},
"InvoiceParties": {
"BuyerParty": { // you: the entity the invoice was addressed to
"ContactData": {
"MailAddress": {
"City": "Dubai",
"Country": "AE",
"Extension": {
"@extensionId": "MailAddressEN",
"CustomContent": {
"MailAddressEN": {
"CountryCode": "AE",
"CountrySubDivision": "DXB"
}
},
"InformationContent": null
},
"PostalAddress1": "Sheikh Zayed Road"
}
},
"Extension": {
"@extensionId": "PartyEN",
"CustomContent": {
"PartyEN": {
"PartyElectronicAddress": {
"#text": "1009998887",
"@schemeId": "0235"
},
"PartyId": "1009998887"
}
},
"InformationContent": null
},
"Name": "Dubai Buyer LLC",
"RegNumber": "1009998887",
"VATRegNumber": "100999888700003" // the party's 15-digit TRN
},
"SellerParty": { // your supplier
"AccountInfo": {
"AccountNumber": "AE070331234567890123456",
"IBAN": "AE070331234567890123456"
},
"ContactData": {
"MailAddress": {
"City": "Dubai",
"Country": "AE",
"Extension": {
"@extensionId": "MailAddressEN",
"CustomContent": {
"MailAddressEN": {
"CountryCode": "AE",
"CountrySubDivision": "DXB"
}
},
"InformationContent": null
},
"PostalAddress1": "Warehouse 14, Al Quoz Industrial Area 3"
}
},
"Extension": {
"@extensionId": "PartyEN",
"CustomContent": {
"PartyEN": {
"PartyElectronicAddress": {
"#text": "1007778889",
"@schemeId": "0235"
},
"PartyId": {
"#text": "1007778889",
"@schemeId": "0235"
}
}
},
"InformationContent": null
},
"Name": "Example Supplies Trading LLC",
"RegNumber": "1007778889",
"VATRegNumber": "100777888900003"
}
},
"InvoiceSumGroup": {
"Currency": "AED",
"InvoiceSum": "1050",
"TotalSum": "1102.5", // amounts are strings, without trailing zeros
"TotalVATSum": "52.5",
"VAT": {
"@vatId": "TAX",
"Currency": "AED",
"SumBeforeVAT": "1050",
"VATRate": "5",
"VATSum": "52.5"
}
},
"PaymentInfo": {
"Currency": "AED",
"PayDueDate": "2026-11-17",
"PayToAccount": "AE070331234567890123456",
"PayToName": "Example Supplies Trading LLC",
"Payable": "YES",
"PayerName": "Dubai Buyer LLC",
"PaymentDescription": "INV-2026-0418",
"PaymentId": "INV-2026-0418",
"PaymentTotalSum": "1102.5"
}
}
}
},
"number": "INV-2026-0418",
"receivedAt": "2026-10-19T08:14:57.912Z",
"receivedFromOperator": "peppol",
"receiverName": "Dubai Buyer LLC",
"receiverRegistryCode": "1009998887", // your entity's Peppol id (first 10 digits of its TRN)
"senderName": "Example Supplies Trading LLC",
"senderRegistryCode": "1007778889", // the supplier's Peppol id
"status": { // the latest row; the whole trail is in status_history
"code": "RECEIVED_SUCCESSFULLY",
"created_at": "2026-10-19T08:15:04.880431+00:00",
"message": "Invoice received successfully from the Peppol network."
},
"status_history": [
{
"code": "RECEIVED_BY_PEPPOL",
"created_at": "2026-10-19T08:14:58.204117+00:00",
"message": "Invoice received by Peppol"
},
{
"code": "VALIDATION_IN_PROGRESS",
"created_at": "2026-10-19T08:14:59.517302+00:00",
"message": ""
},
{
"code": "RECEIVED_SUCCESSFULLY",
"created_at": "2026-10-19T08:15:04.880431+00:00",
"message": "Invoice received successfully from the Peppol network."
}
],
"type": "debit", // "debit" = invoice, "credit" = credit note
"updated_at": "Mon, 19 Oct 2026 08:15:04 GMT" // HTTP date; changes on every status row
}
}Statuses a received invoice moves through
The trail is in status_history; the last row is status. final_status sums it up as received, sent (synced to the connected accounting system) or failed.
| Status | Means | final_status |
|---|---|---|
RECEIVED_BY_PEPPOL | The invoice arrived over the network and was stored. The first row on every one. | received |
VALIDATION_IN_PROGRESS | It is being checked for your entity. | received |
RECEIVED_SUCCESSFULLY | Received successfully: it passed validation for your entity and is stored, complete and ready to read and download. With an accounting system connected, SENT_TO_<ERP> follows once it is synced there. Without one — an entity used only through this API, say — this is where it stays, and nothing is wrong. | received |
VALIDATION_SUCCEEDED | Xero only: Xero accepted the invoice's details, so it can be synced there. | sent |
SENT_TO_<ERP>_IN_PROGRESS → SENT_TO_<ERP> | Being synced to the connected accounting system, then successfully synced: it is a bill there. <ERP> is XERO, QUICKBOOKS, ZOHO, ODOO, NAQOOD or WAFEQ. | received → sent |
SENT_TO_<ERP>_FAILED | The sync failed: the connected system refused it. The message says why; the invoice itself is kept. | failed |
WAITING_FOR_ERP_CONNECTION | Legacy: invoices received before RECEIVED_SUCCESSFULLY was introduced carry this instead. Treat it exactly as RECEIVED_SUCCESSFULLY. | received |
Where to find what
invoice_data is the document in the Peppol gateway's own layout. The values most integrations need are here; paths inside it start from invoice_data.E_Invoice.Invoice, and plain names are top-level fields of the invoice.
| Supplier name and Peppol id | senderName, senderRegistryCode |
| Supplier TRN | InvoiceParties.SellerParty.VATRegNumber |
| Invoice number, issue date, due date | number, date, dueDate |
| Document type (380, 381, 480, 389, 261, 81) | InvoiceInformation.Extension.CustomContent.InvoiceInformationEN.InvoiceTypeCode |
| Self-billed? | …InvoiceInformationEN.ProcessControl.SpecificationId ends in selfbilling-1@ae-1 |
| The invoice a credit note corrects | …InvoiceInformationEN.PrecedingInvoice.Number and .Date |
| Invoicing period, when stated | InvoiceInformation.Period.StartDate and .EndDate |
| Currency | InvoiceSumGroup.Currency |
| Total before VAT, VAT, total | InvoiceSumGroup.InvoiceSum, .TotalVATSum, .TotalSum |
| The lines | InvoiceItem.InvoiceItemGroup.ItemEntry |
| A line's quantity, unit price, net amount | ItemEntry.ItemDetailInfo.ItemAmount, .ItemPrice, ItemEntry.ItemSum |
| A line's VAT category, rate, exemption reason | ItemEntry.VATTreatment.category, .percent, .exemption_reason_code |
| The supplier's bank account | PaymentInfo.PayToAccount |
Things that trip people up
One line is an object, two are a list
ItemEntry is an array only when the invoice has more than one line; a one-line invoice carries the line itself. InvoiceSumGroup.VAT does the same when there is more than one VAT rate. Normalise both to a list before you loop.
Amounts are strings
Every amount and quantity inside invoice_data is a string, and trailing zeros are dropped: "1102.5", "450". Parse them as decimals, not floats.
Take the VAT category from VATTreatment
The VAT block on a line only says TAX, TAXEX or NOTTAX. VATTreatment is read from the original UBL and carries the real category (S, Z, E, O, AE, N), the rate and any exemption reason. Older received invoices may not have it.
DocumentName is not the document type
The gateway labels an ordinary tax invoice "Commercial Invoice". Read InvoiceTypeCode, or the top-level type ("debit" for an invoice, "credit" for a credit note).
The id is a number
id is the gateway's numeric id. Put it in the URL as it is; the status endpoint echoes it back as a string in invoice_id.
Two date formats
updated_at is an HTTP date ("Mon, 19 Oct 2026 08:15:04 GMT"); every created_at in the status trail, and receivedAt, is ISO 8601. To filter, pass ISO 8601 to date_from.
/oauth/invoices/receivedAccess tokenList received invoices
Return invoices RECEIVED over the Peppol network for your entities (delivered via Peppol). Read-only. An app can own many users and entities, so narrow the results with entity_id and/or user_id, and by last change with date_from / date_to. Results are ordered by last change, newest first; sort=asc reverses that. For a daily catch-up, set date_from to the time of your previous sync: it returns every invoice that arrived or changed status since. A malformed or reversed date range, or an unknown sort, is answered 400 with an error naming the parameter. Each item carries the whole document in invoice_data — see Received invoices above for a full example and where to find each value in it.
Query parameters
entity_id | Filter to invoices received by a single entity (its id from GET /oauth/entities). |
user_id | Filter to entities owned by a single user. |
date_from | Last changed at or after this time. ISO 8601 date or time, e.g. 2026-10-19 or 2026-10-19T08:00:00Z; a time without an offset is UTC. A new invoice and every status change count — use it for a catch-up sync. |
date_to | Last changed at or before this time. ISO 8601 date or time; a date alone covers that whole day (UTC). |
sort | Order by last change: desc (newest first, the default) or asc (oldest first). Works with or without a date filter. |
page | Page number. Defaults to 1. |
limit | Page size, 1–100. Defaults to 20. |
/oauth/invoices/received/{invoice_id}Access tokenGet a received invoice
Fetch a single received invoice, with its full status history in status_history, by its gateway id. The list endpoint returns the same object for each invoice, without status_history. `attachments` lists the files the document came with — each file's `index`, `filename`, `mime_code`, `size` and `download_url` — and is [] when there are none. A full example response, and where to find each value in it, is under Received invoices above.
Path parameters
invoice_id | The numeric `id` from the received-invoices list, e.g. 15231. |
Responses
| 200 | The invoice, in `invoice` |
| 404 | No received invoice with this id for your entities |
/oauth/invoices/received/{invoice_id}/pdfAccess tokenDownload a received invoice as PDF
Render a received invoice as its Tax Invoice PDF, as received: the sender is the seller and your entity the buyer. The PDF's Invoice Number is the invoice's `id`, and its UUID row is the invoice's `number` (both as the received-invoice objects give them). The file is still named after the `number`. An invoice in a currency other than AED shows its VAT in AED as well, as the document states it: a "Tax amount AED" column beside each line's VAT in the invoice currency, and a "Total VAT Amount (AED)" row in the totals. An invoice in AED is unchanged. The PDF is generated for this request and returned as the response (Content-Type: application/pdf, Content-Disposition: attachment). TaxStar does not store it and it is not added to the invoice's attachments.
The response body is the PDF itself, not JSON. Save it with cURL's -o. In the Try-it console below, the PDF is shown and can be saved with Save file.
Path parameters
invoice_id | The numeric `id` from the received-invoices list, e.g. 15231. |
Responses
| 200 | The PDF (application/pdf) |
| 404 | No received invoice with this id for your entities |
| 429 | More than 30 PDFs a minute for this application — see Retry-After |
/oauth/invoices/received/{invoice_id}/attachments/{index}Access tokenDownload an attachment of a received invoice
Download one file a received invoice came with. When an invoice is received, TaxStar takes its files out of the Peppol document and keeps them in its file storage — once, however often the invoice is processed again — and serves them here. The file is returned with its own Content-Type and filename, always as a download (Content-Disposition: attachment). Files come from any sender on the network: open them with the care you give any email attachment.
The response body is the file itself. Use the `download_url` from the invoice's `attachments` list, with your access token, and save the body (cURL -OJ keeps the file's own name). In the Try-it console below, the file is offered with Save file (PDFs and images are also shown).
Path parameters
invoice_id | The numeric `id` from the received-invoices list, e.g. 15231. |
index | The file's position in the invoice's `attachments` list, from 0. |
Responses
| 200 | The file |
| 404 | No such invoice for your entities, or no file at this index |
| 502 | The file could not be read from storage — try again |
| 429 | More than 120 file downloads a minute for this application — see Retry-After |
/oauth/invoices/received/{invoice_id}/xmlAccess tokenDownload the XML of a received invoice
Return the UBL (PINT-AE) XML a received invoice came in, as TaxStar kept it when the invoice was received. It is the sender's own document, so use it as your copy of what you were sent. Files the document carried were taken out when it was received and kept in TaxStar's file storage: download them with Download an attachment of a received invoice. The XML is returned as the response body (Content-Type: application/xml; charset=utf-8, Content-Disposition: attachment; filename="Invoice_<number>.xml") and is not stored again. Any role your application holds on the entity may download it. Errors are { error, code }.
The response body is the XML itself, not JSON. Save it with cURL's -o, e.g. curl -H "Authorization: Bearer $TOKEN" -o invoice.xml …/xml. In the Try-it console below, use Save file.
Path parameters
invoice_id | The numeric `id` from the received-invoices list, e.g. 15231. Only letters, digits, - and _ are accepted (at most 64 characters); anything else is a 400. |
Responses
| 200 | The XML (application/xml) |
| 400 | Invalid invoice id (code invalid_invoice_id) |
| 401 | Missing or invalid access token |
| 404 | No received invoice with this id for your entities, or its XML is not available (code xml_not_available) |
| 429 | More than 120 file downloads a minute for this application — see Retry-After |