Start here

Update notices

What changed in the OAuth API and in the application, by date, newest first. Open a date to read what the update was, whether it changes what you send, and what to do. Each date has its own page: use its link to share that update.

19 Nov 2026Download the XML of a sent or received invoice; invoice docs split in twoNew

Download the XML of a sent or received invoice; invoice docs split in two

Two new endpoints return the XML an invoice was sent with, or came in. The invoice reference is now two sub-sections, Send invoices and Receive invoices. The Partner overview has a customer onboarding diagram, and the Entities reference lists create and delete for Development only.

OAuth API

New

Download the XML of a sent invoice, and of a received invoice

  • GET /oauth/invoices/sent/{invoice_id}/xml returns the UBL (PINT-AE) XML the invoice was delivered to Peppol with, exactly as kept when its status became SENT_TO_PEPPOL.
  • GET /oauth/invoices/received/{invoice_id}/xml returns the XML a received invoice came in.
  • Both answer with the XML as the response body (Content-Type application/xml; charset=utf-8, as a download named Invoice_<number>.xml). Nothing is stored again.
  • A sent invoice that has not reached SENT_TO_PEPPOL, or whose send failed, answers 409 invoice_not_sent. The XML of a conversion that was never delivered is never returned.
  • The invoice id is checked first: a sent invoice's id is its 24-character invoice_id; a received invoice's id is letters, digits, - and _ (at most 64). Anything else is 400 invalid_invoice_id.
  • An invoice of an entity your app cannot reach, or one that does not exist, is 404. A sent or received invoice whose XML is no longer stored is 404 xml_not_available. Errors are { error, code }.
  • Files the document carried are links in the XML, not content: download them from the attachments endpoints.
  • Any role your app holds on the entity may download. They share the file-download limit of 120 a minute per app; over it, 429 with Retry-After.
Why we changed this
  • An integrator needs its own copy of the exact document that was delivered or received, for its records and for audits, without rebuilding it from the invoice data.

What to do: Nothing to change. Call the endpoint when you need the XML; for a sent invoice, wait for SENT_TO_PEPPOL.

Download the XML of a sent invoice →Download the XML of a received invoice →

Application

No change

Nothing changes in the application

  • The application's screens and rules are unchanged.

Documentation

Documentation

