Special scenarios

Read this page when your app builds a document for a special type of sale, or gets an error about transaction_type_code. For the steps to submit a document, refer to Submit a document.

This page uses these terms:

Taxpayer: a business from which your organization has an active grant. On each document that your app submits, the taxpayer is the seller.
Buyer: the business that receives the document.
Document: an invoice or a credit note.
FTA: the UAE Federal Tax Authority. Wafeq ASP reports each document to the FTA.
Peppol: the network on which businesses exchange e-invoices. Each business connects to Peppol through an e-invoicing provider.
Peppol ID: the address of a business on Peppol. For a UAE business, it is 0235: followed by the TIN of the business. A business outside the UAE uses the scheme of its country.
TIN: the 10-digit number that the FTA gives a business.
TRN: the VAT registration number of a business: 15 digits, ending in 03.
VAT category and VAT rate: the details on each line that tell how VAT applies to the line, in tax_category and tax_percent.
FTA placeholder address: an address that Wafeq ASP uses instead of the Peppol ID of the buyer. Wafeq ASP uses it when it reports a document to the FTA only, and does not deliver the document to the buyer.
Special scenario: a type of sale that the UAE rules mark in the document. Some special scenarios need more fields in the request.
Flag: one character of transaction_type_code. The value is 1 when the special scenario applies, and 0 when it does not apply.
Commercial invoice and commercial credit note: a document outside the scope of VAT, with the type 480 or 81. Refer to Document types.
Self-billed document: an invoice or a credit note that the buyer issues, under a self-billing agreement with the seller.

Example. A company in Dubai sells spare parts on its website. A company in the United Kingdom orders parts on the website. The seller ships the parts to London. This sale is an e-commerce sale and an export. Thus the invoice has two flags: 00000011.

A document can be a special scenario. Your app tells Wafeq ASP which special scenarios apply, in transaction_type_code. Wafeq ASP puts the flags in the document. Some flags need more fields in the request. For some flags, Wafeq ASP routes the document in a different way.

Invoices and credit notes use transaction_type_code in the same way. The flags do not change the VAT category or the VAT rate of the lines. Your user decides them. The margin scheme is the only exception: it needs the category N on each line. Refer to VAT on each line.

The format of `transaction_type_code`

transaction_type_code has 8 characters. Each character is 0 or 1. Each position is one special scenario, from left to right:

Position	Special scenario
1	Free zone
2	Deemed supply
3	Margin scheme
4	Summary invoice
5	Continuous supply
6	Disclosed agent billing
7	E-commerce
8	Exports

To set a flag, put 1 at its position. For example, 00010000 is a summary invoice. The default value is 00000000: no special scenario. Wafeq ASP refuses a value that is not 8 characters of 0 and 1, with 422.

A document can have more than one flag. For example, 00000011 is an e-commerce sale that is also an export. The last example on this page shows it.

The check (POST /invoices/validate) gives the flags of the document in profile_execution_id.

The sections below tell you how to use each special scenario, in the order of the positions.

Free zone (position 1)

Example. A company in a Dubai free zone sells 10 forklifts to a food distributor in Dubai. The distributor uses the forklifts in its own warehouse. Thus the distributor is the buyer and also the beneficiary.

When it applies. The sale involves a business in a UAE free zone. Or the supply takes place in a free zone, or from a free zone. The business in the free zone can be the seller, the buyer or the beneficiary. The beneficiary is the business that finally uses, consumes or owns the goods or services. Usually, the beneficiary is the buyer. Your user decides if a sale is a free zone sale.

What the request must contain.

transaction_type_code with 1 at position 1, for example 10000000.
beneficiary.identifier: an identifier of the beneficiary, for example its VAT TRN. If the buyer is the beneficiary, send the identifier of the buyer again. Wafeq ASP does not copy it from customer.
Without beneficiary, Wafeq ASP refuses the request with 422. Wafeq ASP also refuses beneficiary on a document without the free zone flag.

What Wafeq ASP does. Wafeq ASP puts the identifier of the beneficiary in the document. Then it delivers and reports the document in the same way as a document without flags.

Example:

{
  "invoice_number": "INV-2026-0310",
  "issue_date": "2026-10-15",
  "due_date": "2026-11-14",
  "source_id": "erp-invoice-9310",
  "transaction_type_code": "10000000",
  "customer": {
    "id": "0235:1999200000",
    "name": "Gulf Fresh Foods LLC",
    "vat_number": "199920000000003",
    "address": { "street": "Warehouse 7, Al Quoz Industrial 3", "city": "Dubai", "country": "AE", "country_subentity": "DXB" }
  },
  "beneficiary": { "identifier": "199920000000003" },
  "line_items": [
    { "description": "Forklift, 2.5 tonnes", "quantity": 10, "unit_price": 48000, "tax_category": "S", "tax_percent": 5 }
  ]
}

Deemed supply (position 2)

Example. A furniture trader gives 20 office chairs to a business customer, as a free gift. The trader gets no payment. VAT treats the gift as a sale.

When it applies. The seller supplies goods or services without payment, and VAT treats this as a supply. Your user decides if a sale is a deemed supply.

What the request must contain.

transaction_type_code with 1 at position 2, for example 01000000.
A type that is not 480 or 81. Wafeq ASP refuses a commercial invoice or a commercial credit note with this flag (transaction_flags_not_allowed).
customer.id is optional. If you do not send the TIN of the buyer in customer.id, send customer.vat_number or customer.identifier.

What Wafeq ASP does.

Wafeq ASP does not deliver the document to the buyer. It reports the document to the FTA only, with the FTA placeholder address 0235:9900000097.
Wafeq ASP does this also when the buyer is on Peppol, and also when the document has the export flag.
If you send the TIN of the buyer in customer.id, Wafeq ASP keeps the TIN in the document as the identifier of the buyer.
The check gives route: reporting_only and effective_recipient_id: 0235:9900000097.
The submission needs an Idempotency-Key header. Wafeq ASP answers 202, with status: reporting_only.

A self-billed document cannot be a deemed supply. Wafeq ASP refuses it with 422.

Example:

{
  "invoice_number": "INV-2026-0304",
  "issue_date": "2026-10-15",
  "due_date": "2026-10-15",
  "source_id": "erp-invoice-9304",
  "transaction_type_code": "01000000",
  "customer": {
    "id": "0235:1999200000",
    "name": "Gulf Fresh Foods LLC",
    "vat_number": "199920000000003",
    "address": { "street": "Warehouse 7, Al Quoz Industrial 3", "city": "Dubai", "country": "AE", "country_subentity": "DXB" }
  },
  "line_items": [
    { "description": "Office chairs, free gift", "quantity": 20, "unit_price": 450, "tax_category": "S", "tax_percent": 5 }
  ]
}

Margin scheme (position 3)

Example. A dealer in used vehicles buys a used delivery van from a private person. The dealer sells the van to a company for AED 52,500, under the profit margin scheme. The invoice shows AED 52,500 and no VAT.

When it applies. The seller sells goods under the profit margin scheme of the UAE VAT law. With this scheme, the seller pays VAT on its profit margin, not on the full price. The document does not show this VAT. Your user decides if a sale uses the margin scheme.

What the request must contain.

transaction_type_code with 1 at position 3, for example 00100000.
On each line, tax_category: "N" and tax_percent: 5. N is the VAT category "standard rate additional VAT". It tells the FTA that VAT applies outside the document. Each line must have this category. A document with this flag cannot have lines with other categories.
unit_price: the price that the buyer pays. Wafeq ASP adds no VAT to it.
The taxpayer must have a VAT TRN. For a taxpayer without a VAT TRN, Wafeq ASP refuses the document with seller_without_trn_taxable_lines.
Wafeq ASP refuses the category N on a document without the margin scheme flag, with 422.

What Wafeq ASP does.

Wafeq ASP calculates no VAT on a line with the category N. The VAT amount of each line and of the document is 0. The total of the document is the sum of the lines.
The document cannot be a commercial invoice (480) or a commercial credit note (81).
Then Wafeq ASP delivers and reports the document in the same way as a document without flags.

Example:

{
  "invoice_number": "INV-2026-0330",
  "issue_date": "2026-10-15",
  "due_date": "2026-11-14",
  "source_id": "erp-invoice-9330",
  "transaction_type_code": "00100000",
  "customer": {
    "id": "0235:1999200000",
    "name": "Gulf Fresh Foods LLC",
    "vat_number": "199920000000003",
    "address": { "street": "Warehouse 7, Al Quoz Industrial 3", "city": "Dubai", "country": "AE", "country_subentity": "DXB" }
  },
  "line_items": [
    { "description": "Used delivery van, 2021", "quantity": 1, "unit_price": 52500, "tax_category": "N", "tax_percent": 5 }
  ]
}

