E-Invoicing for UAE (United Arab Emirates) API References

Introduction

The United Arab Emirates is rolling out a nationwide e-invoicing mandate driven by the Ministry of Finance and the Federal Tax Authority (FTA). The UAE has adopted a Peppol-based 5-corner model (Decentralised Continuous Transaction Control and Exchange — "DCTCE"): invoices travel from the supplier through Accredited Service Providers to the buyer, while tax-relevant data is simultaneously reported to the FTA in near real time.

Every document exchanged on the network must be a UBL 2.1 XML document conforming to the PINT AE 1.0.4 specialisation — the UAE-specific profile of the Peppol International (PINT) billing model. Flick handles all of this for you: you send a simple JSON payload, and Flick validates it, converts it to compliant UBL XML, exchanges it over Peppol, and reports it to the FTA.

Key things to know before you start:

Base URL: https://sb-ae-api.flick.network
Authentication: pass your API key in the X-Flick-Auth-Key header on every call.
Participants: every request is scoped to a participant_id — the UUID of an active participant (a legal entity you have onboarded) owned by your account.
Two-layer validation: Layer 1 runs fast JSON pre-checks (mandatory fields, code lists, conditional dependencies). Layer 2 renders the UBL XML and runs the official PINT AE 1.0.4 schematron rule sets. Every error carries a path pointing into your JSON payload and the official rule id (e.g. ibr-159-ae) in code. If any layer reports errors, the request fails with HTTP 400 and nothing is stored.
Prefill & auto-computation: seller details are merged field-by-field from the participant profile (your payload values win). uuid, tax_accounting_currency (always AED), VAT breakdowns, document totals, line VAT amounts and all AED-converted amounts are computed automatically when omitted — which is why the minimal payload is so small.
JSON or XML: documents are accepted as JSON ({"document": {...}}) or as raw UBL 2.1 XML (Content-Type: application/xml). XML ingestion is lossless.

Document Types

The document_type code (IBT-003) plus the flags.is_selfbilled boolean together select one of the four PINT AE document variants:

`document_type`	`flags.is_selfbilled`	Document
`380`	`false`	Tax Invoice
`380`	`true`	Self-Billed Tax Invoice
`381`	`false`	Tax Credit Note
`381`	`true`	Self-Billed Tax Credit Note
`480`	—	Out-of-scope Invoice (supplies outside UAE VAT)
`81`	—	Out-of-scope Credit Note

Self-billing is a flag, not a type code. Send document_type: "380" (or "381") together with flags.is_selfbilled: true. Legacy codes 389/361 are still accepted but are auto-normalised to 380/381 + is_selfbilled: true and produce a deprecation warning in the response.

Special rules for out-of-scope documents (480 / 81), in plain language:

The seller's VAT number (TRN) is not required on out-of-scope documents — it is mandatory on every other type (ibr-134-ae).
The buyer's legal registration identifier becomes mandatory (ibr-136-ae).
Only the categories exempt (E), not-subject-to-VAT (O) or zero-rated (Z) may be used — no standard rate, no reverse charge (ibr-122-ae).
They cannot be flagged as summary invoice, deemed supply, or margin scheme (ibr-157-ae).
A commercial invoice or credit note cannot be made up only of exempt / not-subject-to-VAT items — if everything is out of scope, use the out-of-scope document type instead (ibr-151-ae).

Transaction Flags

The flags object describes the nature of the transaction. The flags drive the 8-position transaction type code (BTAE-02) in the XML — you never need to build that code yourself, it is auto-derived. Each flag can switch on additional requirements:

Flag	Position	Meaning	What it additionally requires (rule)
`is_ftz`	1	Free-trade-zone supply	You must name the beneficiary: provide `receiving_party.fz_beneficiary_id` (`ibr-007-ae`)
`is_deemed`	2	Deemed supply	Nothing extra — `due_date` and `payment_means` are not expected, since no payment happens (`ibr-127-ae`, `ibr-191-ae`)
`is_margin`	3	Margin scheme supply	All VAT categories on the document must be the margin-scheme category `N` (`ibr-116-ae`)
`is_summary`	4	Summary invoice	You must state the billing period being summarized: provide `invoice_period` (`ibr-138-ae`)
`is_continuous`	5	Continuous supply	Nothing extra
`is_dab`	6	Disclosed agent billing	You must name the principal: provide `principal_id` — and the agent (seller) and principal must be different entities, their TRNs can't be the same (`ibr-137-ae`, `ibr-176-ae`)
`is_ecommerce`	7	Supply through e-commerce	You must include the delivery address: address line 1, city and Emirate (`ibr-142-ae`)
`is_export`	8	Export supply	You must include a delivery address, and the destination country must NOT be AE (`ibr-152-ae`)

flags.is_selfbilled sits outside the 8 positions: it switches the document to the self-billing rulebook and swaps the supplier/customer roles in the generated XML — in your JSON, issuing_party always stays the seller.

Common Structs

The structs below are shared by all document types. Each conditional field's description explains the condition in plain language, with the official rule id in parentheses as an error-code reference — that is exactly the code you will see in a validation error.

1. Seller `issuing_party`

The seller (supplier) party. Fully optional for JSON submissions: every field left empty is prefilled from the participant profile (legal name, TRN, address, Peppol endpoint, TIN, legal form, registered identifiers). Provide fields only to override the profile per document. For self-billed documents this party is still the seller — roles are swapped automatically in the XML.

Name
legal_name
Type
string
Description
Seller legal name (IBT-027). Prefilled from profile; every document must carry the seller name (ibr-006).
Name
trade_name
Type
string (optional)
Description
Seller trading name (IBT-028), if different from the legal name.
Name
peppol_id
Type
string
Description
Seller electronic address (IBT-034) in the form 0235:100000000000003 — scheme id, a colon, then the identifier. Prefilled from profile. The scheme must come from the official EAS code list (ibr-cl-25); 0235 is the UAE domestic scheme. For domestic e-invoicing (scheme 0235) the seller's legal registration identifier is mandatory (ibr-150-ae).
Name
party_identifier
Type
string (optional)
Description
Seller identifier (IBT-029). The buyer must be able to recognise the seller automatically: give at least one of seller identifier, legal registration identifier, or VAT identifier (ibr-co-26).
Name
vat_number
Type
string (conditional)
Description
Seller VAT identifier / TRN (IBT-031). Prefilled from profile. The seller's TRN is mandatory on every document except out-of-scope types 480/81 (ibr-134-ae). Any UAE TRN must be exactly 15 digits, start with 1, and end with 03 (ibr-132-ae). The seller must be tax-identified one way or another: give the TRN or the TIN (ibr-177-ae).
Name
tax_registration_id
Type
string (conditional)
Description
Seller tax identification number — TIN (IBT-032). The seller's TIN must be exactly 10 digits and start with 1 (ibr-148-ae). Alternative to vat_number for sellers without a TRN (ibr-177-ae).
Name
company_legal_form
Type
string (optional)
Description
Seller additional legal information / company legal form (IBT-033), e.g. Limited Liability Company.
Name
identifiers
Type
identifiers (optional)
Description
Additional registered identifiers keyed by type — see the Registered Identifiers struct below. For a UAE seller on the domestic network, the legal registration type must be one of: Commercial/Trade license (TL), Emirates ID (EID), Passport (PAS), or Cabinet decision (CD) (ibr-173-ae).
Name
street_address
Type
string
Description
Address line 1 (IBT-035). The seller's address must always include address line 1, city and country subdivision (Emirate) (ibr-143-ae). Prefilled from profile.
Name
additional_street_address
Type
string (optional)
Description
Address line 2 (IBT-036).
Name
additional_address_lines
Type
string (optional)
Description
Address line 3 (IBT-162).
Name
city_address
Type
string
Description
Seller city (IBT-037). Always required together with address line 1 and Emirate (ibr-143-ae).
Name
postal_zone
Type
string (optional)
Description
Seller post code (IBT-038).
Name
emirates_code
Type
string
Description
Seller country subdivision (IBT-039). For any UAE address this must be one of the 7 official Emirate codes: AUH, DXB, SHJ, AJM, UAQ, RAK, FUJ (ibr-128-ae). See the Emirates table under Code Lists.
Name
country_code
Type
string
Description
Seller country code (IBT-040), ISO 3166-1 alpha-2 — e.g. AE (ibr-cl-14).
Name
contact_name
Type
string (optional)
Description
Seller contact point (IBT-041).
Name
contact_telephone
Type
string (optional)
Description
Seller contact telephone (IBT-042).
Name
contact_email
Type
string (optional)
Description
Seller contact email (IBT-043).

2. Buyer `receiving_party`

The buyer (customer) party. Required on every document. For self-billed documents this party is still the buyer (the actual document issuer); XML roles are swapped automatically.

Name
legal_name
Type
string
Description
Buyer legal name (IBT-044). Every document must include the buyer name (ibr-007).
Name
trade_name
Type
string (optional)
Description
Buyer trading name (IBT-045).
Name
peppol_id
Type
string
Description
Buyer electronic address (IBT-049) in the form 0235:112345679000003 — this is the Peppol routing destination. The buyer's electronic address is mandatory, it's how the document is routed (ibr-080), and it must always say which identification scheme it uses (ibr-063).
Name
party_identifier
Type
string (conditional)
Description
Buyer identifier (IBT-046). For domestic e-invoicing (UAE endpoint scheme 0235), you must identify the buyer with either a Buyer identifier or a Buyer VAT number — unless it's an export, or the buyer address starts with 1 (freelancer / natural person) (ibr-135-ae).
Name
vat_number
Type
string (conditional)
Description
Buyer VAT identifier / TRN (IBT-048). Must be exactly 15 digits, start with 1 and end with 03 (ibr-132-ae). Reverse charge shifts the tax to the buyer — so on reverse-charge documents the buyer's TRN becomes mandatory (ibr-103-ae).
Name
identifiers
Type
identifiers (conditional)
Description
Additional registered identifiers keyed by type — see the Registered Identifiers struct below. For domestic e-invoicing (scheme 0235), the buyer's legal registration identifier is mandatory — unless the buyer address starts with 1 or 9 (natural person / government) (ibr-149-ae). On out-of-scope documents (480/81) it is always mandatory (ibr-136-ae). The buyer's registration type must be one of TL, CL, EID, PAS, CD (ibr-183-ae).
Name
fz_beneficiary_id
Type
string (conditional)
Description
Free-trade-zone beneficiary identifier (BTAE-01). Free-trade-zone invoices must name the beneficiary: provide the Beneficiary ID (TRN/TIN) when flags.is_ftz is true (ibr-007-ae).
Name
street_address
Type
string
Description
Address line 1 (IBT-050). The buyer's address must always include address line 1, city and country subdivision (Emirate) (ibr-144-ae).
Name
additional_street_address
Type
string (optional)
Description
Address line 2 (IBT-051).
Name
additional_address_lines
Type
string (optional)
Description
Address line 3 (IBT-163).
Name
city_address
Type
string
Description
Buyer city (IBT-052). Always required together with address line 1 and Emirate (ibr-144-ae).
Name
postal_zone
Type
string (optional)
Description
Buyer post code (IBT-053).
Name
emirates_code
Type
string (conditional)
Description
Buyer country subdivision (IBT-054). Mandatory when country_code is AE; must be one of the 7 official Emirate codes (ibr-128-ae).
Name
country_code
Type
string
Description
Buyer country code (IBT-055), ISO 3166-1 alpha-2 (ibr-cl-14).
Name
contact_name
Type
string (optional)
Description
Buyer contact point (IBT-056).
Name
contact_telephone
Type
string (optional)
Description
Buyer contact telephone (IBT-057).
Name
contact_email
Type
string (optional)
Description
Buyer contact email (IBT-058).

