Guides

E-invoicing

Clear the tax invoices your own system issues with the FTA, through KWN, in one call.

UAE e-invoicing requires every tax invoice to be reported through an accredited service provider. KWN submits through Taxstar. POST /einvoices takes an invoice exactly as your system issued it; you never handle the provider’s format.

What one call does

Checks the request: the seller TRN must be this company’s (SELLER_TRN_MISMATCH), there must be lines, and with expectedTotal the invoice must add up to it to the fils (EINVOICE_TOTAL_MISMATCH).
Finds the buyer: customerId, or customer matched by TRN, then by exact name, else created. An existing contact is never overwritten.
Creates the invoice in Sales under KWN’s number, keeping yours as a reference, and approves it.
Takes one invoice credit and queues the invoice for the provider. A company with no credits left is refused NO_CREDITS.
Answers 201 with the e-invoice, PENDING.

Any refusal leaves nothing behind: no contact, no draft, no credit taken.

bash

curl -sS -X POST https://app.kwn.tax/api/v1/einvoices \
  -H "X-Api-Key: $KWN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "INV-2026-00042",
    "sellerTrn": "100234567800003",
    "issueDate": "2026-10-15",
    "customer": {
      "name": "Al Noor Trading L.L.C.", "isCompany": true, "trn": "100398765400003",
      "address": "Office 1204, Bay Square", "city": "Dubai", "emirate": "DUBAI", "country": "AE"
    },
    "lines": [
      { "description": "Bookkeeping, October 2026", "quantity": 1, "unitPrice": 2500, "taxRate": 5 }
    ],
    "expectedTotal": 2625
  }'

Statuses

Status	Meaning
`PENDING`	Accepted by KWN and on its way to the provider, or waiting for its answer.
`CLEARED`	Reported and accepted. The invoice is final.
`REJECTED`	The provider refused it. Correct it and send it again with the same `externalId`.
`FAILED`	The provider could not process it, for a technical reason rather than its content. It can be sent again from KWN; nothing about the invoice needs to change.
`CANCELLED`	Cancelled in KWN.

Read one with GET /einvoices/{id}, or list every change with GET /einvoices?updatedSince=….

Sending the same invoice again

The same externalId with the same content answers the first invoice, 200 with duplicate: true, and takes no second credit.
A rejected invoice sent again corrected, under its externalId, is resubmitted: 200 with resubmitted: true, still on its one credit.
The same externalId with other content, while the first is not rejected, is refused 409 EXTERNAL_ID_CONFLICT.

Before you go live

Call GET /me: eInvoicing.available must be true. It is false until KWN has registered the company with the provider (CLEARANCE_UNAVAILABLE otherwise). eInvoicing.mode is LIVE in production; MOCK means a test server, where nothing reaches the FTA.
The company’s e-invoicing details must be complete in KWN — legal name, address, TRN (EINVOICE_FIELDS_MISSING names what is missing).
The key needs sales:approve.
Keep an eye on credits: each cleared invoice uses one; the company tops up in KWN.

A buyer without a TRN — a private person — is cleared on the simplified route, as the app does for its own invoices.