Summary invoice (position 4)

Example. A fuel supplier delivers diesel to a construction company 12 times in September. At the start of October, the supplier issues one tax invoice for the 12 deliveries.

When it applies. The seller makes more than one supply to the same buyer in the same calendar month. The seller issues one tax invoice for all of these supplies.

What the request must contain.

transaction_type_code with 1 at position 4, for example 00010000.
invoice_period, with start_date and end_date in the format YYYY-MM-DD. The start date cannot be after the end date. Without invoice_period, Wafeq ASP refuses the request with 422.
A type that is not 480 or 81. Wafeq ASP refuses a commercial invoice or a commercial credit note with this flag (transaction_flags_not_allowed).

What Wafeq ASP does. Wafeq ASP puts the period in the document. Then it delivers and reports the document in the same way as a document without flags.

Example:

{
  "invoice_number": "INV-2026-0305",
  "issue_date": "2026-10-01",
  "due_date": "2026-10-31",
  "source_id": "erp-invoice-9305",
  "transaction_type_code": "00010000",
  "invoice_period": { "start_date": "2026-09-01", "end_date": "2026-09-30" },
  "customer": {
    "id": "0235:1999200000",
    "name": "Gulf Fresh Foods LLC",
    "vat_number": "199920000000003",
    "address": { "street": "Warehouse 7, Al Quoz Industrial 3", "city": "Dubai", "country": "AE", "country_subentity": "DXB" }
  },
  "line_items": [
    { "description": "Diesel delivery, 1,000 litres", "quantity": 12, "unit_price": 3100, "tax_category": "S", "tax_percent": 5 }
  ]
}

Continuous supply (position 5)

Example. A cleaning company cleans the offices of a client under a 12-month contract. The cleaning company issues a tax invoice each month.

When it applies. The seller supplies goods or services again and again, under one agreement.

What the request must contain.

transaction_type_code with 1 at position 5, for example 00001000.
No other field is necessary. You can send invoice_period to show the period that the document covers.

What Wafeq ASP does. Wafeq ASP delivers and reports the document in the same way as a document without flags.

Example:

{
  "invoice_number": "INV-2026-0306",
  "issue_date": "2026-10-01",
  "due_date": "2026-10-31",
  "source_id": "erp-invoice-9306",
  "transaction_type_code": "00001000",
  "invoice_period": { "start_date": "2026-10-01", "end_date": "2026-10-31" },
  "customer": {
    "id": "0235:1999200000",
    "name": "Gulf Fresh Foods LLC",
    "vat_number": "199920000000003",
    "address": { "street": "Warehouse 7, Al Quoz Industrial 3", "city": "Dubai", "country": "AE", "country_subentity": "DXB" }
  },
  "line_items": [
    { "description": "Office cleaning, October", "quantity": 1, "unit_price": 6000, "tax_category": "S", "tax_percent": 5 }
  ]
}

Disclosed agent billing (position 6)

Example. A sales agent in Dubai sells pumps for a manufacturer in Sharjah. The agent tells the buyer that the pumps come from the manufacturer. The agent issues the tax invoice to the buyer. The invoice names the manufacturer as the principal.

When it applies. The taxpayer is an agent. It sells goods or services for another business, the principal, and it tells the buyer the name of the principal. The taxpayer issues the document. Your user decides if a sale is disclosed agent billing.

What the request must contain.

transaction_type_code with 1 at position 6, for example 00000100.
principal.vat_number: the VAT TRN of the principal. A VAT TRN has 15 digits, starts with 1 and ends in 03.
The principal cannot be the taxpayer. If principal.vat_number is the VAT TRN of the taxpayer, the check gives the error SCH:ibr-176-ae. If the taxpayer sells for itself, the flag does not apply.
Without principal, Wafeq ASP refuses the request with 422. Wafeq ASP also refuses principal on a document without the disclosed agent billing flag.

What Wafeq ASP does. Wafeq ASP puts the VAT TRN of the principal in the document. Then it delivers and reports the document in the same way as a document without flags.

Example:

{
  "invoice_number": "INV-2026-0320",
  "issue_date": "2026-10-15",
  "due_date": "2026-11-14",
  "source_id": "erp-invoice-9320",
  "transaction_type_code": "00000100",
  "customer": {
    "id": "0235:1999200000",
    "name": "Gulf Fresh Foods LLC",
    "vat_number": "199920000000003",
    "address": { "street": "Warehouse 7, Al Quoz Industrial 3", "city": "Dubai", "country": "AE", "country_subentity": "DXB" }
  },
  "principal": { "vat_number": "199999999900003" },
  "line_items": [
    { "description": "Centrifugal pump", "quantity": 4, "unit_price": 6500, "tax_category": "S", "tax_percent": 5 }
  ]
}

E-commerce (position 7)

Example. An office supplies company sells printer paper on its website. A business buyer orders the paper on the website. The seller delivers the paper to the warehouse of the buyer.

When it applies. The seller supplies goods or services through e-commerce, for example through a website or an app.

What the request must contain.

transaction_type_code with 1 at position 7, for example 00000010.
delivery_address: the place where the seller delivers the goods or services. It needs street, city, country_subentity and country. For a UAE address, put the emirate in country_subentity, for example DXB.
Wafeq ASP does not copy the address of the buyer into delivery_address. Send delivery_address also when it is the same as the address of the buyer.
Without delivery_address, the check gives the error SCH:ibr-142-ae.

What Wafeq ASP does. Wafeq ASP puts the delivery address in the document. Then it delivers and reports the document in the same way as a document without flags.

Example:

{
  "invoice_number": "INV-2026-0307",
  "issue_date": "2026-10-15",
  "due_date": "2026-11-14",
  "source_id": "erp-invoice-9307",
  "transaction_type_code": "00000010",
  "customer": {
    "id": "0235:1999200000",
    "name": "Gulf Fresh Foods LLC",
    "vat_number": "199920000000003",
    "address": { "street": "Office 402, Al Quoz Business Centre", "city": "Dubai", "country": "AE", "country_subentity": "DXB" }
  },
  "delivery_address": { "street": "Warehouse 7, Al Quoz Industrial 3", "city": "Dubai", "country": "AE", "country_subentity": "DXB" },
  "line_items": [
    { "description": "Printer paper A4, box of 5 reams", "quantity": 40, "unit_price": 95, "tax_category": "S", "tax_percent": 5 }
  ]
}

Exports (position 8)

Example. A company in Dubai sells pump parts to a company in the United Kingdom. The seller ships the parts to the buyer in Manchester. The buyer has no Peppol ID.

When it applies. The seller supplies goods or services to a place outside the UAE. This applies to services also.

What the request must contain.

transaction_type_code with 1 at position 8, for example 00000001.
customer.name, and customer.address with street, city, country_subentity and country. Send the real country of the buyer. The default value of country is AE.
delivery_address, with street, city, country_subentity and country. The country cannot be AE. Wafeq ASP does not copy the address of the buyer into delivery_address.
customer.id: the Peppol ID of the buyer, if the buyer has one. Use the scheme of the country of the buyer. If the buyer has no Peppol ID, do not send customer.id.
For an export, customer.vat_number and customer.identifier are not necessary.

What Wafeq ASP does.

You send customer.id, and the buyer is on Peppol. Wafeq ASP delivers the document to the provider of the buyer. It also reports the document to the FTA.
You send customer.id, and the buyer is not on Peppol. Wafeq ASP reports the document to the FTA only. It uses the FTA placeholder address 0235:9900000099.
You do not send customer.id. Wafeq ASP reports the document to the FTA only. It uses the FTA placeholder address 0235:9900000099. It does not look for the buyer on Peppol.
Wafeq ASP cannot look for the buyer at this time. Wafeq ASP refuses the submission with 503 smp_unavailable. It keeps nothing. Send the same request again later, with the same Idempotency-Key.

When Wafeq ASP reports the document to the FTA only, the submission needs an Idempotency-Key header. Wafeq ASP answers 202, with status: reporting_only.

A document without the export flag is not an export, also when the buyer is outside the UAE. Wafeq ASP routes it as any other document, with 0235:9900000098 when it cannot deliver it. Refer to Who receives the document.

Example:

{
  "invoice_number": "INV-2026-0308",
  "issue_date": "2026-10-15",
  "due_date": "2026-11-14",
  "source_id": "erp-invoice-9308",
  "transaction_type_code": "00000001",
  "customer": {
    "name": "Northern Pump Works Ltd",
    "address": { "street": "14 Trafford Park Road", "city": "Manchester", "country": "GB", "country_subentity": "Greater Manchester" }
  },
  "delivery_address": { "street": "14 Trafford Park Road", "city": "Manchester", "country": "GB", "country_subentity": "Greater Manchester" },
  "line_items": [
    { "description": "Hydraulic pump spare parts", "quantity": 4, "unit_price": 2750, "tax_category": "Z", "tax_percent": 0 }
  ]
}