3. Registered Identifiers `identifiers`

A map of additional registered identifiers keyed by type, used inside issuing_party and receiving_party. Each entry is an object with value and (where applicable) authority_name:

Key	Identifier	Plain-language condition (rule)
`TL`	Commercial / Trade license	If a party is identified by a trade license, you must name the authority that issued that license via `authority_name` (seller: `ibr-172-ae`, buyer: `ibr-101-ae`)
`CL`	Commercial license	Buyer only (`ibr-183-ae`); same authority-name requirement as `TL`
`EID`	Emirates ID	—
`PAS`	Passport	If a party is identified by passport, you must also say which country issued that passport, as a valid 2-letter ISO country code (seller: `ibr-012-ae`/`ibr-013-ae`, buyer: `ibr-010-ae`/`ibr-011-ae`)
`CD`	Cabinet decision number	—

Name
value
Type
string
Description
The identifier value, e.g. CN-1234567.
Name
authority_name
Type
string (conditional)
Description
The issuing authority, e.g. Abu Dhabi Department of Economic Development. Mandatory for TL / CL identifiers (ibr-172-ae, ibr-101-ae); carries the passport-issuing country code for PAS identifiers (ibr-012-ae, ibr-010-ae).

4. Payment Means `payment_means[]`

Payment instructions (IBG-16). At least one entry is required on invoices — you must say how payment will be made, except on credit notes and deemed supplies where no payment is expected (ibr-191-ae).

Name
type_code
Type
string
Description
Payment means type code (IBT-081). Must come from the UAE subset of the UNCL4461 code list (ibr-cl-16) — see the Payment Means table under Code Lists (e.g. 10 cash, 30 credit transfer, 54 credit card).
Name
payment_instruction_id
Type
string (optional)
Description
Payment instructions ID (IBT-178). Links this payment means to payment_terms installments carrying the same payment_instruction_id.
Name
payment_id
Type
string (optional)
Description
Remittance information (IBT-083), e.g. a structured payment reference the buyer should quote.
Name
payment_account_id
Type
string (conditional)
Description
Payment account identifier / IBAN (IBT-084). If payment is by credit transfer, you must give the bank account (IBAN / account number) to pay into (ibr-192-ae).
Name
payment_account_scheme_id
Type
string (optional)
Description
Account identifier scheme, e.g. IBAN.
Name
payment_account_name
Type
string (optional)
Description
Payment account name (IBT-085).
Name
payment_service_provider_id
Type
string (optional)
Description
Payment service provider identifier / BIC (IBT-086), e.g. EBILAEAD.
Name
card
Type
object (optional)
Description
Card payment details (IBG-18) — at most one card block per document (ibr-066). Keys: primary_account_number (IBT-087, masked PAN only — never send full card numbers, e.g. XXXXXXXXXXXX4321), network_id (e.g. VISA), holder_name (IBT-088).
Name
mandate
Type
object (optional)
Description
Direct debit details (IBG-19) — at most one mandate block per document (ibr-067). Keys: id (mandate reference, IBT-089) and debited_account_id (IBT-091).

5. Payment Terms `payment_terms[]`

Payment terms / installments (IBG-33). When used instead of a document-level due_date, every entry must carry an installment_due_date — if money is still owed (amount due > 0) you must say when it's due, except on credit notes and deemed supplies (ibr-127-ae).

Name
payment_instruction_id
Type
string (optional)
Description
Matches a payment_means.payment_instruction_id (IBT-187), tying this installment to a payment instruction.
Name
note
Type
string (optional)
Description
Terms text (IBT-020), e.g. 50% on delivery.
Name
amount
Type
number (optional)
Description
Installment amount (IBT-176). If any payment terms carry a paid amount, the document-level invoice_totals.prepaid_amount must also be present (ibr-093).
Name
installment_due_date
Type
date (conditional)
Description
Installment due date (IBT-177), YYYY-MM-DD. Required on every entry when the document has no due_date (ibr-127-ae).

6. Line Items `invoice_lines[]`

Invoice / credit note lines (IBG-25). At least one line is required (ibr-016). line_extension_amount, vat_line_amount and the AED amounts are auto-computed when omitted.