FAQ: going live answers

  • A new FAQ group, Going live, answers what integrators ask before they connect: the production URL (https://api.taxstar.app/einv) and that sending there is closed until the FTA activation date while validation works; POST /oauth/invoices/send is an alias of POST /oauth/invoices; the seller block is optional.
  • It also explains when beneficiary_id, principal_id, einv_scope_note, discount_percent and account_code apply, and that there is no debit note: reduce with a credit note, increase with a new Tax Invoice.
  • Credit notes: the original is sent first and its credit note only once it shows as sent, because processing order is not guaranteed; a PROCESSING invoice after 15 minutes should be reported to support.
  • Poll the sent list every 5 to 15 minutes as a fallback to webhooks, and map tax rates to S, Z, E, O or AE (not N).
  • The access token answer now also says the refresh token's lifetime is returned as refresh_token_expires_in.

FAQ →

Documentation

Invoices are two sub-sections: Send invoices and Receive invoices

  • The sidebar's Invoices heading now holds two pages: Send invoices (at /invoices, as before) and Receive invoices (new, at /received-invoices).
  • Send invoices keeps the sending endpoints and guide: push, bulk, validate, update, the sent list and detail, the sent PDF, XML and attachments.
  • Receive invoices holds the received list and detail, the received PDF, XML and attachments, and the guide to the document you get back (statuses, the daily sync).
  • The links to the received endpoints moved with them: use /received-invoices#list-received-invoices and /received-invoices#received-invoices.
  • The API overview and the home page list both pages.

Send invoices →Receive invoices →

Documentation

Entities: create and delete are shown on Development only

  • POST /oauth/entities (create an entity) and DELETE /oauth/entities/{entity_id} (delete one) are back in the Entities reference, marked Development only. They appear only while Development is selected in the top bar, and are hidden on Production.
  • On production no entity is created through the API: every entity is created for you by FTA onboarding, and both endpoints answer 404 Resource Not Found. Use GET /oauth/entities to find the entity_id.
  • On Development the TRN must be a conformant UAE TRN (15 digits, starting with 1, ending with 03 or 001) and unique. The seller's legal registration is optional when creating but mandatory before the entity can send.
  • Deleting needs admin access to the entity and releases its Peppol registration first; if that fails nothing is deleted (502).
  • The API overview and the quickstart step 1 say the same: FTA onboarding on production, POST /oauth/entities on Development.

Entities →

Documentation

Partner overview: onboard a customer end to end

  • A new card, Onboard a customer with no Tax Star sign-up, shows the whole journey of one customer in four lanes: the customer, your app, Tax Star and EmaraTax (the FTA portal).
  • Below the diagram the same journey is written as six steps: the customer signs up on your app, consents to your raising invoices, you pre-register the client, the customer onboards on EmaraTax and selects Tax Star as ASP, Tax Star links the company and registers it on Peppol, and you go live.
  • The diagram's text is small at page width, so a View full screen button opens it in a viewer you can zoom in and out of; Esc or Close returns to the page.
  • The customer never creates or uses a Tax Star account. Their actions are in your app and on the FTA portal only.
  • A note maps the diagram's temp_onboarding_id to the id of the client that pre-register returns, and says the client.onboarded webhook does not carry entity_id: read it from GET /oauth/partners/pre-register/clients/{client_id}.

Partner overview →

Open this date on its own page, to share →

17 Nov 2026API invoices wait for approval by defaultChangedBreaking changeNew

API invoices wait for approval by default

When an entity requires approval for sending, an invoice pushed through the API now waits for approval unless you send bypass_send_approval true.

OAuth API

Breaking change

bypass_send_approval now defaults to false

  • bypass_send_approval used to default to true, so an API invoice was sent at once even when the entity required approval for sending.
  • It now defaults to false: if the entity has Require Approval for Sending switched on and you leave the field out, the invoice is held as WAITING_FOR_APPROVAL and the approvers are emailed.
  • Send bypass_send_approval true to send the invoice without waiting, as before.
  • The same applies to every PATCH: a corrected invoice sent without the field goes for approval again.
  • It makes no difference when the entity does not require approval, and invoices already stored keep the value they were pushed with.
Why we changed this
  • An entity that switches approval on expects its invoices to be checked by a person. Skipping it by default meant API invoices went out unchecked unless the integration knew to opt in.

What to do: If your integration pushes invoices for an entity that requires approval and you want them sent without waiting, add bypass_send_approval true to each push and each PATCH. Otherwise nothing to change.

Invoices pushed through the API →Push an invoice →

New

An app setting turns off Tax Star's welcome email for its clients

  • Your apps, Settings now has Send Tax Star's welcome email. It is on by default and applies to the whole OAuth app.
  • Turn it off and a client you pre-registered does not get Tax Star's welcome email when it completes FTA onboarding.
  • You are still linked, client.onboarded still fires, and the company's owner still gets the partner connection notice.
  • It is not a field of POST /oauth/partners/pre-register: nothing is sent with the request. It is read when the client is welcomed, so changing it applies to every client not yet welcomed.
  • You can also read and change it with GET and PATCH /oauth/apps/<app_id> as send_welcome_email.
Why we changed this
  • A partner that welcomes its own clients does not want them to receive a second welcome from Tax Star.

What to do: Nothing to change. Turn the setting off under Your apps, Settings when you want to welcome your clients yourself.

Partner clients →

New

Entity update can switch invoice approval on or off

  • PATCH and PUT /oauth/entities/{entity_id} accept is_active_send_approver, a boolean.
  • It is the same setting as Require Approval for Sending in the web app: true holds the invoices the entity sends for an approver, false sends them without approval.
  • It needs admin or editor access to the entity, the same as the switch in the web app. An approver's or viewer's app gets 403.
  • It does not release an invoice that is already waiting, and an API invoice can still skip approval with bypass_send_approval true.
Why we changed this
  • An integration that creates and manages companies had to ask a person to open the web app to turn approval on or off.

What to do: Nothing to change. Send is_active_send_approver when you want to set approval for an entity from your integration.

Entities →

Application

Changed

Signing in to the portal now includes a captcha check

  • The developer sign-in on this site, and the sign-in, password reset and two-factor steps of the E-Invoice app and the Reseller dashboard, now show a Cloudflare Turnstile captcha.
  • The check usually passes by itself. If you press Sign in before it has finished, the form asks you to complete the captcha and try again.
  • The browser sends the captcha result in the X-Turnstile-Token header of /auth/sign-in, /auth/forgot-password, /auth/forgot-password/reset, /auth/2fa/challenge/email-code, /auth/2fa/challenge/verify and /reseller-portal/sign-in. A request without a valid token is refused with 400.
  • Calls to the OAuth API are not affected: they authenticate with a client_id and client_secret at POST /oauth/token, and no captcha is involved.
Why we changed this
  • Sign-in and password-reset forms are open to anyone, so scripts can try passwords and codes at scale. A captcha stops callers that are not a real browser.

What to do: Nothing to do when you sign in from a browser. A script that called these sign-in endpoints directly can no longer do so; use the OAuth API with your app credentials instead.

Authentication →

No change

Nothing changes in the application

  • The application's own screens and the approval switch are unchanged.

Documentation

Documentation

Your apps: Details and Settings tabs on each app

  • Each app card under Your apps now has two tabs: Details, shown by default, and Settings. Settings changes the app's name, its description and the welcome email setting, and saves with PATCH /oauth/apps/<app_id>.
  • The app name is mandatory and must be at least 3 characters once trimmed (at most 100). The same rule applies when you create an app. A shorter name is refused with 400.
  • The app's own view no longer shows who approved it, and GET /oauth/apps no longer returns approved_by or rejected_by. That is a staff member's email.
  • Create an app and Your apps are marked Action in the sidebar and on the page, because you do something there instead of reading reference.
  • The sidebar has two tabs at the top: Documentation for the guides and API reference, and Manage for Create an app and Your apps. A link into a page opens its tab.

Your apps →

Open this date on its own page, to share →

16 Nov 2026Validate invoices on productionChanged

Validate invoices on production

POST /oauth/invoices/validate now works for every entity on production, not only for entities cleared for sending.

OAuth API

Changed

Validate no longer needs an activated entity on production

  • POST /oauth/invoices/validate answers for any entity your app can reach, on test and on production.
  • Before, an entity that was not activated or cleared for sending was refused with 403 on production.
  • Validating still stores nothing, queues nothing and sends nothing to Peppol. Sending an invoice is unchanged: it still needs the entity to be cleared.
Why we changed this
  • A dry run delivers nothing to Peppol, so there is no reason to hold it back, and you can check your payloads before the entity is cleared to send.

What to do: Nothing to change. You can validate on production now.

Validate an invoice →

Application

No change

Nothing changes in the application

  • The application's own screens are unchanged.

Open this date on its own page, to share →

13 Nov 2026Clearer failure messagesChangedBreaking changeNew

Clearer failure messages

When an invoice fails for a reason on our side or in your accounting system, the message now says in plain words what happened and what to do. Raw system text no longer appears on the invoice.

OAuth API

Changed

A failed invoice's message is plain, and never carries system text

  • A conversion that fails unexpectedly no longer reads "Conversion to XML raised exception: KeyError('x')". It reads "An unexpected problem stopped this invoice from being prepared for Peppol" and gives a short reference to quote to support.
  • The delivery failure message stays "Failed to send invoice to Peppol", and its `reason` and `reason_code` are unchanged.
  • Failures that are only temporary (a connection problem) now say so and ask you to send the invoice again in a few minutes.
Why we changed this
  • The old text was an internal error message. It told you nothing you could act on, and it could carry data from the system that refused the request.

What to do: Nothing to change if you only show the status to a person. If your code matches the old conversion error text, match the status code (XML_CONVERTED_FAILED) instead.

Invoice statuses →

Breaking change

The user endpoints are removed

  • POST /oauth/users, GET /oauth/users and GET /oauth/users/{user_id} no longer exist. A call to any of them is answered 404.
  • Entities and users made earlier are unchanged, and your app keeps reaching its entities as before.
  • A partner or reseller sees its clients through the partner or reseller endpoints (/oauth/partners/pre-register/clients, /oauth/reseller/pre-register/clients), not through users.
Why we changed this
  • An account must be made by the person it belongs to. An account an app created on their behalf left that person's company owned by an account they had never signed up for.

What to do: Stop calling the /oauth/users endpoints and remove created_by_user_id from your code. Have each customer sign up in the Tax Star E-Invoice application. To list your clients, use the partner or reseller client endpoints.

Partner accounts →Reseller accounts →

New

List the clients that have registered

  • GET /oauth/partners/pre-register/clients/registered and GET /oauth/reseller/pre-register/clients/registered return the clients you pre-registered whose company is now registered.
  • Each client carries its entity_id, entity_created_at and activity. They take search, page and limit.
  • It is the same list as the client list with status=entity_created, which still works.
Why we changed this
  • With the user endpoints gone, this is the one call that answers which of your pre-registered clients have registered.

What to do: Nothing to change. Call it, or subscribe to client.onboarded, to learn who has registered.

Partner accounts →Reseller accounts →

Application

Changed

Failure messages on an invoice say what happened and what to do

  • A failure while checking, preparing or sending an invoice, or while booking a received one into your accounting system, now gives one plain sentence and the next step: reconnect the system, wait a few minutes, or correct the document.
  • When the accounting system refuses a document, only its own validation sentences are shown (for example that an account code is not valid), never its full response.
  • A problem we could not classify shows a short reference. Quote it if you contact support.
  • The Events tab shows a failed validation as a card: what is wrong, what is missing, where to fix it and a link to the entity's details. The original message is one click away.
  • Delivery failures use one wording, "Failed to send invoice to Peppol", in every accounting system.
  • Messages already on invoices are not rewritten; the new wording applies to failures from now on.
Why we changed this
  • Messages used to carry raw error text, which was hard to read and could echo customer data.

What to do: Nothing to do.

Documentation

Documentation

The Users section is removed

  • The Users tab and its endpoint pages are gone, and the OAuth overview, Roles and permissions, Partner and Reseller pages no longer list user endpoints.

Open this date on its own page, to share →

12 Nov 2026Legal registration in the application, and who uploaded and sent an invoiceBreaking changeNewChanged

Legal registration in the application, and who uploaded and sent an invoice

Two breaking changes in the application: a seller's legal registration is now mandatory, and an out-of-scope invoice now waits for its buyer's registration. A sales invoice also shows who uploaded and who sent it, and an invoice number is uploaded once per company.

OAuth API

No change

The OAuth API is not changed by this update

  • The legal registration rules of the OAuth API are the ones announced on 10 Nov 2026.
  • Nothing changes for API clients.

Application

Breaking change

A seller's legal registration is now mandatory in the application too

  • An invoice from your accounting system no longer goes on to the next step while its entity has no legal registration: it fails validation until you add it.
  • This also applies to invoices triggered through the API for the entity. Before, such an invoice went out with a stand-in registration.
  • The entity page shows an alert while a seller has not provided its legal registration, listing what is missing. It disappears as soon as everything is provided.
  • The edit form marks the legal registration fields as required for a seller: the number, the type, the issuing authority for a trade licence and the issuing country (two letters) for a passport.
  • A registration that contradicts itself, for example a number with no type, is refused when you save.
  • An invoice from your accounting system is refused (it fails validation) while the entity has not provided the registration.
  • The message lists what is missing and says to add it to the entity's details, in the application or through the entity update API, then send the invoice again.
  • Nothing is filled in for you. The TRN, the TIN and the participant id are never used as the registration number.
Why we changed this
  • Every invoice a seller sends carries its legal registration, the same as on the OAuth API, so the seller has to state it.
  • Until now the application treated it as optional, which let an incomplete entity be set up and then fail when its first invoice was built.
Reference

From the PINT AE Billing 1.0.4 specification. Each ID opens the rule on the Peppol documentation.

  • IBT-030The seller's legal registration identifier.
  • IBR-173-AE ↗The seller's legal registration identifier must state its type: TL, EID, PAS or CD.
  • IBR-150-AE ↗The seller's legal registration identifier must be present.
  • IBR-172-AE ↗A trade licence needs the authority that issued it.

What to do: Before your next invoices, provide the legal registration on every seller entity, in the application or through the entity update API. Invoices that already failed for this reason have to be sent again once it is added.

Setting up an entity →

Breaking change

A buyer's legal registration is asked only when the invoice needs it

  • An out-of-scope invoice or a credit note for goods or services no longer goes out on its own: it waits until the buyer's legal registration is given. Before, it went out with a placeholder.
  • An invoice from your accounting system no longer carries a placeholder registration for the buyer (the number 0000000, a trade licence type and the authority name "Trade License issuing Authority"). Those values were never real.
  • The buyer's registration is sent only when you state it completely: the number with its type, and the issuing authority for a trade licence or the country for a passport. A half-stated one is left out.
  • It is mandatory on an out-of-scope invoice and on a credit note for goods or services. Such an invoice is held, shown as "needs an answer", and asks for the registration on its Review PINT Mapping tab.
  • Your answer is remembered for that buyer: its later invoices, and its other held invoices, are sent with it.
  • On the PINT Mapping page the four Buyer Legal Registration rows start empty. Map the number to a field in your accounting system, or leave it empty to be asked when an invoice needs it.
Why we changed this
  • A registration the buyer never stated is invented data on a tax document, and the number 0000000 was sent on every invoice.
  • Asking only where the rule requires it keeps ordinary invoices flowing.
Reference

From the PINT AE Billing 1.0.4 specification. Each ID opens the rule on the Peppol documentation.

  • IBR-136-AE ↗The buyer legal registration identifier must be present on an Out of scope of VAT invoice and on a credit note related to goods or services.
  • IBR-180-AE ↗A buyer legal registration identifier on a 0235 buyer must state its type.
  • IBR-101-AE ↗A trade licence (TL) must carry the authority that issued it.

What to do: Nothing is needed for invoices that do not need the registration. If you invoice out-of-scope supplies, give the buyer's registration on the invoice when it asks, or map it on the PINT Mapping page, so those invoices are not left waiting.

PINT Mapping →

New

Uploaded by and Sent by on Invoice Details

  • On Sales Invoices, the Invoice Details tab shows Uploaded by, Uploaded on, Sent by and Sent on.
  • Each person is shown by name and by the email of their account, which cannot be changed, so a renamed member is still recognisable.
  • Sent by says how the invoice was sent: pressed Send, approved it, or approved by email link. It shows once Peppol accepted the invoice.
  • An invoice your accounting system sent on its own says Automatically; one sent through the API says Through the API.
  • A Tax Star support member who sent an invoice for you is shown as Tax Star support.
  • Uploads made before today show who uploaded them. Invoices sent before today do not show who sent them.
  • See Invoice Uploads.
Why we changed this
  • Owners and editors of a company can all upload and send invoices, and could not tell which of them uploaded or sent a given invoice, or when.

What to do: Nothing to do.

Invoice Uploads →

Changed

An invoice number is uploaded once per company, whoever uploads it

  • A spreadsheet row whose invoice number another member of the company already uploaded is now refused with "Duplicate — already uploaded".
  • Until now only your own uploads were checked, so two members could each upload, and send, the same invoice.
  • Uploads that already exist are not changed.
Why we changed this
  • The same invoice must not reach Peppol twice. PDF uploads were already checked across the company; spreadsheet rows now are too.

What to do: If an upload is refused as a duplicate, find the other member's upload on Sales Invoices before deleting anything.

Invoice Uploads →

Open this date on its own page, to share →

11 Nov 2026Status endpoint says why a delivery failedChanged

Status endpoint says why a delivery failed

The status of an invoice that failed at dispatch now carries the reason the access point gave, instead of only the generic message.

OAuth API

Changed

reason and reason_code on a failed status

  • GET /oauth/invoices/{invoice_id}/status adds reason (for example "Organization Doesn't Accept E-Invoices") and reason_code (for example "409") when the status category is failed and the access point gave them.
  • message is unchanged ("Failed to send invoice to Peppol"). The fields are absent when no reason was given.
  • To correct and re-send, PATCH /oauth/invoices/{invoice_id} with the corrected invoice (same entity_id and invoice_number). The same invoice is re-queued, no duplicate is created, and the answer is 202 with status PROCESSING.
  • A reason such as "Organization Doesn't Accept E-Invoices" means the buyer is not registered to receive e-invoices; correct the buyer's participant details before the PATCH.
Why we changed this
  • A client could see that a delivery failed but not why, and had to ask support to read the logs.

What to do: Read reason and reason_code on failed statuses. No change is needed for existing integrations.

Open this date on its own page, to share →

10 Nov 2026Legal registration of the buyer and of the sellerChangedBreaking changeNew

Legal registration of the buyer and of the seller

The OAuth API now follows the PINT AE rules for the legal registration of the buyer and of the seller, and no longer fills either one in for you.

OAuth API

Changed

The buyer's legal registration follows the PINT AE rules

  • The buyer's registration id (buyer.legal_registration_id, IBT-047) is required only on an Out of scope of VAT invoice (type 480) and on a credit note related to goods or services (type 81).
  • That includes an invoice whose every line is exempt or out of scope, because it becomes type 480 or 81.
  • On every other invoice the buyer's registration is optional.
  • When you send the id, send its type too (buyer.legal_registration_type: TL, EID, PAS or CD).
  • TL also needs authority_name. PAS also needs passport_country_code, a two-letter ISO 3166-1 code.
  • A request that leaves one out is refused with a 422 that names the field. POST /oauth/invoices/validate reports the same errors.
  • For EID and CD no authority is sent, even if you supply one. The second value is written only for TL (the authority) and PAS (the country).
  • The buyer's TIN is no longer copied into this field. The TIN, the TRN and the participant id are never used as a legal registration number.
Why we changed this
  • The specification asks for the buyer's registration only on those two document types, and asks for its type whenever an id is sent. Our API did neither: it copied the buyer's TIN into the field with no type.
  • A TIN is a tax identifier, not a legal registration number, and a registration with no type breaks IBR-180-AE. A document could go out that the rules reject, with no error to the sender.
  • In the specification, EID and CD carry no second value, so sending an authority for them was not allowed.
  • The Peppol rule IBR-149-AE says the buyer registration is required for every UAE buyer, but its own test checks the VAT number, not the registration. We do not enforce a buyer registration on the strength of that rule.
Reference

From the PINT AE Billing 1.0.4 specification. Each ID opens the rule on the Peppol documentation.

  • IBR-136-AE ↗The buyer legal registration identifier must be present on an Out of scope of VAT invoice and on a credit note related to goods or services.
  • IBR-180-AE ↗When the buyer id is given on the 0235 scheme, its registration type must be present.
  • IBR-183-AE ↗The type must be Commercial/Trade license, Emirates ID, Passport or Cabinet decision.
  • IBR-101-AE ↗A trade licence (TL) must carry its authority name.
  • IBR-010-AE ↗A passport must carry its issuing country.
  • IBR-011-AE ↗The passport country must be coded with ISO 3166-1.
  • IBR-CL-11 ↗A registration identifier scheme must come from the ISO 6523 list, so the type is never written in schemeID.
  • IBR-103 ↗The buyer legal registration identifier may occur at most once.
  • IBR-149-AE ↗Known issue: its message and its test disagree, so it is not enforced.

What to do: Send the buyer's registration on Out of scope of VAT invoices and on credit notes related to goods or services. Wherever you already send an id, add its type.

Legal registration rules →Push invoice →

Changed

An invoice to a UAE buyer with no registration no longer fails with Company ID is required

  • An invoice to a UAE buyer that sends no buyer.legal_registration_id passed validation but then failed while the XML was built, with the error Company ID is required.
  • That was a fault in how the buyer was carried from validation to the XML. It is fixed: such an invoice is built and sent, and the buyer's registration is left out of the XML.
  • The buyer's registration is still required on an Out of scope of VAT invoice and on a credit note related to goods or services, and its type is still required whenever you send the id.
  • An invoice that failed this way can be sent again: PATCH /oauth/invoices/{invoice_id} with the same invoice body.
  • Anything that stops the document being built is now reported when you send or validate, as an error in section document, and never later as a failed conversion.
  • POST /oauth/invoices/validate shows it too, so a preview now predicts the send.
Why we changed this
  • The specification makes the buyer's registration optional except on those two document types, and our validation already accepted an invoice without it. The XML step then rejected the same invoice, so the two disagreed.
  • The fault only appeared in the step that builds the XML, which is why validation and the preview did not show it.
  • A client should be told what is missing when they send, not find a failed status afterwards, so validation now also builds the document as a dry run.
Reference

From the PINT AE Billing 1.0.4 specification. Each ID opens the rule on the Peppol documentation.

  • IBR-136-AE ↗The buyer legal registration identifier is required only on an Out of scope of VAT invoice and on a credit note related to goods or services.
  • IBR-180-AE ↗When the buyer id is given on the 0235 scheme, its registration type must be present.

What to do: If an invoice to a UAE buyer failed with Company ID is required, send it again with PATCH /oauth/invoices/{invoice_id} and the same invoice body. Nothing else changes.

Legal registration rules →

Breaking change

The seller's legal registration comes from the entity, and is required

  • State the seller's registration once, on the entity: legal_registration_id, legal_registration_type, and issuing_authority (TL) or passport_country (PAS).
  • Every invoice for that entity then carries it exactly as given.
  • One invoice can differ by sending the seller block on that invoice.
  • An invoice for an entity with no registration is refused with a 422 that names what is missing.
  • So is a trade licence without its issuing authority, and a passport without its country or with a code that is not ISO 3166-1.
  • For EID and CD no authority is sent.
  • Before, the invoice carried the entity's registry code labelled as a passport issued by AE, whatever you had set. That value is removed.
  • Entities created through FTA onboarding have no registration until you set one.
Why we changed this
  • The specification requires the seller's legal registration id and its type on every UAE document, with the authority for TL and the country for PAS.
  • We were sending the entity's registry code, which is a TIN, labelled as a passport issued by AE. A TIN is not a legal registration number, and the label was not true.
  • That value was there because we believed the gateway needed it to find the sender. We tested it on the Peppol development gateway: the sender is found from the endpoint, not from this element.
  • The registration belongs to the seller, so the seller states it once on the entity. We no longer decide it for you.
Reference

From the PINT AE Billing 1.0.4 specification. Each ID opens the rule on the Peppol documentation.

  • IBR-006 ↗An invoice must contain the seller name.
  • IBR-150-AE ↗The seller legal registration identifier must be provided when the endpoint scheme is 0235.
  • IBR-181-AE ↗When the seller id is given on the 0235 scheme, its registration type must be present.
  • IBR-173-AE ↗The type must be Commercial/Trade license, Emirates ID, Passport or Cabinet decision.
  • IBR-172-AE ↗A trade licence (TL) must carry its authority name.
  • IBR-012-AE ↗A passport must carry its issuing country.
  • IBR-013-AE ↗The passport country must be coded with ISO 3166-1.
  • IBR-100 ↗The seller legal registration identifier may occur at most once.

What to do: Set the registration on each entity you send invoices for, before you send the next invoice.

Update an entity →Legal registration rules →

New

PUT is accepted on the entity update, and the registration fields are checked together

  • PATCH and PUT on /oauth/entities/{entity_id} are the same partial update: send only the fields you want to change.
  • A change to the registration fields is checked against what the entity will then hold.
  • An id needs its type, and a type needs its id.
  • TL needs issuing_authority. PAS needs passport_country, an ISO 3166-1 code.
  • Otherwise the update is a 400 and nothing is stored.
  • An update that touches none of these fields is not checked.
Why we changed this
  • A registration set on the entity is used on every invoice, so a half-filled one (an id with no type, a TL with no authority) would make every invoice fail.
  • The update now refuses it when it is entered, instead of each invoice failing later.
  • PUT is accepted because many clients update with PUT. It does the same partial update as PATCH.
Reference

From the PINT AE Billing 1.0.4 specification. Each ID opens the rule on the Peppol documentation.

Update an entity →

Application

No change

The application is not changed by this update

  • Invoices from a connected ERP, or from an upload, still take their buyer and seller registration from the PINT Mapping page and the entity's details, as before.
  • The same handling is planned for the application in a later update, and will be announced here.

PINT Mapping →

Documentation

Documentation

Legal registration reference, field tables and this page updated

  • Invoice validation has a new reference for the legal registration: where each value goes in the UBL, the seller and buyer rules with their IBR numbers, and the sources.
  • The buyer and seller fields are updated in the Push invoice and Update an entity references, and in the invoice guide.
  • The seller block is no longer shown in the request examples: the seller comes from the entity.
  • PINT AE rule IDs (for example IBR-006 or IBR-136-AE) are now shown beside the fields they govern, in one spelling, so you can copy an ID and search for it on the Peppol documentation.
  • Each change on this page now says why it was made and which rules it follows.
  • This Update notices page is new.

Open this date on its own page, to share →

7 Nov 2026Invoices outside e-invoicing: exclude one yourself, and reopen one with a reasonNewChanged

Invoices outside e-invoicing: exclude one yourself, and reopen one with a reason

An invoice can now be excluded from its own tab, an excluded one is reopened with a reason and fetched again from your accounting system, and sales to private individuals are answered and seen by admins and editors only.

OAuth API

Changed

An invoice pushed as excluded cannot be reopened

  • An invoice pushed with einv_scope "excluded" is stored as a summary only, so it cannot be reopened from the dashboard.
  • A PATCH on it is refused with 409.
  • To send it after all, push it again without einv_scope.
  • The docs said it could be reopened from the dashboard. That was wrong and is corrected.
Why we changed this
  • The invoice's details are not kept once it is excluded, so there is nothing to send it from.
Reference

A reference that names a decision or the Guidelines is from the Ministry of Finance; it opens the document on its site.

What to do: To send an invoice you pushed as excluded, push it again without einv_scope.

Push invoice →

Application

New

Exclude an invoice yourself, and reopen one with a reason

  • An invoice from your accounting system that is not sent yet has an E-invoicing scope tab. Pick a reason and Save, and the invoice moves to Excluded instead of being sent.
  • OTHER also asks what the transaction is. The exclusion applies to that invoice alone.
  • An excluded invoice has an Excluded tab with its reason and note. Reopen asks why it is reopened.
  • Reopen fetches the invoice again from your accounting system. It is then checked like any invoice: held if something is missing, waiting for approval where you require it, or sent.
  • If Zoho Books, Odoo, Naqood or Wafeq cannot return it (not connected, connection expired, or deleted there), Reopen says so and the invoice stays excluded.
  • An excluded spreadsheet row, PDF upload or API invoice cannot be reopened, because its details were not kept. Send or upload it again.
  • The company page's E-invoicing Exclusion list gives each company a reason: Tax Group member (invoices dated 2027 to 2028) or Other (every invoice, with a note). Its business name is filled in from the latest invoice.
  • An excluded invoice keeps its number, date, totals, lines and your company's details. The customer's details are removed, and no PDF is offered.
Why we changed this
  • Some transactions are outside the e-invoicing system by law, and which ones is not always recorded in an accounting system. You can now mark one yourself, with the reason the law gives.
  • The law lets you e-invoice an excluded transaction if you choose to, so an exclusion can always be undone, and the reason for undoing it is recorded.
  • An excluded invoice is never sent, so we keep only what your records need, and not your customer's details.
Reference

A reference that names a decision or the Guidelines is from the Ministry of Finance; it opens the document on its site.

What to do: To keep an invoice out, open it on Sales Invoices and use its E-invoicing scope tab. To send one that was kept out, use Reopen on its Excluded tab.

Excluding an invoice yourself →Reopen →

Changed

Sales to private individuals: who answers them, and who sees them

  • Whether a customer with no TRN is a private individual is asked on the invoice's Review PINT Mapping tab, which replaces the Customer tab.
  • Only admins and editors answer it. The answer is remembered for the customer and can be changed on the Contacts page.
  • Approvers no longer see an invoice held on that question, nor one excluded as a sale to a private individual. Other excluded invoices stay visible to them.
Why we changed this
  • A sale to a private individual is outside the e-invoicing system, so it never comes to approval, and an approver has no decision to take on it.
  • Deciding that a customer is a private person, and seeing their invoices, is kept to the people who manage the company's invoicing.
Reference

A reference that names a decision or the Guidelines is from the Ministry of Finance; it opens the document on its site.

  • MD 244 of 2025, Art. 5.2 ↗Business-to-consumer transactions are not subject to the e-invoicing system until the Minister decides otherwise.

Invoices outside e-invoicing →

Documentation

Documentation

Invoices outside e-invoicing rewritten

  • Invoices outside e-invoicing now covers the E-invoicing scope tab, Reopen by where the invoice came from, what an excluded invoice keeps, and who sees sales to private individuals.
  • It names the Review PINT Mapping tab, the Contacts page, the E-invoicing Exclusion list and Sales Invoices, and the deadline reminders' recipients and start date.
  • Push invoice and Invoice status no longer say an excluded API invoice can be reopened.

Open this date on its own page, to share →

6 Nov 2026Held invoices: what is waiting for you, and where to answer itNewChanged

Held invoices: what is waiting for you, and where to answer it

Invoices that wait for an answer from your company are now listed together under Held, and each one asks for its answer on its own tab.

OAuth API

Changed

Status catalogue 1.2.0: excluded invoices and Sage Intacct syncs return their category

  • Invoices pushed through the API are held only for approval, as before. None of the other holds above applies to them.
  • EXCLUDED_FROM_EINVOICING is now in GET /oauth/invoices/status-codes. The status endpoint answers it with category blocked and terminal true, where it answered unknown.
  • SENT_TO_SAGE_INTACCT, SENT_TO_SAGE_INTACCT_IN_PROGRESS and SENT_TO_SAGE_INTACCT_FAILED are new, for a received invoice synced into Sage Intacct.
  • The blocked category is unchanged. Its description now says that a blocked status with terminal true stays until someone reopens or re-sends the invoice.
  • No other code, category or field changes.
Why we changed this
  • These statuses were already written on invoices but were missing from the catalogue, so an integration that switches on category was told unknown and kept polling.
  • The old blocked description said every blocked invoice moves on by itself, which is not true for an excluded invoice or one whose operations are switched off.
Reference

A reference that names a decision or the Guidelines is from the Ministry of Finance; it opens the document on its site.

What to do: If you switch on category, nothing to do. If you list codes yourself, add the four new ones.

Invoice status →

Application

New

Held lists every invoice waiting for you, and the invoice asks for the answer

  • Sales Invoices and Purchase Bills filter by All, Held, Delivered, Booked and Failed. Sales Invoices also filter by Excluded and Overdue.
  • Held lists the invoices waiting for someone in your company. Nothing is wrong with them, and they move on once answered.
  • A sales invoice is held for an approval, which is given under Invoices to Approve.
  • It is held when a customer has no TRN and is recorded as a private individual, or, in the UAE, has no type recorded. Answered as a private individual, the invoice moves to Excluded; answered in scope, a customer in the UAE still needs its TRN, so the invoice fails until it is added in your accounting system.
  • It is held for a line's tax treatment or type of goods, or for values given at invoice level.
  • A self-billed invoice you issue to a supplier is a purchase, so it is listed on Purchase Bills. It is held there for the same answers, and for the supplier's details.
  • All of these are answered on one tab of the invoice, Review PINT Mapping, which stays open from one question to the next.
  • It is held when your accounting system refused the connection while the invoice was checked. Connect it again on Connections: every invoice held for it is then checked and sent on its own.
  • An upload is held for a missing value, or for a PDF's readings to be confirmed, on its Missing details tab.
  • A purchase bill is held when a line's tax code, stock item or account cannot be settled in your system. It is answered on its Item Codes, Tax Codes and Expense Account tabs, and Save posts it within a minute.
  • On a bill, a goods line takes one of your stock items or is marked not a stock item: a bill never creates a product.
  • A self-billed invoice a customer issued to you is your sale, so it is held on Sales Invoices, on the same tabs except Expense Account. There a product can be created, except in Sage Intacct, where it is added in Sage and read with Refresh.
  • A customer or supplier answered once is remembered for its later invoices.
Why we changed this
  • These holds were added one at a time, each waiting for a different answer, and they were spread over several lists. One filter now shows everything that waits for you.
  • A sale to a natural person not carrying on business is outside the e-invoicing system (Ministerial Decision 244 of 2025, Art. 5.2). When it is not recorded whether a customer with no TRN is a private individual, we ask you instead of guessing, because sending a private individual's invoice and excluding a business's would both be mistakes.
  • On a self-billed invoice your supplier is the seller, and the rules require the seller's registration type, with the authority for a trade licence and the country for a passport. These are not part of an accounting system's supplier record, so you are asked once per supplier.
  • A received bill is not posted with a guessed tax code, product or account, because a wrong one would have to be corrected in your books.
Reference

From the PINT AE Billing 1.0.4 specification. Each ID opens the rule on the Peppol documentation.

  • IBR-173-AE ↗The seller's registration type must be Commercial/Trade license, Emirates ID, Passport or Cabinet decision.
  • IBR-172-AE ↗A trade licence (TL) must carry its authority name.
  • IBR-012-AE ↗A passport must carry its issuing country.

What to do: Open Held on Sales Invoices and on Purchase Bills, and answer each invoice on the tab it opens with.

Held invoices →Held bills →Invoices outside e-invoicing →

Documentation

Documentation

Held invoices and the status catalogue documented

Open this date on its own page, to share →