API reference

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.

Received invoices

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

  1. 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. Add sort=asc to process them oldest first.
  2. Each item already carries the whole document in invoice_data. Fetching it again by id only adds status_history.
  3. Store the time you started this sync and use it as date_from next time. Or register a webhook and be told when one arrives. A received-invoice event has direction: "received" and names the invoice by invoice_number and your entity's receiver_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.

GET /oauth/invoices/received/{invoice_id}
{
  "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.

StatusMeansfinal_status
RECEIVED_BY_PEPPOLThe invoice arrived over the network and was stored. The first row on every one.received
VALIDATION_IN_PROGRESSIt is being checked for your entity.received
RECEIVED_SUCCESSFULLYReceived 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_SUCCEEDEDXero 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>_FAILEDThe sync failed: the connected system refused it. The message says why; the invoice itself is kept.failed
WAITING_FOR_ERP_CONNECTIONLegacy: 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 idsenderName, senderRegistryCode
Supplier TRNInvoiceParties.SellerParty.VATRegNumber
Invoice number, issue date, due datenumber, 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 statedInvoiceInformation.Period.StartDate and .EndDate
CurrencyInvoiceSumGroup.Currency
Total before VAT, VAT, totalInvoiceSumGroup.InvoiceSum, .TotalVATSum, .TotalSum
The linesInvoiceItem.InvoiceItemGroup.ItemEntry
A line's quantity, unit price, net amountItemEntry.ItemDetailInfo.ItemAmount, .ItemPrice, ItemEntry.ItemSum
A line's VAT category, rate, exemption reasonItemEntry.VATTreatment.category, .percent, .exemption_reason_code
The supplier's bank accountPaymentInfo.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.

GET/oauth/invoices/receivedAccess token

List 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_idFilter to invoices received by a single entity (its id from GET /oauth/entities).
user_idFilter to entities owned by a single user.
date_fromLast 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_toLast changed at or before this time. ISO 8601 date or time; a date alone covers that whole day (UTC).
sortOrder by last change: desc (newest first, the default) or asc (oldest first). Works with or without a date filter.
pagePage number. Defaults to 1.
limitPage size, 1–100. Defaults to 20.
GET/oauth/invoices/received/{invoice_id}Access token

Get 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_idThe numeric `id` from the received-invoices list, e.g. 15231.

Responses

200The invoice, in `invoice`
404No received invoice with this id for your entities
GET/oauth/invoices/received/{invoice_id}/pdfAccess token

Download 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_idThe numeric `id` from the received-invoices list, e.g. 15231.

Responses

200The PDF (application/pdf)
404No received invoice with this id for your entities
429More than 30 PDFs a minute for this application — see Retry-After
GET/oauth/invoices/received/{invoice_id}/attachments/{index}Access token

Download 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_idThe numeric `id` from the received-invoices list, e.g. 15231.
indexThe file's position in the invoice's `attachments` list, from 0.

Responses

200The file
404No such invoice for your entities, or no file at this index
502The file could not be read from storage — try again
429More than 120 file downloads a minute for this application — see Retry-After
GET/oauth/invoices/received/{invoice_id}/xmlAccess token

Download 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_idThe 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

200The XML (application/xml)
400Invalid invoice id (code invalid_invoice_id)
401Missing or invalid access token
404No received invoice with this id for your entities, or its XML is not available (code xml_not_available)
429More than 120 file downloads a minute for this application — see Retry-After