Name
id
Type
string
Description
Line identifier (IBT-126). Every line must include a line identifier (ibr-021).
Name
note
Type
string (optional)
Description
Line note (IBT-127).
Name
name
Type
string
Description
Item name (IBT-153). Every line must include the item name (ibr-025).
Name
description
Type
string
Description
Item description (IBT-154). Every item must have a description, not just a name (ibr-125-ae).
Name
quantity
Type
number
Description
Invoiced quantity (IBT-129). Line math check: line net amount = quantity × (unit price ÷ price base quantity) + line charges − line allowances (ibr-147-ae). Emitted as CreditedQuantity on credit notes.
Name
uom
Type
string
Description
Unit of measure code (IBT-130). Must come from the UN/ECE Recommendation 20 (incl. Rec 21) code list (ibr-cl-23) — e.g. H87 piece, DAY, KGM. See Code Lists.
Name
unit_price
Type
number
Description
Item net price (IBT-146). The unit net price can't be negative — use allowances or credit notes for reductions (ibr-027).
Name
gross_price
Type
number (optional)
Description
Item gross price (IBT-148). Simple price math: net price = gross price minus discount — if you give a gross price, the numbers must add up (aligned-ibrp-004). The gross price can't be negative (ibr-028). Auto-derived when omitted (ibr-126-ae).
Name
price_discount
Type
number (optional)
Description
Item price discount (IBT-147). Only a discount is allowed inside the price block — never a charge (ibr-083).
Name
base_quantity
Type
number (optional)
Description
Price base quantity (IBT-149) — the quantity the price applies to. Must be a positive number above zero (ibr-087). Auto-set to 1 when omitted.
Name
base_quantity_uom
Type
string (optional)
Description
Base quantity unit (IBT-150). The unit of the price base quantity must match the unit of the invoiced quantity (ibr-088).
Name
line_extension_amount
Type
number (auto)
Description
Line net amount (IBT-131). Auto-computed when omitted; when provided, the line math must check out (ibr-147-ae).
Name
vat_category
Type
string
Description
Line VAT category code (IBT-151): S standard 5%, Z zero-rated, E exempt, O out of scope, AE reverse charge, N margin scheme. Every line must be tagged with a VAT category code (ibr-145-ae), and it must come from the official AE VAT category list (ibr-139-ae).
Name
vat_percentage
Type
number (conditional)
Description
Line VAT rate (IBT-152). The UAE standard rate is 5% — any standard-rated line must state exactly 5 (ibr-190-ae). A zero-rated line must state exactly 0 (aligned-ibrp-z-05). An exempt line must not state a rate at all (aligned-ibrp-e-05); same for out-of-scope lines (aligned-ibrp-o-05). A reverse-charge line must still state the applicable rate (aligned-ibrp-ae-05-ae). A margin-scheme line must not have a 0% rate (ibr-111-ae).
Name
vat_exemption_reason_code
Type
string (conditional)
Description
Exemption reason code (IBT-186). Every exempt (E) line must carry an exemption reason code explaining WHY it's exempt (ibr-167-ae) — see the Reasons for exemption from tax list.
Name
vat_exemption_reason
Type
string (optional)
Description
Exemption reason text (IBT-185).
Name
vat_line_amount
Type
number (auto)
Description
Line VAT amount in document currency. Auto-computed: omitted for E lines, 0 for O/AE/Z lines.
Name
line_amount_aed
Type
number (auto)
Description
Line amount payable in AED (BTAE-10), VAT-inclusive. Whenever a line has VAT information, you must also give that line's amount and VAT amount converted to AED (ibr-104-ae) — every line must state its payable amount in AED (ibr-194-ae). Auto-computed via currency_exchange_rate.
Name
vat_line_amount_aed
Type
number (auto)
Description
Line VAT amount in AED (BTAE-08). Auto-computed. On an exempt line, don't provide any AED VAT line amount at all (ibr-163-ae); on a zero-rated line it must be zero (ibr-165-ae); on a reverse-charge line it must be zero (ibr-162-ae).
Name
commodity_code
Type
string (optional)
Description
Item type (BTAE-13): G goods, S services, B both. Items marked as Goods must carry an HS classification code (ibr-184-ae); items marked as Services must carry a Service Accounting Code (ibr-185-ae); items marked as Both must carry both (ibr-186-ae).
Name
hs_code
Type
string (conditional)
Description
Harmonised System commodity code (IBT-158). Required when commodity_code is G or B (ibr-184-ae, ibr-186-ae); when you give an item classification, its scheme must be HS — set automatically (ibr-188-ae).
Name
hs_code_version
Type
string (optional)
Description
HS list version, e.g. 2022.
Name
sac_code
Type
string (conditional)
Description
Service accounting code (BTAE-17). Required when commodity_code is S or B (ibr-185-ae, ibr-186-ae); its scheme must be SAC — set automatically (ibr-189-ae).
Name
sac_code_scheme_version
Type
string (optional)
Description
SAC list version.
Name
standard_item_id
Type
string (conditional)
Description
Item standard identifier (IBT-157), e.g. a GTIN. Reverse-charge (AE) items must carry a GTIN: the standard item identifier is mandatory with scheme 0160 (ibr-174-ae).
Name
standard_item_id_scheme
Type
string (conditional)
Description
ICD scheme of standard_item_id (ibr-cl-21). Must be 0160 for reverse-charge lines (ibr-174-ae).
Name
reverse_charge_item_type
Type
string (conditional)
Description
Type of goods or services subject to RCM (BTAE-09), e.g. DL8.48.8.1. Reverse-charge items must state the type of goods or services (ibr-166-ae), and it must come from the official RCM goods/services code list (ibr-006-ae).
Name
origin_country
Type
string (optional)
Description
Item country of origin (IBT-159), ISO 3166-1 alpha-2 (ibr-cl-15).
Name
buyers_item_code
Type
string (optional)
Description
Item buyer's identifier (IBT-156).
Name
supplier_item_code
Type
string (optional)
Description
Item seller's identifier (IBT-155).
Name
batch_number
Type
string (optional)
Description
Item batch / lot number (BTAE-24).
Name
object_id
Type
string (optional)
Description
Line object identifier (IBT-128). Only one object identifier is allowed per line (ibr-089).
Name
object_id_scheme
Type
string (optional)
Description
Scheme for object_id — must come from the UNCL1153 restriction (ibr-cl-07).
Name
item_attributes
Type
map (optional)
Description
Item attributes (IBG-32) as a name → value map, e.g. {"Colour": "Graphite"}. Each attribute must contain both a name and a value (ibr-054).
Name
invoice_period_start_date
Type
date (optional)
Description
Line period start (IBT-134). A line's period must start within the overall invoicing period (ibr-085) and can't end before it starts (ibr-030).
Name
invoice_period_end_date
Type
date (optional)
Description
Line period end (IBT-135). Must end within the overall invoicing period (ibr-086).
Name
order_line_reference
Type
string (optional)
Description
Referenced purchase order line (IBT-132).
Name
accounting_cost
Type
string (optional)
Description
Line buyer accounting reference (IBT-133).
Name
vat_per_unit_amount
Type
number (optional)
Description
Per-unit VAT amount — margin scheme (N) lines only.
Name
allowance_charges
Type
allowance_charge[] (optional)
Description
Line-level allowances / charges (IBG-27 / IBG-28) — same shape as the document-level struct below, but with no vat_category (the line's category applies). Every line discount or charge must say why — as text or as a reason code (ibr-042, ibr-044), and must have an amount (ibr-041, ibr-043).

7. Discounts & Charges `allowance_charge[]`

Document-level allowances (discounts) and charges (IBG-20 / IBG-21). Sums feed into the document totals automatically.

Name
charge_indicator
Type
boolean
Description
false = allowance (discount), true = charge (ibr-082).
Name
reason_code
Type
string (optional)
Description
Coded reason. Allowances use the UNCL5189 list (ibr-cl-19), charges use the UNCL7161 list (ibr-cl-20).
Name
reason
Type
string (conditional)
Description
Reason text (IBT-097 / IBT-104). Every document-level discount or charge must say why — as text or as a reason code (ibr-033, ibr-038).
Name
amount
Type
number
Description
Allowance / charge amount without VAT (IBT-092 / IBT-099). Math check: amount = base amount × percentage ÷ 100, when both base and percentage are given (ibr-131-ae, ibr-146-ae).
Name
base_amount
Type
number (conditional)
Description
Base amount (IBT-093 / IBT-100). Base amount and percentage come as a pair: give both or neither, never just one (aligned-ibrp-057, aligned-ibrp-058).
Name
percentage
Type
number (conditional)
Description
Percentage applied to base_amount (IBT-094 / IBT-101). Pairs with base_amount (aligned-ibrp-057, aligned-ibrp-058).
Name
vat_category
Type
string
Description
VAT category of the allowance / charge (IBT-095 / IBT-102). Every document-level discount or charge must say which VAT category it belongs to (aligned-ibrp-032, aligned-ibrp-037). Document-level allowances and charges can never use the margin-scheme category N (ibr-115-ae, ibr-114-ae). Every exempt allowance or charge must carry an exemption reason code (ibr-168-ae, ibr-169-ae).
Name
vat_percentage
Type
number (conditional)
Description
VAT rate (IBT-096 / IBT-103). Standard-rated entries must state exactly 5 (ibr-190-ae); exempt, zero-rated and reverse-charge entries must carry a 0% rate (aligned-ibrp-e-06, aligned-ibrp-z-06, aligned-ibrp-ae-06); out-of-scope entries must not carry any rate (aligned-ibrp-o-06).

8. Preceding Invoice References `document_references[]`

References to the invoice(s) being corrected (IBG-3). A credit note (type 381 or 81) must reference the original invoice it corrects — except volume-discount credit notes (reason VD), which don't tie to a single invoice (ibr-055-ae).

Name
document_identifier
Type
string
Description
Preceding invoice number (IBT-025). Each preceding-invoice reference must contain the invoice number (ibr-055).
Name
issue_date
Type
date (optional)
Description
Preceding invoice issue date (IBT-026), YYYY-MM-DD (ibr-073).

9. Supporting Documents `additional_document_references[]`

Additional supporting documents (IBG-24). Three usage patterns: (1) invoiced-object identifier — set document_type_code: "130" + scheme_id; (2) external attachment — set attachment_uri; (3) embedded file — set embedded_document. One reference can't be both an invoiced-object reference and an attachment — use separate references (ibr-071).

Name
document_identifier
Type
string
Description
Supporting document reference (IBT-122). Each additional supporting document must contain a reference (ibr-052).
Name
document_type_code
Type
string (optional)
Description
Set to 130 to mark this reference as the invoiced object (IBT-018). Only one invoiced-object reference is allowed at document level (ibr-078), and it can't also carry a document description (ibr-072).
Name
scheme_id
Type
string (conditional)
Description
Identifier scheme for invoiced-object references. Must come from the UNCL1153 restriction (ibr-cl-07). Mandatory when document_type_code is 130.
Name
document_description
Type
string (optional)
Description
Supporting document description (IBT-123).
Name
attachment_uri
Type
string (optional)
Description
External attachment URL (IBT-124).
Name
embedded_document
Type
object (optional)
Description
Embedded binary attachment (IBT-125). Keys: mime_code — every embedded attachment must declare its file type (ibr-074), from the PINT media-type subset (ibr-cl-24); filename — every embedded attachment must declare its filename (ibr-075); content — Base64-encoded file content.

10. Invoicing Period `invoice_period`

The period the document covers (IBG-14). Summary invoices must state the billing period they summarize (ibr-138-ae).

Name
start_date
Type
date (conditional)
Description
Period start (IBT-073). If you include an invoicing period, give at least the start date or the end date (ibr-co-19).
Name
end_date
Type
date (conditional)
Description
Period end (IBT-074). The invoicing period can't end before it starts (ibr-029).
Name
description_code
Type
string (optional)
Description
Frequency of billing code (BTAE-06). Must be one of the official codes — DLY, WKY, MTH, QTR, YRL, OTH, etc. (ibr-005-ae). If the billing frequency is Others (OTH), explain the actual frequency in the document note (ibr-160-ae). Full list: Frequency of billing codes.

11. Order & Other References `order_reference` / `other_references`

Name
order_reference.purchase_order_id
Type
string (optional)
Description
Purchase order reference (IBT-013).
Name
order_reference.sales_order_id
Type
string (optional)
Description
Sales order reference (IBT-014). If only the sales order is supplied, an empty purchase-order placeholder is emitted in the XML automatically.
Name
other_references.despatch_document_reference
Type
string (optional)
Description
Despatch advice reference (IBT-016). Reference the despatch advice either per line or at document level — not both (ibr-092).
Name
other_references.receipt_document_reference
Type
string (optional)
Description
Receiving advice reference (IBT-015).
Name
other_references.tender_or_lot_reference
Type
string (optional)
Description
Tender or lot reference (IBT-017).
Name
other_references.contract_document_reference
Type
object (optional)
Description
Contract reference (IBT-012) with optional AE contract value: { "id": "CTR-2026-009", "contract_value": "AED 200000" } (BTAE-05).
Name
other_references.customs_reference_number
Type
string (optional)
Description
Customs declaration reference (BTAE-21).
Name
other_references.project_reference
Type
string (optional)
Description
Project reference (IBT-011). Only one project reference is allowed on the document (ibr-090).

12. Payee `payee_party`

Only needed when the payment receiver differs from the seller — if someone other than the seller receives the money, you must name that payee (ibr-017).

Name
name
Type
string
Description
Payee name (IBT-059). Mandatory whenever a payee is given (ibr-017).
Name
identifier
Type
object (optional)
Description
Payee identifier (IBT-060) as { "value": "...", "scheme_id": "0060" }. The scheme must come from the ISO 6523 ICD list (ibr-cl-10).
Name
legal_registration_id
Type
object (optional)
Description
Payee legal registration identifier (IBT-061), same shape as identifier (ibr-cl-11).
Name
bank_creditor_id
Type
string (optional)
Description
Bank-assigned creditor identifier (IBT-090), e.g. a SEPA-style creditor reference.

13. Tax Representative `tax_representative`

The seller's tax representative party (IBG-11). If the seller uses a tax representative, that representative must be named (ibr-018), must have a VAT identifier (ibr-056), and their postal address must be included (ibr-019) — at minimum the country (ibr-020).

Name
name
Type
string
Description
Tax representative name (IBT-062).
Name
vat_number
Type
string
Description
Tax representative VAT identifier (IBT-063). A UAE TRN must be exactly 15 digits, start with 1 and end with 03 (ibr-132-ae).
Name
street_address
Type
string
Description
Address line 1 (IBT-064).
Name
city_address
Type
string
Description
City (IBT-066).
Name
emirates_code
Type
string (conditional)
Description
Country subdivision (IBT-068). For any UAE address, must be one of the 7 Emirate codes (ibr-128-ae).
Name
country_code
Type
string
Description
Country code (IBT-069), ISO 3166-1 alpha-2.

14. Delivery `delivery`

Delivery information (IBG-13). Required (address line 1, city and Emirate) for e-commerce supplies (ibr-142-ae); for exports the delivery address is required and the destination country must NOT be AE (ibr-152-ae).

Name
actual_delivery_date
Type
date (optional)
Description
Actual delivery date (IBT-072), YYYY-MM-DD (ibr-073).
Name
location_id
Type
string (optional)
Description
Deliver-to location identifier (IBT-071), with optional location_id_scheme from the ICD list (ibr-cl-26).
Name
party_name
Type
string (optional)
Description
Deliver-to party name (IBT-070).
Name
address
Type
object (conditional)
Description
Deliver-to address (IBG-15): street_address (IBT-075), city_address (IBT-077), postal_zone (IBT-078), emirates_code (IBT-079 — one of the 7 Emirate codes for UAE addresses, ibr-128-ae), country_code (IBT-080 — every deliver-to address must contain a country code, ibr-057).
Name
delivery_terms
Type
object (optional)
Description
Delivery terms (BTAE-22): { "incoterms": "DDP" }. If you include delivery terms, they must state the Incoterms code — CIF, FOB, DDP, etc. (ibr-196-ae).

15. VAT Breakdown `vat_totals[]`

VAT breakdown per category + rate (IBG-23). Auto-computed from lines and document allowances/charges when omitted — provide it only to override exemption reason texts or when your rounding differs.

Name
tax_category
Type
string
Description
VAT category code (IBT-118). One row per category is enforced: e.g. if anything on the document is VAT-exempt, there must be exactly one Exempt row in the breakdown (aligned-ibrp-e-01); same pattern for zero-rated (aligned-ibrp-z-01), out-of-scope (aligned-ibrp-o-01), reverse charge (aligned-ibrp-ae-01-ae) and margin scheme (ibr-105-ae).
Name
tax_rate
Type
number (conditional)
Description
VAT rate (IBT-119). Every breakdown row needs a rate — unless the category is out-of-scope or exempt, where no rate applies (ibr-119-ae). A zero-rated row must state the rate as exactly 0 (ibr-120-ae); an exempt row must not state any rate (ibr-121-ae).
Name
taxable_amount
Type
number
Description
Taxable base amount (IBT-116). Every breakdown row needs the taxable base (aligned-ibrp-045). Per-rate sums must add up — each row equals the sum of the lines, charges and allowances taxed at that same rate (aligned-ibrp-s-08 and friends).
Name
tax_amount
Type
number
Description
VAT amount (IBT-117). For a standard-rated row: VAT amount = taxable amount × VAT rate, the math must check out exactly (aligned-ibrp-s-09). Exempt, zero-rated, out-of-scope and reverse-charge rows always show 0 (aligned-ibrp-e-09, aligned-ibrp-z-09, aligned-ibrp-o-09, aligned-ibrp-ae-09-ae); the margin-scheme row also shows 0 — the tax is embedded in the margin (ibr-108-ae).
Name
tax_exemption_reason_code
Type
string (conditional)
Description
Exemption reason code (IBT-121) — for E and O rows. See Reasons for exemption from tax.
Name
tax_exemption_reason
Type
string (optional)
Description
Exemption reason text (IBT-120). Include it only once — don't repeat it (ibr-sr-32).

16. Document Totals `invoice_totals`

Document totals (IBG-22). Fully auto-computed when omitted. Provided values are kept and cross-validated, so partial overrides are safe — but the math must check out:

Name
line_extension_amount
Type
number (auto)
Description
Sum of line net amounts (IBT-106). Totals check: must equal the sum of all line net amounts (ibr-co-10).
Name
allowance_total_amount
Type
number (auto)
Description
Document allowances total (IBT-107) = sum of all document-level allowance amounts (ibr-co-11).
Name
charge_total_amount
Type
number (auto)
Description
Document charges total (IBT-108) = sum of all document-level charge amounts (ibr-co-12).
Name
tax_exclusive_amount
Type
number (auto)
Description
Total without VAT (IBT-109) = line total − allowances + charges (ibr-co-13).
Name
tax_amount
Type
number (auto)
Description
Total VAT (IBT-110) = sum of the VAT amounts of every breakdown row (ibr-co-14). Max 2 decimals (ibr-124).
Name
tax_inclusive_amount
Type
number (auto)
Description
Total with VAT (IBT-112) = total excl. tax + total VAT (ibr-co-15).
Name
prepaid_amount
Type
number (optional)
Description
Paid amount (IBT-113). Feeds the amount-due formula (ibr-co-16).
Name
payable_rounding_amount
Type
number (optional)
Description
Rounding amount (IBT-114).
Name
payable_amount
Type
number (auto)
Description
Amount due for payment (IBT-115) = total incl. tax − prepaid + rounding (ibr-co-16). If money is still owed (amount due > 0) you must say when it's due via due_date or installment dates — except on credit notes and deemed supplies (ibr-127-ae).
Name
tax_included_indicator
Type
boolean (optional)
Description
Whether line prices include VAT (IBT-200). Default false.
Name
total_tax_amount_in_aed
Type
number (auto)
Description
Total VAT in AED (IBT-111). Foreign-currency invoices must also state the total VAT amount in AED (ibr-175-ae). Auto-computed via currency_exchange_rate. The VAT total in document currency and the VAT total in AED must have the same sign (ibr-084).
Name
total_amount_with_tax_in_aed
Type
number (auto)
Description
Grand total (incl. VAT) in AED (BTAE-20). Required alongside the AED VAT total on foreign-currency documents (ibr-175-ae). Auto-computed.

POST/v3/{participant_id}/documents

Issue a Document

Submits an invoice or credit note for validation, clearance and Peppol exchange.

Pipeline: seller prefill from participant profile → normalisation (aliases, AED conversion, VAT breakdown, totals) → layer-1 JSON checks → UBL 2.1 XML generation → layer-2 PINT AE 1.0.4 schematron → persist + schedule delivery.

If any layer reports errors the request fails with HTTP 400 and nothing is stored. Non-fatal payload adjustments (e.g. legacy 389 type-code normalisation) are reported in warnings on the success response.

You can also send raw UBL XML instead of JSON (Content-Type: application/xml) — the XML is parsed losslessly into the same model.

Path Parameters

Name
participant_id
Type
uuid
Description
UUID of an active participant owned by your account. Returns 403 if the participant exists but is not active, 404 if it doesn't exist.

Headers

Name
Idempotency-Key
Type
string (optional)
Description
Unique key for safe retries. A repeated key returns the originally created document with is_duplicate: true instead of creating a second one.

Request Body

The body is a single document object. Only the fields below are required for the simplest domestic AED invoice — everything else (seller details, UUID, VAT breakdown, totals, AED amounts) is prefilled or auto-computed. See the sample on the right: that payload is complete and valid as-is.

Name
document_identifier
Type
string
Description
Your invoice / credit note number (IBT-001). Every document must include one (ibr-002).
Name
issue_date
Type
date
Description
Issue date (IBT-002), format YYYY-MM-DD (ibr-003, ibr-073).
Name
issue_time
Type
string (optional)
Description
Issue time with timezone offset, e.g. 10:30:00+04:00 (IBT-168). Times must be written as hh:mm:ss, optionally with fractional seconds and a timezone (ibr-119).
Name
due_date
Type
date (conditional)
Description
Payment due date (IBT-009). If money is still owed (amount due > 0) you must say when it's due — except on credit notes and deemed supplies, where no payment is expected (ibr-127-ae). Alternatively, give an installment_due_date on every payment_terms entry.
Name
document_type
Type
string
Description
Document type code (IBT-003): 380, 480, 381 or 81 — see the Document Types table (ibr-cl-01).
Name
document_currency
Type
string
Description
Invoice currency (IBT-005), ISO 4217 — e.g. AED, USD (ibr-cl-04). If the document isn't in AED, you must provide currency_exchange_rate (ibr-159-ae).
Name
currency_exchange_rate
Type
number (conditional)
Description
Currency-to-AED exchange rate (BTAE-04). Required for non-AED documents (ibr-159-ae). Can have at most 6 decimal places (ibr-002-ae). Direction matters: source currency = invoice currency, target = AED (ibr-153-ae).
Name
tax_accounting_currency
Type
string (auto)
Description
VAT accounting currency (IBT-006). Always AED — auto-set. If you provide it, it can only be AED (ibr-140-ae) and must differ from the invoice currency (ibr-077).
Name
tax_point_date
Type
date (conditional)
Description
VAT point date (IBT-007). When given, it must be earlier than the issue date (ibr-141-ae). Credit notes never carry a VAT point date — leave it out when the type is 381 or 81 (ibr-124-ae).
Name
uuid
Type
uuid (auto)
Description
Globally unique document UUID (BTAE-07) — this is what makes the document traceable across the whole system (ibr-193-ae). Auto-generated when omitted.
Name
note
Type
string (optional)
Description
Free-text note (IBT-022). Required to explain the billing frequency when invoice_period.description_code is OTH (ibr-160-ae).
Name
buyer_reference
Type
string (optional)
Description
Buyer reference (IBT-010).
Name
accounting_cost
Type
string (optional)
Description
Buyer accounting reference (IBT-019).
Name
credit_note_reason_code
Type
string (conditional)
Description
Credit notes only (BTAE-03). If the document type is Credit note (381), you must give a credit note reason code (ibr-158-ae), from the official reasons list — DL8.61.1.A…DL8.61.1.E or VD (ibr-001-ae). Any reason other than VD also requires document_references to the corrected invoice(s) (ibr-055-ae). See the Credit Note Reasons table under Code Lists.
Name
credit_note_reason
Type
string (optional)
Description
Credit notes only. Free-text reason accompanying the code.
Name
flags
Type
flags (optional)
Description
Transaction-nature flags — see the Transaction Flags table. All default to false.
Name
principal_id
Type
string (conditional)
Description
TRN of the principal supplier (BTAE-14). Disclosed-agent invoices must name the principal (ibr-137-ae); the agent and the principal must be different entities — their TRNs can't be the same (ibr-176-ae).
Name
issuing_party
Type
issuing_party (optional)
Description
Seller party — prefilled from the participant profile. Struct: issuing_party.
Name
receiving_party
Type
receiving_party
Description
Buyer party. Struct: receiving_party.
Name
payment_means
Type
payment_means[]
Description
Payment instructions — at least one entry with a type_code (ibr-191-ae, ibr-049). Struct: payment_means[].
Name
invoice_lines
Type
invoice_lines[]
Description
Document lines — at least one (ibr-016). Struct: invoice_lines[].
Name
invoice_period
Type
invoice_period (conditional)
Description
Billing period. Required for summary invoices (ibr-138-ae). Struct: invoice_period.
Name
document_references
Type
document_references[] (conditional)
Description
Preceding invoice references. Required on credit notes unless the reason is VD (ibr-055-ae). Struct: document_references[].
Name
order_reference / other_references
Type
objects (optional)
Description
Order, despatch, contract, customs and project references. Struct: order_reference / other_references.
Name
additional_document_references
Type
array (optional)
Description
Supporting documents and attachments. Struct: additional_document_references[].
Name
payee_party
Type
payee_party (optional)
Description
Only when the payment receiver differs from the seller (ibr-017). Struct: payee_party.
Name
tax_representative
Type
tax_representative (optional)
Description
Seller tax representative (ibr-018). Struct: tax_representative.
Name
delivery
Type
delivery (conditional)
Description
Delivery information. Required for e-commerce (ibr-142-ae) and export (ibr-152-ae) supplies. Struct: delivery.
Name
allowance_charge
Type
allowance_charge[] (optional)
Description
Document-level discounts and charges. Struct: allowance_charge[].
Name
payment_terms
Type
payment_terms[] (optional)
Description
Payment terms / installments. Struct: payment_terms[].
Name
vat_totals
Type
vat_totals[] (auto)
Description
VAT breakdown — auto-computed when omitted. Struct: vat_totals[].
Name
invoice_totals
Type
invoice_totals (auto)
Description
Document totals — auto-computed when omitted. Struct: invoice_totals.

Minimal Payload

POST

/v3/{participant_id}/documents

curl --request POST \
  --url https://sb-ae-api.flick.network/v3/{participant_id}/documents \
  --header 'X-Flick-Auth-Key: {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "document": {
      "document_identifier": "INV-0001/2026",
      "issue_date": "2026-07-23",
      "due_date": "2026-08-22",
      "document_type": "380",
      "document_currency": "AED",
      "receiving_party": {
        "legal_name": "Gulf Retail Trading LLC",
        "peppol_id": "0235:112345679000003",
        "identifiers": {
          "AE:VAT": { "value": "112345679000003" }
        },
        "street_address": "Khalifa Street 12",
        "city_address": "Abu Dhabi",
        "emirates_code": "AUH",
        "country_code": "AE"
      },
      "payment_means": [
        { "type_code": "10" }
      ],
      "invoice_lines": [
        {
          "id": "1",
          "name": "Smart POS Terminal X9",
          "description": "Handheld smart POS terminal, dual-SIM, 256GB",
          "quantity": 10,
          "uom": "H87",
          "unit_price": 100.00,
          "tax_category": "S",
          "tax_percentage": 5
        }
      ]
    }
  }'

