Skip to main content

Exports

Export invoices — which zero-rating code​

An export invoice has the export flag in its BTOM-001 transaction type. When you send invoice data, that means om_invoice_kind includes export, and delivery_country gives the deliver-to country. A standard-rated export line (category S) needs no reason code. A zero-rated export line (category Z) needs an export code:

CodeUse it forAlso needed on the invoice
VATZR-OM-10Direct export of goods—
VATZR-OM-11Indirect export of goods—
VATZR-OM-12Re-export of goodsThe supporting document's reference and its UUID (IBR-013-OM), both of them: supporting_document_id and supporting_document_uuid. See Zero-rated export lines, and a re-export's supporting document. Neither Odoo nor Zoho Books has a field for them, so a re-export from either connector is parked with a message telling you to send it through the invoice API or a CSV import instead.
VATZR-OM-09Export of serviceservice_type_code on the line, an 8-digit code from CL-12-OM (IBR-155-OM), and a deliver-to country other than OM (IBR-012-OM): delivery_country, or the buyer's address country when delivery_country is not set.
VATZR-OM-04International and intra-GCC transport of goods or passengers—
VATZR-OM-05Services related to international and intra-GCC transport of goods or passengers—

On an export, GoRoute does not choose a code for you. In particular it never fills in VATZR-OM-01, which means qualifying food, not "export". A zero-rated export line with no code, or with a code that does not describe an export, is refused before anything is sent:

  • POST /api/v1/invoices answers with status: "validation_failed" and an error with code BUS_024, whose field points at the line (lines[n].tax_exemption_reason_code, or lines[n].service_type_code / delivery_country for VATZR-OM-09).
  • POST /api/v1/invoices/validate and POST /api/v1/invoices/preview-xml report the same error, so you can check before sending.
  • In a CSV import, that row is not sent and the import job lists it as an error, with the same explanation.
  • An invoice pulled from Odoo or Zoho Books with the same problem is parked, with the reason.

The four export codes need an export. VATZR-OM-09, -10, -11 and -12 describe nothing but an export, so a zero-rated line carrying one of them on a document that is not marked as an export is refused too — until now it was filed with the Tax Authority as a domestic supply zero-rated as an export, and no Schematron rule caught it. GoRoute does not decide for you which of the two is wrong, even when the buyer is abroad: you either add export to om_invoice_kind (a CSV or Excel import has the same om_invoice_kind column), or give the line the code of the domestic zero-rating. The international-transport codes VATZR-OM-04 and -05 stay allowed on a domestic document.

  • POST /api/v1/invoices, /validate and /preview-xml answer with validation error BUS_029, whose field is the line's lines[n].tax_exemption_reason_code. When the buyer's address is outside Oman, the message says so.
  • A CSV or Excel import rejects the row with the same sentence.
  • A credit note is held to the same rule. So is a document declared through another kind that cannot be an export (for example simplified or summary).
  • The Odoo and Zoho Books connectors mark the export themselves from the customer's country, so for them this means a customer in Oman, or with no country, whose line carries one of the four codes. That invoice is parked, with the remedy in the ERP's terms: set the customer's country if it is abroad, or use a domestic code.

If your invoices come from Odoo or Zoho Books, the code has to reach the invoice through the connector. How to do that, and what happens to an invoice that has no code, is on Connectors.

Zero-rated export lines, and a re-export's supporting document​

On an export (om_invoice_kind includes export, so BTOM-001 position 7 is set) a zero-rated line must say why it is zero-rated with an export code: VATZR-OM-10 direct export of goods, VATZR-OM-11 indirect export of goods, VATZR-OM-12 re-export of goods, VATZR-OM-09 export of service, or VATZR-OM-04 / VATZR-OM-05 international transport. GoRoute does not fill one in for you. A standard-rated export line needs no code.

A re-export of goods (VATZR-OM-12) must also reference its supporting document — its reference (IBT-122) and its UUID (BTOM-023). This is the fatal rule IBR-013-OM. Give both on the invoice, once per document:

Invoice API field / CSV columnOn the e-invoice
supporting_document_idcac:AdditionalDocumentReference/cbc:ID (IBT-122)
supporting_document_uuidcac:AdditionalDocumentReference/cbc:UUID (BTOM-023)
{
  "invoice": {
    "document_type": "invoice",
    "om_invoice_kind": "export",
    "number": "OM-EXP-2026-0042",
    "supporting_document_id": "BOE-2026-0042",
    "supporting_document_uuid": "f12f329f-6430-4399-b661-7c5cd9c3a9e6",
    "lines": [
      {
        "description": "Re-exported pumps",
        "quantity": 2,
        "unit_price": 500,
        "tax_category": "zero",
        "tax_rate": 0,
        "tax_exemption_reason_code": "VATZR-OM-12"
      }
    ]
  }
}

(Seller, buyer and totals are left out of the example.) GoRoute writes the two values as one cac:AdditionalDocumentReference with no cbc:DocumentTypeCode, as in the Tax Authority's own export sample.

Check that your reference actually reaches the e-invoice

Before you rely on this for a real re-export, send the invoice to POST /api/v1/invoices/preview-xml and look in the XML that comes back for a cac:AdditionalDocumentReference whose cbc:ID is your supporting document's reference.

If it is there, you are ready to file. If it is not there, do not file the re-export: the service you are talking to does not yet accept these two fields, and it will not tell you so — a field it does not recognise is ignored rather than refused, so the invoice would be filed without the reference IBR-013-OM requires. Please tell us if that happens — see Support — and we will get the service brought current.

If either value is missing, POST /api/v1/invoices, POST /api/v1/invoices/validate and POST /api/v1/invoices/preview-xml answer with validation error BUS_024, and its field names the one to fill — supporting_document_id, or supporting_document_uuid when only the UUID is missing; the message names every one that is empty. Nothing is rendered or sent. A CSV or Excel import rejects the row with the same sentence.

supporting_document_id cannot be QR or HASH (in any case, with or without spaces), on any Oman document: GoRoute writes the invoice's QR code, and its hash, as cac:AdditionalDocumentReference elements with those IDs. Such a value is refused with validation error BUS_025 against supporting_document_id, and a CSV or Excel import rejects the row.

supporting_document_uuid must be a UUID written in the usual form: 32 hexadecimal digits in groups of 8-4-4-4-12, for example f12f329f-6430-4399-b661-7c5cd9c3a9e6. Upper or lower case is accepted, and so is any UUID version. Any other value is refused with validation error BUS_026 against supporting_document_uuid, and a CSV or Excel import rejects the row. That includes the sample in the Tax Authority's data dictionary, which has only seven digits in its first group.

When the buyer takes only BIS Billing 3.0 and receives a BIS 3.0 copy, that copy carries the same reference: IBT-122 as cbc:ID, with the UUID written in cbc:DocumentDescription. BIS 3.0 does not allow a cbc:UUID element there.

A credit note that GoRoute creates from an invoice (POST /api/v1/invoices/credit-note) copies several fields from the invoice: om_invoice_kind, the supporting document, and the details that the invoice's kind requires (the deliver-to country, the import customs details, the invoicing period, the prepayment reference and the third party). So a credit note of an export is also an export. These fields are copied only when the seller or the buyer is in Oman; a credit note of any other country's invoice is built exactly as before.

The Odoo and Zoho Books connectors mark an Omani seller's invoice as an export whenever the customer's country is outside Oman, the other GCC states included. A customer with an Omani VAT number (OM…) and a country outside Oman is parked instead, because the two disagree. So is an Odoo customer whose country code is not an ISO 3166-1 code, since GoRoute cannot tell whether it is abroad. Neither ERP has a field for the supporting document, so a re-export (VATZR-OM-12) from either is parked with a message that says to send it through the invoice API or CSV import instead. See Connectors.

Validate before you send

POST /api/v1/invoices/validate/deep runs the full PINT OM 1.0.1 Schematron and returns every rule that fired, by identifier. Cheaper than a rejection, and the free sandbox is provisioned within 24 hours.

Last updated on