Example with two flags: e-commerce and export. A company in Dubai sells spare parts on its website. A company in the United Kingdom orders parts on the website. The seller ships the parts to London. The invoice has the flags at positions 7 and 8: 00000011. It needs the fields of both scenarios:

{
  "invoice_number": "INV-2026-0309",
  "issue_date": "2026-10-15",
  "due_date": "2026-11-14",
  "source_id": "erp-invoice-9309",
  "transaction_type_code": "00000011",
  "customer": {
    "name": "Thames Marine Supplies Ltd",
    "address": { "street": "8 Canary Wharf Road", "city": "London", "country": "GB", "country_subentity": "Greater London" }
  },
  "delivery_address": { "street": "Unit 3, Royal Docks Trade Park", "city": "London", "country": "GB", "country_subentity": "Greater London" },
  "line_items": [
    { "description": "Marine engine filters", "quantity": 25, "unit_price": 180, "tax_category": "Z", "tax_percent": 0 }
  ]
}

Combinations that Wafeq ASP refuses

Wafeq ASP refuses these combinations:

A commercial invoice or a commercial credit note that is a summary invoice or a deemed supply. Wafeq ASP refuses it with transaction_flags_not_allowed.
A self-billed document that is a deemed supply. Wafeq ASP refuses it with 422.

Common errors

The check gives the SCH: codes and transaction_flags_not_allowed in errors. A submission gives transaction_flags_not_allowed in status, with success: false. For a 422, the response contains one of the messages below.

422: invoice_period is required when the summary-invoice transaction flag is set

Cause: the document has the summary invoice flag, but no invoice_period.
Action: send invoice_period with start_date and end_date.

422: delivery_address is required for exports

Cause: the document has the export flag, but no delivery_address.
Action: send delivery_address with all four fields.

422: Export delivery_address.country must not be AE (IBR-152-AE)

Cause: the document has the export flag, and the delivery address is in the UAE.
Action: send the address outside the UAE where the seller delivers the goods or services. If the delivery is in the UAE, remove the export flag.

422: beneficiary is required when the free-zone transaction flag is set

Cause: the document has the free zone flag, but no beneficiary.
Action: send beneficiary.identifier. If the buyer is the beneficiary, send the identifier of the buyer.

422: line_items[0].tax_category must be N when the margin-scheme transaction flag is set

Cause: the document has the margin scheme flag, and a line has a different VAT category. The number in brackets is the position of the line, from 0.
Action: give each line the category N. If the sale does not use the margin scheme, remove the flag.

422: line_items[0].tax_percent must be 5 when tax_category is N

Cause: a line with the category N has a different VAT rate.
Action: send tax_percent: 5.

422: principal is required when the disclosed-agent-billing transaction flag is set

Cause: the document has the disclosed agent billing flag, but no principal.
Action: send principal.vat_number.

422: principal.vat_number must be a TRN: 15 digits, starting with 1 and ending in 03

Cause: the value is not a VAT TRN.
Action: send the VAT TRN of the principal.

422: a field without its flag

Messages: beneficiary is only allowed when the free-zone transaction flag is set, principal is only allowed when the disclosed-agent-billing transaction flag is set and tax_category N is only allowed when the margin-scheme transaction flag is set.
Cause: the document has the field, but not the flag.
Action: set the flag, or remove the field.

SCH:ibr-176-ae

Cause: principal.vat_number is the VAT TRN of the taxpayer.
Action: send the VAT TRN of the principal. If the taxpayer sells for itself, remove the disclosed agent billing flag.

SCH:ibr-142-ae

Cause: the document has the e-commerce flag, but no delivery_address.
Action: send delivery_address.

SCH:ibr-135-ae

Cause: a deemed supply has no TIN of the buyer in customer.id, no customer.vat_number and no customer.identifier.
Action: send customer.identifier, for example the trade licence number of the buyer.

transaction_flags_not_allowed

Cause: the document is a commercial invoice or a commercial credit note, and it has the summary invoice flag or the deemed supply flag.
Action: remove the flag.