Sample Response

200

Success

{
  "status": "success",
  "message": "Document submitted successfully",
  "data": {
    "id": "1de47b81-9c34-4f0a-b2fe-05e6a7c31f88",
    "status": "processing",
    "document_identifier": "INV-0001/2026",
    "exchange_status": "pending",
    "reporting_status": "pending",
    "peppol_message_id": null,
    "envelope_id": null,
    "is_duplicate": false,
    "created_at": "2026-07-23T06:15:42Z",
    "warnings": []
  }
}

Validation Error

400

Failed

{
  "status": "failed",
  "message": "Invalid request payload.",
  "errors": [
    {
      "code": "ibr-159-ae",
      "document_identifier": "INV-0002/2026",
      "message": "If the invoice isn't in AED, you must provide the exchange rate to AED.",
      "path": "currency_exchange_rate"
    },
    {
      "code": "ibr-128-ae",
      "document_identifier": "INV-0002/2026",
      "message": "For any UAE address, the country subdivision must be one of the 7 official Emirate codes: AUH, DXB, SHJ, UAQ, FUJ, AJM, RAK.",
      "path": "receiving_party.emirates_code"
    }
  ],
  "warnings": []
}

GET/v3/{participant_id}/documents/{document_id}

Get a Document

Returns the full document record — lifecycle status, exchange and reporting statuses, Peppol message identifiers, and the complete normalised payload under parsed. Works for both outgoing documents you issued and incoming documents received over the network.

Path Parameters

Name
participant_id
Type
uuid
Description
UUID of the active participant that owns the document.
Name
document_id
Type
uuid
Description
The document id returned when the document was issued (or received).

Response Fields

Name
status
Type
string
Description
Overall lifecycle status of the document, e.g. processing, completed, failed.
Name
direction
Type
string
Description
outgoing (you issued it) or incoming (received from a supplier over Peppol).
Name
type
Type
string
Description
invoice, creditNote, selfBillingInvoice or selfBillingCreditNote — derived from document_type + flags.is_selfbilled.
Name
exchange_status
Type
string
Description
Peppol delivery status, e.g. pending, delivered, failed.
Name
reporting_status
Type
string
Description
Tax-authority reporting status, e.g. pending, reported.
Name
peppol_message_id / peppol_conversation_id
Type
string
Description
Identifiers assigned on the Peppol network once the document is exchanged.
Name
validation
Type
object
Description
The validation verdict recorded at submission time.
Name
parsed
Type
object
Description
The complete normalised v3 payload merged with the stored summary — everything you submitted plus all auto-computed values (UUID, VAT breakdown, totals, AED amounts).

Sample Request

GET

/v3/{participant_id}/documents/{document_id}

curl --url https://sb-ae-api.flick.network/v3/{participant_id}/documents/{document_id} \
  --header 'X-Flick-Auth-Key: {token}'

Sample Response

200

Success

{
  "status": "success",
  "message": "Resource retrieved successfully",
  "data": {
    "id": "1de47b81-9c34-4f0a-b2fe-05e6a7c31f88",
    "status": "completed",
    "document_identifier": "INV-0001/2026",
    "participant_id": "7b6a1f7e-30cf-4a11-9c5c-2e6f9a4d5b21",
    "direction": "outgoing",
    "sender_id": "0235:100000000000003",
    "receiver_id": "0235:112345679000003",
    "type": "invoice",
    "exchange_status": "delivered",
    "reporting_status": "reported",
    "reporting_reference": "FTA-2026-0098231",
    "peppol_message_id": "a41f9c7e-77e2-4d16-8f2a-91b3c5d60f44",
    "peppol_conversation_id": "cc93b6e2-1f04-45d7-9a3e-7d21f84a6c02",
    "envelope_id": "env-59d20c17",
    "validation": { "result": "valid", "error_count": 0 },
    "labels": [],
    "read_at": null,
    "created_at": "2026-07-23T06:15:42Z",
    "updated_at": "2026-07-23T06:16:05Z",
    "parsed": {
      "document_identifier": "INV-0001/2026",
      "uuid": "0f4d2a9b-58e1-4f7c-9d36-b91c2f8a7e55",
      "document_type": "380",
      "issue_date": "2026-07-23",
      "due_date": "2026-08-22",
      "document_currency": "AED",
      "tax_accounting_currency": "AED",
      "issuing_party": { "legal_name": "Desert Tech Solutions LLC", "vat_number": "100000000000003" },
      "receiving_party": { "legal_name": "Gulf Retail Trading LLC", "peppol_id": "0235:112345679000003" },
      "invoice_lines": [
        {
          "id": "1",
          "name": "Smart POS Terminal X9",
          "quantity": 10,
          "uom": "H87",
          "unit_price": 100.0,
          "line_extension_amount": 1000.0,
          "vat_category": "S",
          "vat_percentage": 5,
          "vat_line_amount": 50.0,
          "line_amount_aed": 1050.0,
          "vat_line_amount_aed": 50.0
        }
      ],
      "vat_totals": [
        { "tax_category": "S", "tax_rate": 5, "taxable_amount": 1000.0, "tax_amount": 50.0 }
      ],
      "invoice_totals": {
        "line_extension_amount": 1000.0,
        "tax_exclusive_amount": 1000.0,
        "tax_amount": 50.0,
        "tax_inclusive_amount": 1050.0,
        "payable_amount": 1050.0
      }
    }
  }
}

GET/v3/{participant_id}/documents/{document_id}/xml

Download UBL XML

Regenerates and streams the PINT AE 1.0.4 UBL 2.1 XML for a stored document — the exact compliant representation that travels over the Peppol network. Use this when you need the legal artefact for archiving, audits, or handing to another system.

The response is raw XML (Content-Type: application/xml). If you prefer the XML wrapped in a JSON envelope as a Base64 string, use the /xml-base64 variant of this endpoint.

Path Parameters

Name
participant_id
Type
uuid
Description
UUID of the active participant that owns the document.
Name
document_id
Type
uuid
Description
The document id. Returns 404 if the document doesn't exist for this participant.

Sample Request

GET

/v3/{participant_id}/documents/{document_id}/xml

curl --url https://sb-ae-api.flick.network/v3/{participant_id}/documents/{document_id}/xml \
  --header 'X-Flick-Auth-Key: {token}' \
  --output INV-0001-2026.xml

Sample Response

200

application/xml

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
         xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
         xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">
  <cbc:CustomizationID>urn:peppol:pint:billing-1@ae-1</cbc:CustomizationID>
  <cbc:ProfileID>urn:peppol:bis:billing</cbc:ProfileID>
  <cbc:ProfileExecutionID>00000000</cbc:ProfileExecutionID>
  <cbc:ID>INV-0001/2026</cbc:ID>
  <cbc:UUID>0f4d2a9b-58e1-4f7c-9d36-b91c2f8a7e55</cbc:UUID>
  <cbc:IssueDate>2026-07-23</cbc:IssueDate>
  <cbc:DueDate>2026-08-22</cbc:DueDate>
  <cbc:InvoiceTypeCode>380</cbc:InvoiceTypeCode>
  <cbc:DocumentCurrencyCode>AED</cbc:DocumentCurrencyCode>
  <cac:AccountingSupplierParty>
    <!-- seller party, prefilled from the participant profile -->
  </cac:AccountingSupplierParty>
  <cac:AccountingCustomerParty>
    <!-- buyer party -->
  </cac:AccountingCustomerParty>
  <cac:TaxTotal>
    <cbc:TaxAmount currencyID="AED">50.00</cbc:TaxAmount>
    <!-- VAT breakdown per category -->
  </cac:TaxTotal>
  <cac:LegalMonetaryTotal>
    <cbc:PayableAmount currencyID="AED">1050.00</cbc:PayableAmount>
  </cac:LegalMonetaryTotal>
  <cac:InvoiceLine>
    <!-- one element per line, incl. AED line amounts -->
  </cac:InvoiceLine>
</Invoice>

More Use Cases

All the scenarios below use the same Issue a Document endpoint. Each sample is a complete, runnable curl — replace {participant_id} and {token} and hit it directly against the sandbox. Only the fields that scenario involves are explained in detail; everything else behaves exactly as in the minimal example.

Use Case 1: Credit Note

Issue a Tax Credit Note to correct or cancel a previously issued invoice.

Fields involved:

Name
document_type
Type
string
Description
Set to 381.
Name
credit_note_reason_code
Type
string
Description
A credit note (381) must give a reason code (ibr-158-ae) from the official list (ibr-001-ae): DL8.61.1.A supply cancelled, .B tax treatment changed, .C consideration altered (e.g. bad debt relief), .D goods/services returned, .E tax charged in error, or VD volume discount.
Name
document_references
Type
array (conditional)
Description
The credit note must reference the original invoice it corrects — except volume-discount (VD) credit notes, which don't tie to a single invoice (ibr-055-ae).
Name
due_date / tax_point_date
Type
—
Description
Leave both out. No payment is expected on a credit note (ibr-127-ae), payment means are not required (ibr-191-ae), and credit notes never carry a VAT point date (ibr-124-ae).

Credit Note

POST

/v3/{participant_id}/documents

curl --request POST \
  --url https://sb-ae-api.flick.network/v3/{participant_id}/documents \
  --header 'X-Flick-Auth-Key: {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "document": {
      "document_identifier": "CN-0007/2026",
      "issue_date": "2026-07-24",
      "document_type": "381",
      "document_currency": "AED",
      "credit_note_reason_code": "DL8.61.1.D",
      "credit_note_reason": "Goods returned by the buyer",
      "document_references": [
        { "document_identifier": "INV-0001/2026", "issue_date": "2026-07-23" }
      ],
      "receiving_party": {
        "legal_name": "Gulf Retail Trading LLC",
        "peppol_id": "0235:112345679000003",
        "vat_number": "112345679000003",
        "street_address": "Khalifa Street 12",
        "city_address": "Abu Dhabi",
        "emirates_code": "AUH",
        "country_code": "AE"
      },
      "invoice_lines": [
        {
          "id": "1",
          "name": "Smart POS Terminal X9",
          "description": "Returned units - 2 of 10 from INV-0001/2026",
          "quantity": 2,
          "uom": "H87",
          "unit_price": 100.00,
          "vat_category": "S",
          "vat_percentage": 5
        }
      ]
    }
  }'

Use Case 2: Self-Billed Invoice

The buyer issues the invoice on behalf of the supplier (e.g. agreed self-billing arrangements).

Fields involved:

Name
flags.is_selfbilled
Type
boolean
Description
Set to true. The document must declare which rulebook it follows — the flag switches the specification identifier to the official self-billing variant automatically (aligned-ibrp-001-ae), and the business process to the self-billing process (aligned-ibrp-002-ae).
Name
issuing_party / receiving_party
Type
party
Description
Keep them logical, not literal: issuing_party stays the seller (the supplier whose goods were bought) and receiving_party stays the buyer (who is actually creating this document). Flick swaps the supplier/customer roles in the generated XML for you.
Name
document_type
Type
string
Description
Stays 380. Do not use the legacy self-billing code 389 — it is auto-normalised to 380 + is_selfbilled: true with a deprecation warning.

Self-Billed Invoice

POST

/v3/{participant_id}/documents

curl --request POST \
  --url https://sb-ae-api.flick.network/v3/{participant_id}/documents \
  --header 'X-Flick-Auth-Key: {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "document": {
      "document_identifier": "SBINV-0031/2026",
      "issue_date": "2026-07-24",
      "due_date": "2026-08-23",
      "document_type": "380",
      "document_currency": "AED",
      "flags": { "is_selfbilled": true },
      "issuing_party": {
        "legal_name": "Emirates Fresh Farms LLC",
        "vat_number": "100000000000103",
        "peppol_id": "0235:100000000000103",
        "street_address": "Industrial Area 4",
        "city_address": "Sharjah",
        "emirates_code": "SHJ",
        "country_code": "AE"
      },
      "receiving_party": {
        "legal_name": "Gulf Retail Trading LLC",
        "peppol_id": "0235:112345679000003",
        "vat_number": "112345679000003",
        "street_address": "Khalifa Street 12",
        "city_address": "Abu Dhabi",
        "emirates_code": "AUH",
        "country_code": "AE"
      },
      "payment_means": [
        { "type_code": "30", "payment_account_id": "AE070331234567890123456" }
      ],
      "invoice_lines": [
        {
          "id": "1",
          "name": "Fresh produce - weekly supply",
          "description": "Assorted fresh vegetables, week 30",
          "quantity": 500,
          "uom": "KGM",
          "unit_price": 4.50,
          "vat_category": "S",
          "vat_percentage": 5
        }
      ]
    }
  }'

Use Case 3: Self-Billed Credit Note

The buyer corrects a self-billed invoice it previously issued. This simply combines the two cases above.

Fields involved:

Name
document_type
Type
string
Description
Set to 381 (legacy 361 is auto-normalised).
Name
flags.is_selfbilled
Type
boolean
Description
Set to true.
Name
credit_note_reason_code + document_references
Type
—
Description
Same rules as a regular credit note: reason code required (ibr-158-ae), original-invoice references required unless the reason is VD (ibr-055-ae).

Self-Billed Credit Note

POST

/v3/{participant_id}/documents

curl --request POST \
  --url https://sb-ae-api.flick.network/v3/{participant_id}/documents \
  --header 'X-Flick-Auth-Key: {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "document": {
      "document_identifier": "SBCN-0004/2026",
      "issue_date": "2026-07-25",
      "document_type": "381",
      "document_currency": "AED",
      "flags": { "is_selfbilled": true },
      "credit_note_reason_code": "DL8.61.1.E",
      "credit_note_reason": "Tax applied in error on self-billed invoice",
      "document_references": [
        { "document_identifier": "SBINV-0031/2026", "issue_date": "2026-07-24" }
      ],
      "issuing_party": {
        "legal_name": "Emirates Fresh Farms LLC",
        "vat_number": "100000000000103",
        "peppol_id": "0235:100000000000103",
        "street_address": "Industrial Area 4",
        "city_address": "Sharjah",
        "emirates_code": "SHJ",
        "country_code": "AE"
      },
      "receiving_party": {
        "legal_name": "Gulf Retail Trading LLC",
        "peppol_id": "0235:112345679000003",
        "vat_number": "112345679000003",
        "street_address": "Khalifa Street 12",
        "city_address": "Abu Dhabi",
        "emirates_code": "AUH",
        "country_code": "AE"
      },
      "invoice_lines": [
        {
          "id": "1",
          "name": "Fresh produce - weekly supply",
          "description": "Correction of VAT charged in error on SBINV-0031/2026",
          "quantity": 500,
          "uom": "KGM",
          "unit_price": 4.50,
          "vat_category": "S",
          "vat_percentage": 5
        }
      ]
    }
  }'

Use Case 4: Foreign-Currency Invoice

Invoice in any ISO 4217 currency — VAT is still accounted in AED.

Fields involved:

Name
document_currency
Type
string
Description
Any ISO 4217 code, e.g. USD (ibr-cl-04).
Name
currency_exchange_rate
Type
number
Description
If the invoice isn't in AED, you must provide the exchange rate to AED (ibr-159-ae). At most 6 decimal places (ibr-002-ae). The rate direction is invoice currency → AED (ibr-153-ae).
Name
invoice_totals.total_tax_amount_in_aed / total_amount_with_tax_in_aed
Type
number (auto)
Description
Foreign-currency invoices must also state the total VAT amount in AED and the grand total (incl. VAT) in AED (ibr-175-ae). Auto-computed from the exchange rate — you don't need to send them.
Name
line_amount_aed / vat_line_amount_aed
Type
number (auto)
Description
Every line must state its payable amount in AED (ibr-194-ae) plus its VAT amount in AED (ibr-104-ae). Also auto-computed.

USD Invoice

POST

/v3/{participant_id}/documents

curl --request POST \
  --url https://sb-ae-api.flick.network/v3/{participant_id}/documents \
  --header 'X-Flick-Auth-Key: {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "document": {
      "document_identifier": "INV-0090/2026",
      "issue_date": "2026-07-24",
      "due_date": "2026-08-23",
      "document_type": "380",
      "document_currency": "USD",
      "currency_exchange_rate": 3.6725,
      "receiving_party": {
        "legal_name": "Gulf Retail Trading LLC",
        "peppol_id": "0235:112345679000003",
        "vat_number": "112345679000003",
        "street_address": "Khalifa Street 12",
        "city_address": "Abu Dhabi",
        "emirates_code": "AUH",
        "country_code": "AE"
      },
      "payment_means": [
        { "type_code": "30", "payment_account_id": "AE070331234567890123456" }
      ],
      "invoice_lines": [
        {
          "id": "1",
          "name": "Consulting retainer",
          "description": "Monthly advisory retainer - July 2026",
          "quantity": 1,
          "uom": "H87",
          "unit_price": 2500.00,
          "vat_category": "S",
          "vat_percentage": 5
        }
      ]
    }
  }'

Use Case 5: Free-Trade-Zone Supply

Supplies within / to a UAE free-trade zone (designated zone).

Fields involved:

Name
flags.is_ftz
Type
boolean
Description
Set to true. Sets position 1 of the transaction type code.
Name
receiving_party.fz_beneficiary_id
Type
string
Description
Free-trade-zone invoices must name the beneficiary: provide the Beneficiary ID — a TRN or TIN (BTAE-01, ibr-007-ae).

FTZ Supply

POST

/v3/{participant_id}/documents

curl --request POST \
  --url https://sb-ae-api.flick.network/v3/{participant_id}/documents \
  --header 'X-Flick-Auth-Key: {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "document": {
      "document_identifier": "INV-0101/2026",
      "issue_date": "2026-07-24",
      "due_date": "2026-08-23",
      "document_type": "380",
      "document_currency": "AED",
      "flags": { "is_ftz": true },
      "receiving_party": {
        "legal_name": "JAFZA Logistics FZE",
        "peppol_id": "0235:112345679000103",
        "vat_number": "112345679000103",
        "fz_beneficiary_id": "112345679000103",
        "street_address": "Jebel Ali Free Zone, Gate 4",
        "city_address": "Dubai",
        "emirates_code": "DXB",
        "country_code": "AE"
      },
      "payment_means": [
        { "type_code": "30", "payment_account_id": "AE070331234567890123456" }
      ],
      "invoice_lines": [
        {
          "id": "1",
          "name": "Warehouse racking system",
          "description": "Heavy-duty pallet racking, 40 bays, installed",
          "quantity": 40,
          "uom": "H87",
          "unit_price": 1200.00,
          "vat_category": "S",
          "vat_percentage": 5
        }
      ]
    }
  }'

Use Case 6: Reverse-Charge Supply

Domestic reverse charge — the buyer accounts for the VAT instead of the seller.

Fields involved:

Name
invoice_lines[].vat_category
Type
string
Description
Set to AE (VAT Reverse Charge). The line must still state the applicable VAT rate (aligned-ibrp-ae-05-ae), but its VAT amount is 0 — the buyer accounts for the tax (aligned-ibrp-ae-09-ae), and the AED VAT line amount must be zero (ibr-162-ae).
Name
receiving_party.vat_number
Type
string
Description
Reverse charge shifts the tax to the buyer — so the buyer's TRN becomes mandatory (ibr-103-ae).
Name
invoice_lines[].standard_item_id
Type
string
Description
Reverse-charge items must carry a GTIN: the standard item identifier is mandatory with scheme 0160 (ibr-174-ae).
Name
invoice_lines[].reverse_charge_item_type
Type
string
Description
Reverse-charge items must state the type of goods or services (ibr-166-ae), from the official RCM code list (ibr-006-ae) — e.g. DL8.48.8.1.

Reverse Charge

POST

/v3/{participant_id}/documents

curl --request POST \
  --url https://sb-ae-api.flick.network/v3/{participant_id}/documents \
  --header 'X-Flick-Auth-Key: {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "document": {
      "document_identifier": "INV-0115/2026",
      "issue_date": "2026-07-24",
      "due_date": "2026-08-23",
      "document_type": "380",
      "document_currency": "AED",
      "receiving_party": {
        "legal_name": "Gulf Retail Trading LLC",
        "peppol_id": "0235:112345679000003",
        "vat_number": "112345679000003",
        "street_address": "Khalifa Street 12",
        "city_address": "Abu Dhabi",
        "emirates_code": "AUH",
        "country_code": "AE"
      },
      "payment_means": [
        { "type_code": "30", "payment_account_id": "AE070331234567890123456" }
      ],
      "invoice_lines": [
        {
          "id": "1",
          "name": "Crude oil supply",
          "description": "Crude oil - reverse charge under Art. 48(8)",
          "quantity": 500,
          "uom": "BLL",
          "unit_price": 260.00,
          "vat_category": "AE",
          "vat_percentage": 5,
          "standard_item_id": "04012345123456",
          "standard_item_id_scheme": "0160",
          "reverse_charge_item_type": "DL8.48.8.1"
        }
      ]
    }
  }'

Use Case 7: Exempt Supply

Supplies exempt from VAT (e.g. certain financial services, residential leases).

Fields involved:

Name
invoice_lines[].vat_category
Type
string
Description
Set to E (Exempt). An exempt line must not state a VAT rate at all (aligned-ibrp-e-05), and no AED VAT line amount may be provided (ibr-163-ae).
Name
invoice_lines[].vat_exemption_reason_code
Type
string
Description
Every exempt line must carry an exemption reason code explaining WHY it's exempt (ibr-167-ae) — from the Reasons for exemption from tax list, e.g. DL8.46.1 for certain financial services.
Name
vat_totals
Type
array (auto)
Description
There must be exactly one Exempt row in the VAT breakdown (aligned-ibrp-e-01), with VAT amount 0 (aligned-ibrp-e-09) and no rate (ibr-121-ae). Built automatically from your lines.

A commercial invoice can't be made up ONLY of exempt / not-subject-to-VAT items — if everything is out of scope, use document type 480 / 81 instead (ibr-151-ae).

Exempt Supply

POST

/v3/{participant_id}/documents

curl --request POST \
  --url https://sb-ae-api.flick.network/v3/{participant_id}/documents \
  --header 'X-Flick-Auth-Key: {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "document": {
      "document_identifier": "INV-0122/2026",
      "issue_date": "2026-07-24",
      "due_date": "2026-08-23",
      "document_type": "380",
      "document_currency": "AED",
      "receiving_party": {
        "legal_name": "Gulf Retail Trading LLC",
        "peppol_id": "0235:112345679000003",
        "vat_number": "112345679000003",
        "street_address": "Khalifa Street 12",
        "city_address": "Abu Dhabi",
        "emirates_code": "AUH",
        "country_code": "AE"
      },
      "payment_means": [
        { "type_code": "30", "payment_account_id": "AE070331234567890123456" }
      ],
      "invoice_lines": [
        {
          "id": "1",
          "name": "Life insurance premium",
          "description": "Term life insurance premium - policy 88410",
          "quantity": 1,
          "uom": "H87",
          "unit_price": 1200.00,
          "vat_category": "E",
          "vat_exemption_reason_code": "DL8.46.1",
          "vat_exemption_reason": "Certain financial services"
        },
        {
          "id": "2",
          "name": "Policy admin fee",
          "description": "Administrative service fee",
          "quantity": 1,
          "uom": "H87",
          "unit_price": 100.00,
          "vat_category": "S",
          "vat_percentage": 5
        }
      ]
    }
  }'

Use Case 8: Zero-Rated & Export Supply

Zero-rated supplies (0% VAT), most commonly exports of goods or services.

Fields involved:

Name
invoice_lines[].vat_category
Type
string
Description
Set to Z (Zero rated). A zero-rated line must state the VAT rate as exactly 0 (aligned-ibrp-z-05), and its AED VAT line amount must be zero (ibr-165-ae).
Name
flags.is_export
Type
boolean
Description
Set to true for exports (position 8). Export invoices must include a delivery address (line 1, city, subdivision) and the destination country must NOT be AE (ibr-152-ae).
Name
delivery.address
Type
object
Description
The foreign delivery address required by the export flag (ibr-152-ae).
Name
receiving_party
Type
party
Description
For exports, the usual domestic buyer-identification requirement is relaxed — a buyer identifier / TRN is not demanded (ibr-135-ae).

Export Invoice

POST

/v3/{participant_id}/documents

curl --request POST \
  --url https://sb-ae-api.flick.network/v3/{participant_id}/documents \
  --header 'X-Flick-Auth-Key: {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "document": {
      "document_identifier": "INV-0130/2026",
      "issue_date": "2026-07-24",
      "due_date": "2026-08-23",
      "document_type": "380",
      "document_currency": "USD",
      "currency_exchange_rate": 3.6725,
      "flags": { "is_export": true },
      "receiving_party": {
        "legal_name": "Mumbai Electronics Pvt Ltd",
        "peppol_id": "0060:5790000435968",
        "street_address": "Andheri East",
        "city_address": "Mumbai",
        "country_code": "IN"
      },
      "delivery": {
        "actual_delivery_date": "2026-07-30",
        "address": {
          "street_address": "Nhava Sheva Port, Terminal 2",
          "city_address": "Mumbai",
          "country_code": "IN"
        },
        "delivery_terms": { "incoterms": "CIF" }
      },
      "payment_means": [
        { "type_code": "30", "payment_account_id": "AE070331234567890123456" }
      ],
      "invoice_lines": [
        {
          "id": "1",
          "name": "Smart POS Terminal X9",
          "description": "Export consignment - 200 units",
          "quantity": 200,
          "uom": "H87",
          "unit_price": 95.00,
          "vat_category": "Z",
          "vat_percentage": 0
        }
      ]
    }
  }'

Use Case 9: Summary Invoice

One invoice summarizing multiple supplies over a period (e.g. a month of deliveries).

Fields involved:

Name
flags.is_summary
Type
boolean
Description
Set to true (position 4). Summary invoices must state the billing period they summarize (ibr-138-ae).
Name
invoice_period
Type
object
Description
Give at least a start date or an end date (ibr-co-19); the period can't end before it starts (ibr-029). Optionally add the billing frequency code — DLY, WKY, MTH, QTR, YRL, OTH (ibr-005-ae). If the frequency is OTH, explain the actual frequency in the document note (ibr-160-ae).
Name
invoice_lines[].invoice_period_start_date / _end_date
Type
date (optional)
Description
Optional per-line periods — each line's period must start and end within the overall invoicing period (ibr-085, ibr-086).

Summary Invoice

POST

/v3/{participant_id}/documents

curl --request POST \
  --url https://sb-ae-api.flick.network/v3/{participant_id}/documents \
  --header 'X-Flick-Auth-Key: {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "document": {
      "document_identifier": "INV-0140/2026",
      "issue_date": "2026-08-01",
      "due_date": "2026-08-31",
      "document_type": "380",
      "document_currency": "AED",
      "flags": { "is_summary": true },
      "invoice_period": {
        "start_date": "2026-07-01",
        "end_date": "2026-07-31",
        "description_code": "MTH"
      },
      "receiving_party": {
        "legal_name": "Gulf Retail Trading LLC",
        "peppol_id": "0235:112345679000003",
        "vat_number": "112345679000003",
        "street_address": "Khalifa Street 12",
        "city_address": "Abu Dhabi",
        "emirates_code": "AUH",
        "country_code": "AE"
      },
      "payment_means": [
        { "type_code": "30", "payment_account_id": "AE070331234567890123456" }
      ],
      "invoice_lines": [
        {
          "id": "1",
          "name": "Daily bread delivery",
          "description": "Deliveries for July 2026, 31 days",
          "quantity": 31,
          "uom": "DAY",
          "unit_price": 250.00,
          "vat_category": "S",
          "vat_percentage": 5,
          "invoice_period_start_date": "2026-07-01",
          "invoice_period_end_date": "2026-07-31"
        }
      ]
    }
  }'

Use Case 10: E-Commerce Supply

Supplies made through an e-commerce platform or online store.

Fields involved:

Name
flags.is_ecommerce
Type
boolean
Description
Set to true (position 7). E-commerce supplies must include the delivery address: address line 1, city and Emirate (ibr-142-ae).
Name
delivery.address
Type
object
Description
The delivery address demanded by the flag. For a UAE address, emirates_code must be one of the 7 Emirate codes (ibr-128-ae) and a country code is always required (ibr-057).

E-Commerce

POST

/v3/{participant_id}/documents

curl --request POST \
  --url https://sb-ae-api.flick.network/v3/{participant_id}/documents \
  --header 'X-Flick-Auth-Key: {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "document": {
      "document_identifier": "INV-0155/2026",
      "issue_date": "2026-07-24",
      "due_date": "2026-07-24",
      "document_type": "380",
      "document_currency": "AED",
      "flags": { "is_ecommerce": true },
      "receiving_party": {
        "legal_name": "Gulf Retail Trading LLC",
        "peppol_id": "0235:112345679000003",
        "vat_number": "112345679000003",
        "street_address": "Khalifa Street 12",
        "city_address": "Abu Dhabi",
        "emirates_code": "AUH",
        "country_code": "AE"
      },
      "delivery": {
        "actual_delivery_date": "2026-07-25",
        "party_name": "Sara Al Marzooqi",
        "address": {
          "street_address": "Villa 22, Al Wasl Road",
          "city_address": "Dubai",
          "emirates_code": "DXB",
          "country_code": "AE"
        }
      },
      "payment_means": [
        {
          "type_code": "54",
          "card": {
            "primary_account_number": "XXXXXXXXXXXX4321",
            "network_id": "VISA",
            "holder_name": "Sara Al Marzooqi"
          }
        }
      ],
      "invoice_lines": [
        {
          "id": "1",
          "name": "Wireless earbuds Pro 2",
          "description": "Online order #88712 - noise cancelling earbuds",
          "quantity": 1,
          "uom": "H87",
          "unit_price": 399.00,
          "vat_category": "S",
          "vat_percentage": 5
        }
      ]
    }
  }'

Use Case 11: Disclosed Agent Billing

An agent invoices the buyer on behalf of a disclosed principal supplier.

Fields involved:

Name
flags.is_dab
Type
boolean
Description
Set to true (position 6). Disclosed-agent invoices must name the principal (ibr-137-ae).
Name
principal_id
Type
string
Description
The principal supplier's TRN (BTAE-14). The agent (seller) and the principal must be different entities — their TRNs can't be the same (ibr-176-ae).

Disclosed Agent

POST

/v3/{participant_id}/documents

curl --request POST \
  --url https://sb-ae-api.flick.network/v3/{participant_id}/documents \
  --header 'X-Flick-Auth-Key: {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "document": {
      "document_identifier": "INV-0163/2026",
      "issue_date": "2026-07-24",
      "due_date": "2026-08-23",
      "document_type": "380",
      "document_currency": "AED",
      "flags": { "is_dab": true },
      "principal_id": "155667745601003",
      "receiving_party": {
        "legal_name": "Gulf Retail Trading LLC",
        "peppol_id": "0235:112345679000003",
        "vat_number": "112345679000003",
        "street_address": "Khalifa Street 12",
        "city_address": "Abu Dhabi",
        "emirates_code": "AUH",
        "country_code": "AE"
      },
      "payment_means": [
        { "type_code": "30", "payment_account_id": "AE070331234567890123456" }
      ],
      "invoice_lines": [
        {
          "id": "1",
          "name": "Freight forwarding - sea consignment",
          "description": "Ocean freight arranged on behalf of principal supplier",
          "quantity": 1,
          "uom": "H87",
          "unit_price": 18500.00,
          "vat_category": "S",
          "vat_percentage": 5
        }
      ]
    }
  }'

Use Case 12: Margin Scheme

Supplies taxed on the profit margin (e.g. second-hand goods), where VAT is embedded in the margin.

Fields involved:

Name
flags.is_margin
Type
boolean
Description
Set to true (position 3). If the transaction is flagged as margin scheme, all VAT categories on the document must be the margin-scheme category (ibr-116-ae).
Name
invoice_lines[].vat_category
Type
string
Description
Set to N (Standard rate additional VAT). A margin-scheme line must not have a 0% VAT rate (ibr-111-ae).
Name
invoice_lines[].vat_per_unit_amount
Type
number (optional)
Description
The per-unit VAT embedded in the margin.
Name
vat_totals
Type
array (auto)
Description
The breakdown must contain exactly one margin-scheme row (ibr-105-ae); it shows 0 as the VAT amount — the tax is embedded in the margin, not shown separately (ibr-108-ae). Document-level allowances and charges can never use category N (ibr-115-ae, ibr-114-ae).

Margin Scheme

POST

/v3/{participant_id}/documents

curl --request POST \
  --url https://sb-ae-api.flick.network/v3/{participant_id}/documents \
  --header 'X-Flick-Auth-Key: {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "document": {
      "document_identifier": "INV-0170/2026",
      "issue_date": "2026-07-24",
      "due_date": "2026-08-23",
      "document_type": "380",
      "document_currency": "AED",
      "flags": { "is_margin": true },
      "receiving_party": {
        "legal_name": "Gulf Retail Trading LLC",
        "peppol_id": "0235:112345679000003",
        "vat_number": "112345679000003",
        "street_address": "Khalifa Street 12",
        "city_address": "Abu Dhabi",
        "emirates_code": "AUH",
        "country_code": "AE"
      },
      "payment_means": [
        { "type_code": "30", "payment_account_id": "AE070331234567890123456" }
      ],
      "invoice_lines": [
        {
          "id": "1",
          "name": "Used vehicle - Nissan Patrol 2022",
          "description": "Pre-owned SUV sold under the profit margin scheme",
          "quantity": 1,
          "uom": "H87",
          "unit_price": 85000.00,
          "vat_category": "N",
          "vat_percentage": 5,
          "vat_per_unit_amount": 1000
        }
      ]
    }
  }'

Use Case 13: Discounts & Charges

Document-level discounts / charges (e.g. an order discount, a freight charge) and line-level ones.

Fields involved:

Name
allowance_charge[]
Type
array
Description
Document level. charge_indicator: false = discount, true = charge (ibr-082). Every entry must say why — as text or a reason code (ibr-033, ibr-038) — and which VAT category it belongs to (aligned-ibrp-032, aligned-ibrp-037). If you give both base_amount and percentage, the math must check out: amount = base × percentage ÷ 100 (ibr-131-ae, ibr-146-ae) — and they come as a pair, give both or neither (aligned-ibrp-057).
Name
invoice_lines[].allowance_charges[]
Type
array
Description
Line level. Same shape, but no VAT category — the line's own category applies. Amount is mandatory (ibr-041, ibr-043), and the reason (text or code) is too (ibr-042, ibr-044). Line net amount = quantity × unit price + line charges − line allowances (ibr-147-ae).
Name
invoice_totals
Type
object (auto)
Description
allowance_total_amount = sum of document discounts (ibr-co-11), charge_total_amount = sum of document charges (ibr-co-12), and total excl. tax = lines − allowances + charges (ibr-co-13). All auto-computed.

Discounts & Charges

POST

/v3/{participant_id}/documents

curl --request POST \
  --url https://sb-ae-api.flick.network/v3/{participant_id}/documents \
  --header 'X-Flick-Auth-Key: {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "document": {
      "document_identifier": "INV-0181/2026",
      "issue_date": "2026-07-24",
      "due_date": "2026-08-23",
      "document_type": "380",
      "document_currency": "AED",
      "receiving_party": {
        "legal_name": "Gulf Retail Trading LLC",
        "peppol_id": "0235:112345679000003",
        "vat_number": "112345679000003",
        "street_address": "Khalifa Street 12",
        "city_address": "Abu Dhabi",
        "emirates_code": "AUH",
        "country_code": "AE"
      },
      "payment_means": [
        { "type_code": "30", "payment_account_id": "AE070331234567890123456" }
      ],
      "allowance_charge": [
        {
          "charge_indicator": false,
          "reason_code": "95",
          "reason": "Order volume discount",
          "percentage": 5,
          "base_amount": 1000.00,
          "amount": 50.00,
          "vat_category": "S",
          "vat_percentage": 5
        },
        {
          "charge_indicator": true,
          "reason_code": "FC",
          "reason": "Freight charge",
          "amount": 100.00,
          "vat_category": "S",
          "vat_percentage": 5
        }
      ],
      "invoice_lines": [
        {
          "id": "1",
          "name": "Smart POS Terminal X9",
          "description": "Handheld smart POS terminal",
          "quantity": 10,
          "uom": "H87",
          "unit_price": 100.00,
          "vat_category": "S",
          "vat_percentage": 5,
          "allowance_charges": [
            {
              "charge_indicator": false,
              "reason": "Launch promo",
              "amount": 20.00
            }
          ]
        }
      ]
    }
  }'

Use Case 14: Installments & Payment Terms

Split the payable amount into scheduled installments instead of a single due date.

Fields involved:

Name
payment_terms[]
Type
array
Description
One entry per installment. When the document has no due_date, every entry must carry an installment_due_date — if money is still owed, you must say when it's due (ibr-127-ae).
Name
payment_terms[].payment_instruction_id
Type
string (optional)
Description
Ties an installment to the payment_means entry with the same payment_instruction_id — e.g. first installment by card, remainder by bank transfer.
Name
invoice_totals.prepaid_amount
Type
number (conditional)
Description
If any payment terms carry a paid amount, the document-level prepaid total must also be present (ibr-093). The amount due = total incl. tax − prepaid + rounding (ibr-co-16).

Installments

POST

/v3/{participant_id}/documents

curl --request POST \
  --url https://sb-ae-api.flick.network/v3/{participant_id}/documents \
  --header 'X-Flick-Auth-Key: {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "document": {
      "document_identifier": "INV-0195/2026",
      "issue_date": "2026-07-24",
      "document_type": "380",
      "document_currency": "AED",
      "receiving_party": {
        "legal_name": "Gulf Retail Trading LLC",
        "peppol_id": "0235:112345679000003",
        "vat_number": "112345679000003",
        "street_address": "Khalifa Street 12",
        "city_address": "Abu Dhabi",
        "emirates_code": "AUH",
        "country_code": "AE"
      },
      "payment_means": [
        {
          "type_code": "30",
          "payment_instruction_id": "PMI-001",
          "payment_account_id": "AE070331234567890123456"
        }
      ],
      "payment_terms": [
        {
          "payment_instruction_id": "PMI-001",
          "note": "50% on delivery",
          "amount": 525.00,
          "installment_due_date": "2026-08-01"
        },
        {
          "payment_instruction_id": "PMI-001",
          "note": "50% after 60 days",
          "amount": 525.00,
          "installment_due_date": "2026-09-30"
        }
      ],
      "invoice_lines": [
        {
          "id": "1",
          "name": "Smart POS Terminal X9",
          "description": "Handheld smart POS terminal, dual-SIM, 256GB",
          "quantity": 10,
          "uom": "H87",
          "unit_price": 100.00,
          "vat_category": "S",
          "vat_percentage": 5
        }
      ]
    }
  }'

Use Case 15: Attachments & References

Attach supporting files (timesheets, delivery notes, contracts) and reference business documents.

Fields involved:

Name
additional_document_references[]
Type
array
Description
Each reference needs a document_identifier (ibr-052). For an embedded file, the attachment must declare its MIME type (ibr-074) from the allowed subset — pdf, png, jpeg, csv, xlsx, ods (ibr-cl-24) — and its filename (ibr-075). For an invoiced object, set document_type_code: "130" + a scheme_id; only one such reference is allowed (ibr-078), and it can't double as an attachment (ibr-071) or carry a description (ibr-072).
Name
order_reference / other_references
Type
objects (optional)
Description
Purchase / sales order (IBT-013/014), despatch and receiving advice (document level or per line, not both — ibr-092), contract with AE contract value, customs declaration reference, and a single project reference (ibr-090).

Attachments & References

POST

/v3/{participant_id}/documents

curl --request POST \
  --url https://sb-ae-api.flick.network/v3/{participant_id}/documents \
  --header 'X-Flick-Auth-Key: {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "document": {
      "document_identifier": "INV-0201/2026",
      "issue_date": "2026-07-24",
      "due_date": "2026-08-23",
      "document_type": "380",
      "document_currency": "AED",
      "order_reference": {
        "purchase_order_id": "PO-88951",
        "sales_order_id": "SO-55673"
      },
      "other_references": {
        "contract_document_reference": {
          "id": "CTR-2026-009",
          "contract_value": "AED 200000"
        },
        "project_reference": "PRJ-BURJ-PHASE2"
      },
      "additional_document_references": [
        {
          "document_identifier": "OBJ-7714",
          "document_type_code": "130",
          "scheme_id": "ON"
        },
        {
          "document_identifier": "TS-JULY-2026",
          "document_description": "Signed timesheet for July",
          "embedded_document": {
            "mime_code": "application/pdf",
            "filename": "timesheet-july.pdf",
            "content": "JVBERi0xLjcKJc..."
          }
        }
      ],
      "receiving_party": {
        "legal_name": "Gulf Retail Trading LLC",
        "peppol_id": "0235:112345679000003",
        "vat_number": "112345679000003",
        "street_address": "Khalifa Street 12",
        "city_address": "Abu Dhabi",
        "emirates_code": "AUH",
        "country_code": "AE"
      },
      "payment_means": [
        { "type_code": "30", "payment_account_id": "AE070331234567890123456" }
      ],
      "invoice_lines": [
        {
          "id": "1",
          "name": "Site engineering services",
          "description": "On-site engineering support, July 2026 (see attached timesheet)",
          "quantity": 20,
          "uom": "DAY",
          "unit_price": 900.00,
          "vat_category": "S",
          "vat_percentage": 5
        }
      ]
    }
  }'

Code Lists

The short lists you will use on every document are reproduced below. The longer ones are linked to the official PINT AE 1.0.4 specification pages.

Emirates Codes

Used in every emirates_code field. For any UAE address, the country subdivision must be one of these 7 codes (ibr-128-ae):

Code	Emirate
`AUH`	Abu Dhabi
`DXB`	Dubai
`SHJ`	Sharjah
`AJM`	Ajman
`UAQ`	Umm Al Quwain
`RAK`	Ras Al Khaimah
`FUJ`	Fujairah

VAT Category Codes

Used in vat_category on lines, allowances/charges and the VAT breakdown (ibr-139-ae):

Code	Category	Plain-language rule (reference)
`S`	Standard rate	The UAE standard rate is 5% — the rate must be exactly `5` (`ibr-190-ae`)
`Z`	Zero rated	Rate must be exactly `0` (`aligned-ibrp-z-05`)
`E`	Exempt from tax	No rate at all (`aligned-ibrp-e-05`); needs an exemption reason code (`ibr-167-ae`)
`O`	Out of scope / not subject to VAT	No rate at all (`aligned-ibrp-o-05`)
`AE`	VAT reverse charge	Rate stated, VAT amount `0` — the buyer accounts for the tax (`aligned-ibrp-ae-09-ae`)
`N`	Margin scheme (standard rate additional VAT)	Must not be 0% (`ibr-111-ae`); breakdown row shows `0` VAT (`ibr-108-ae`)

Document Type Codes

Code	Document
`380`	Tax Invoice (self-billed when `flags.is_selfbilled` is `true`)
`381`	Tax Credit Note (self-billed when `flags.is_selfbilled` is `true`)
`480`	Out-of-scope Invoice
`81`	Out-of-scope Credit Note

Credit Note Reason Codes

Used in credit_note_reason_code (ibr-001-ae), per Article 61(1) of the VAT Executive Regulation:

Code	Meaning
`DL8.61.1.A`	The supply was cancelled
`DL8.61.1.B`	The tax treatment changed due to a change in the nature of the supply
`DL8.61.1.C`	The previously agreed consideration was altered (e.g. bad debt relief)
`DL8.61.1.D`	Goods or services were returned, in full or in part, and the consideration was refunded
`DL8.61.1.E`	Tax was charged, or tax treatment applied, in error
`VD`	Volume discount (no reference to a single original invoice required)

Payment Means Type Codes

The UAE subset of UNCL4461, used in payment_means[].type_code (ibr-cl-16):

Code	Payment method
`1`	Instrument not defined
`10`	In cash
`20`	Cheque
`21`	Banker's draft
`30`	Credit transfer (requires `payment_account_id` — `ibr-192-ae`)
`49`	Direct debit
`54`	Credit card
`55`	Debit card
`68`	Online payment service

Item Type Codes

Used in invoice_lines[].commodity_code:

Code	Item type	What it requires (reference)
`G`	Goods	HS code (`ibr-184-ae`)
`S`	Services	SAC code (`ibr-185-ae`)
`B`	Both	HS code and SAC code (`ibr-186-ae`)

Registered Identifier Types

Used as keys in the identifiers map (seller: ibr-173-ae, buyer: ibr-183-ae):

Key	Identifier
`TL`	Commercial / Trade license (requires `authority_name`)
`CL`	Commercial license (buyer only)
`EID`	Emirates ID
`PAS`	Passport (requires issuing country)
`CD`	Cabinet decision number

Longer Lists (official references)

List	Used in	Official reference
Unit of measure codes (UN/ECE Rec 20 + 21)	`invoice_lines[].uom`	UNECERec20
Reasons for exemption from tax	`vat_exemption_reason_code`	Tax exemption codes
Type of goods/services subject to RCM	`reverse_charge_item_type`	GoodsType
Electronic Address Schemes (EAS)	`peppol_id` prefix	EAS
ISO 6523 ICD schemes	identifier `scheme_id` fields	ICD
Country codes (ISO 3166-1)	all `country_code` fields	ISO3166
Currency codes (ISO 4217)	`document_currency`	ISO4217
Allowance reason codes (UNCL5189)	allowance `reason_code`	UNCL5189
Charge reason codes (UNCL7161)	charge `reason_code`	UNCL7161
Frequency of billing codes	`invoice_period.description_code`	FreqBilling
Invoiced object identifier schemes (UNCL1153)	`scheme_id` / `object_id_scheme`	UNCL1153
Media types for attachments (PINT subset)	`embedded_document.mime_code`	MimeCode
Transaction type code positions	`flags` → BTAE-02	TransactionType

For the complete semantic model, syntax bindings and every schematron rule, see the official PINT AE Billing 1.0.4 documentation (Invoice and Credit Note transactions, code lists, rules and schematrons).

E-Invoicing for UAE (United Arab Emirates) API References

Introduction

Document Types

Transaction Flags

Common Structs

1. Seller issuing_party

2. Buyer receiving_party

3. Registered Identifiers identifiers

4. Payment Means payment_means[]

5. Payment Terms payment_terms[]

6. Line Items invoice_lines[]

7. Discounts & Charges allowance_charge[]

8. Preceding Invoice References document_references[]

9. Supporting Documents additional_document_references[]

10. Invoicing Period invoice_period

11. Order & Other References order_reference / other_references

12. Payee payee_party

13. Tax Representative tax_representative

14. Delivery delivery

15. VAT Breakdown vat_totals[]

16. Document Totals invoice_totals

Issue a Document

Path Parameters

Headers

Request Body

Minimal Payload

Sample Response

Validation Error

Get a Document

Path Parameters

Response Fields

Sample Request

Sample Response

Download UBL XML

Path Parameters

Sample Request

Sample Response

More Use Cases

Use Case 1: Credit Note

Credit Note

Use Case 2: Self-Billed Invoice

Self-Billed Invoice

Use Case 3: Self-Billed Credit Note

Self-Billed Credit Note

Use Case 4: Foreign-Currency Invoice

USD Invoice

Use Case 5: Free-Trade-Zone Supply

FTZ Supply

Use Case 6: Reverse-Charge Supply

Reverse Charge

Use Case 7: Exempt Supply

Exempt Supply

Use Case 8: Zero-Rated & Export Supply

Export Invoice

Use Case 9: Summary Invoice

Summary Invoice

Use Case 10: E-Commerce Supply

E-Commerce

Use Case 11: Disclosed Agent Billing

Disclosed Agent

Use Case 12: Margin Scheme

Margin Scheme

Use Case 13: Discounts & Charges

Discounts & Charges

Use Case 14: Installments & Payment Terms

Installments

Use Case 15: Attachments & References

Attachments & References

Code Lists

Emirates Codes

VAT Category Codes

Document Type Codes

Credit Note Reason Codes

Payment Means Type Codes

Item Type Codes

Registered Identifier Types

Longer Lists (official references)

1. Seller `issuing_party`

2. Buyer `receiving_party`

3. Registered Identifiers `identifiers`

4. Payment Means `payment_means[]`

5. Payment Terms `payment_terms[]`

6. Line Items `invoice_lines[]`

7. Discounts & Charges `allowance_charge[]`

8. Preceding Invoice References `document_references[]`

9. Supporting Documents `additional_document_references[]`

10. Invoicing Period `invoice_period`

11. Order & Other References `order_reference` / `other_references`

12. Payee `payee_party`

13. Tax Representative `tax_representative`

14. Delivery `delivery`

15. VAT Breakdown `vat_totals[]`

16. Document Totals `invoice_totals`