KSA v2: Unify API

Send B2B and B2C invoices, credit notes and debit notes to ZATCA with the KSA ZATCA API v2 Unify API, which validates each document, clears or reports it and returns its QR code and PDF. This page documents API v2, a legacy version.

The Unify API combines validation for business-to-business (B2B) and business-to-consumer (B2C) transactions with QR code generation in one API. When a B2C document passes validation, it is reported. When a B2B document passes validation, it is cleared.

After you onboard your EGS, send each document to the Unify API. Use documentType to say what kind of document it is.

Document types

`documentType`	Description
`DOC_B2B_INV`	Business-to-business invoices
`DOC_B2B_CRD`	Business-to-business credit notes
`DOC_B2B_DBT`	Business-to-business debit notes
`DOC_B2C_INV`	Business-to-consumer invoices
`DOC_B2C_CRD`	Business-to-consumer credit notes
`DOC_B2C_DBT`	Business-to-consumer debit notes

After you set documentType, send the request. The response says whether the document was reported or cleared. It also contains the document’s PDF as Base64 data, which you can download.

Endpoint

http

POST https://api.complyance.io/sandbox/v2/unify

Headers

Header	Value
`x-api-key`	Your API key, from API key generation. For example `EXAMPLEapiKEY00000000000000000000000000`.
`Content-Type`	`application/json`
`env`	`sandbox`

Example request

Request bodyjson

{
    "invoiceData": {
        "documentType": "DOC_B2B_INV",
        "referenceId": "",
        "documentIssueDateTime": "2023-10-02T04:33:41.000Z",
        "documentDueDateTime": "2023-10-02T04:33:41.000Z",
        "sellerName": "Acme Trading LLC",
        "sellerNameAr": "شركة أكمي للتجارة",
        "sellerAddress": {
            "addrLine1": "12, Masjid Street",
            "addrLine2": "Building 4",
            "additionalNo": "1234",
            "buildingNumber": "1234",
            "city": "Dammam",
            "state": "Riyadh",
            "zipCode": "12313",
            "district": "Riyadh",
            "country": "SA",
            "addrLine1Ar": "RB2",
            "addrLine2Ar": "Riyadh",
            "additionalNoAr": "1234",
            "buildingNumberAr": "1234",
            "cityAr": "Riyadh",
            "stateAr": "Riyadh",
            "zipCodeAr": "17555",
            "districtAr": "Riyadh",
            "countryAr": "SA"
        },
        "buyerName": "Example Customer LLC",
        "buyerNameAr": "شركة العميل النموذجي",
        "buyerAddress": {
            "addrLine1": "12, Masjid Street",
            "addrLine2": "Building 4",
            "additionalNo": "1234",
            "buildingNumber": "1234",
            "city": "Dammam",
            "state": "Riyadh",
            "zipCode": "12313",
            "district": "Riyadh",
            "country": "SA",
            "addrLine1Ar": "RB2",
            "addrLine2Ar": "Riyadh",
            "additionalNoAr": "1234",
            "buildingNumberAr": "1234",
            "cityAr": "Riyadh",
            "stateAr": "Riyadh",
            "zipCodeAr": "17555",
            "districtAr": "Riyadh",
            "countryAr": "SA"
        },
        "documentLineItems": [
            {
                "lineItemDesc": "LOGISTICS WITH VAT",
                "lineItemPrice": 5,
                "lineItemQty": 1,
                "lineItemTaxableAmount": 5,
                "discountOnLineItem": 0,
                "vatRateOnLineItem": 15,
                "lineItemVatAmount": 0.75,
                "lineItemSubTotal": 5.75,
                "vatCategoryCode": "S"
            },
            {
                "lineItemDesc": "LOGISTICS WITH OUT VAT",
                "lineItemPrice": 5,
                "lineItemQty": 1,
                "lineItemTaxableAmount": 5,
                "discountOnLineItem": 0,
                "vatRateOnLineItem": 0,
                "lineItemVatAmount": 0.0,
                "lineItemSubTotal": 5,
                "vatCategoryCode": "E",
                "vatExemptionReason": "Financial services mentioned in Article 29 of the VAT Regulations",
                "vatExemptionReasonCode": "VATEX-SA-29"
            }
        ],
        "totalExcludingVat": 10,
        "totalTaxableAmountExcludingVat": 5,
        "vatTotal": 0.75,
        "documentTotal": 10.75,
        "discountOnDocumentTotal": 0,
        "isSpecialBillingAgreement": "false",
        "isTransactionType": "false",
        "isSelfBilled": "false",
        "isThirdParty": "false",
        "isNominalSupply": "false",
        "isExport": "false",
        "isSummary": "false",
        "supplyDate": "2022-12-31T04:33:41.000Z",
        "sellerVatRegistrationNumber": "300000000000003",
        "sellerVatRegistrationNumberAr": "300000000000003",
        "sellerGroupVatRegistrationNumber": "",
        "additionalSellerIdType": "CRN",
        "additionalSellerIdNumber": "34523452345234",
        "additionalSellerIdNumberAr": "34523452345234",
        "specialTaxTreatment": "0",
        "additionalBuyerIdType": "CRN",
        "additionalBuyerIdNumber": "12345678",
        "additionalBuyerIdNumberAr": "1980792",
        "currency": "SAR",
        "paymentMeans": "CREDIT",
        "documentId": "i4928428492",
        "documentIdAr": "خمسة"
    }
}

Request parameters

Parameter	Required	Type	Description	Example
`invoiceData`	Yes	object	The data of the document.	`{...}`
`documentType`	Yes	string	The document type. Use one of these values: 1. Business-to-business invoices: `DOC_B2B_INV` 2. Business-to-business credit notes: `DOC_B2B_CRD` 3. Business-to-business debit notes: `DOC_B2B_DBT` 4. Business-to-consumer invoices: `DOC_B2C_INV` 5. Business-to-consumer credit notes: `DOC_B2C_CRD` 6. Business-to-consumer debit notes: `DOC_B2C_DBT`	`DOC_B2B_INV`
`referenceId`	Conditional	string	The ID of the original (reference) document this document is issued for. It applies only to these document types: 1. Tax invoice credit note 2. Tax invoice debit note For example, for a tax credit note, `referenceId` is the number of the invoice the credit note is for.	`2022100627`
`documentIssueDateTime`	Yes	string	The document’s issue date and time, in the format `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`.	`2022-10-21T12:53:13.000Z`
`documentDueDateTime`	No	string	The document’s due date and time, in the format `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`.	`2022-10-21T12:53:13.000Z`
`sellerName`	Yes	string	The seller’s name.	`Company Name`
`sellerNameAr`	Yes	string	The seller’s name in Arabic.	`Company Name`
`sellerAddress`	Yes	object	The seller’s address, with the address fields below.	`{"addrLine1": "Makkah", "addrLine2": "Al Alam Street", "additionalNo": "1234", "buildingNumber": "1234", "city": "Riyadh", "state": "Riyadh", "zipCode": "24211", "district": "Riyadh", "country": "SA"}`
`buyerName`	Yes	string	The buyer’s name. It is mandatory for the transactions in Article 53 (7), and for private education and private healthcare supplied to citizens.
`buyerNameAr`	Yes	string	The buyer’s name in Arabic.
`buyerAddress`	Yes	object	The buyer’s address, with the address fields below.	`{"addrLine1": "Makkah", "addrLine2": "Al Alam Street", "additionalNo": "1234", "buildingNumber": "1234", "city": "Riyadh", "state": "Riyadh", "zipCode": "24211", "district": "Riyadh", "country": "SA"}`
`addrLine1`	Yes	string	Address line 1.	`Makkah`
`addrLine1Ar`	Yes	string	Address line 1 in Arabic.	`Makkah`
`addrLine2`	Yes	string	Address line 2.	`Al Alam Street`
`addrLine2Ar`	Yes	string	Address line 2 in Arabic.	`Al Alam Street`
`buildingNumber`	Yes	string	Building number.	`20211`
`buildingNumberAr`	Yes	string	Building number in Arabic.	`20211`
`additionalNo`	Yes	string	Additional number (4 digits).	`2134`
`additionalNoAr`	Yes	string	Additional number (4 digits) in Arabic.	`2134`
`city`	Yes	string	City.	`Riyadh`
`cityAr`	Yes	string	City in Arabic.	`Riyadh`
`state`	Yes	string	State.	`Riyadh`
`stateAr`	Yes	string	State in Arabic.	`Riyadh`
`zipCode`	Yes	string	Postal code (5 digits).	`24211`
`zipCodeAr`	Yes	string	Postal code (5 digits) in Arabic.	`24211`
`country`	Yes	string	Country code, as a 2-letter code (ISO 3166 Alpha-2).	`SA`
`countryAr`	Yes	string	Country code, as a 2-letter code (ISO 3166 Alpha-2), in Arabic.	`SA`
`documentLineItems`	Yes	array	The list of line items.	`[...]`
`lineItemDesc`	Yes	string	Line item description.	`Ball point pen`
`lineItemPrice`	Yes	number	Line item price.	`10.00`
`lineItemQty`	Yes	number	Line item quantity.
`additionalDiscountAtLineLevel`	Yes	number	A discount amount applied to the line item after `lineItemPrice` is multiplied by `lineItemQty`.	`0`
`lineItemTaxableAmount`	Yes	number	`lineItemTaxableAmount = (lineItemPrice - discountOnLineItem) * lineItemQty`	`100.00`
`discountOnLineItem`	Yes	number	A discount amount applied to `lineItemPrice` before it is multiplied by `lineItemQty`.	`0.00`
`vatRateOnLineItem`	Yes	number	The VAT rate applied to the line item.	`15.00`
`lineItemVatAmount`	Yes	number	The VAT amount of the line item. `lineItemVatAmount = (lineItemTaxableAmount * vatRateOnLineItem) / 100`	`15.00`
`lineItemSubTotal`	Yes	number	The total of the line item. `lineItemSubTotal = lineItemTaxableAmount + lineItemVatAmount`	`115.00`
`totalExcludingVat`	Yes	number	`totalExcludingVat = documentTotal - totalVat`	`100.00`
`totalTaxableAmountExcludingVat`	Yes	number	`totalTaxableAmountExcludingVat` = the sum of `lineItemTaxableAmount` for all line items, minus `discountOnDocumentTotal` if one applies.	`100.00`
`vatTotal`	Yes	number	`vatTotal = totaltaxableexcludingtax - discountondocumenttotal * 15`	`15.00`
`documentTotal`	Yes	number	`documentTotal = totalTaxableAmountExcludingVat - discountOnDocumentTotal + vatTotal`	`115.00`
`discountOnDocumentTotal`	No	number	A discount amount applied to `totalTaxableAmountExcludingVat` before `documentTotal` is calculated.	`0.00`
`isSpecialBillingAgreement`	Yes	boolean	Set to true when the transaction is one of these: 1. A self-billed invoice 2. A third-party invoice billed on behalf of the supplier	`false`
`isTransactionType`	Yes	boolean	Set to true when the transaction is any of these (they can apply together): 1. Nominal supply 2. Export 3. Summary	`false`
`isSelfBilled`	Conditional	boolean	When `isSpecialBillingAgreement` is true and the invoice is self-billed.	`false`
`isThirdParty`	Conditional	boolean	When `isSpecialBillingAgreement` is true and the invoice is billed by a third party.	`true`
`isNominalSupply`	Conditional	boolean	When `isTransactionType` is true and the supply is nominal.	`false`
`isExport`	Conditional	boolean	When `isTransactionType` is true and the transaction is an export.	`false`
`isSummary`	Conditional	boolean	When `isTransactionType` is true and the invoice is a summary invoice.	`false`
`supplyDate`	Yes	string	The date and time the goods or services were supplied, in the format `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`.
`sellerVatRegistrationNumber`	Yes	string	The seller’s VAT registration number.	`300000000000003`
`sellerVatRegistrationNumberAr`	Yes	string	The seller’s VAT registration number in Arabic.	`300000000000003`
`additionalSellerIdType`	Yes	string	The type of the seller’s other ID. Use the scheme ID in bold: 1. Commercial registration number: `CRN` 2. MOMRA license: `MOM` 3. MLSD license: `MLS` 4. SAGIA license: `SAG` 5. Other ID: `OTH` If the seller has more than one of these IDs, enter one of them in the order above.	`CRN`
`additionalSellerIdNumber`	Yes	string	The seller’s ID number for the chosen ID type.	`1112233344`
`additionalSellerIdNumberAr`	Yes	string	The seller’s ID number for the chosen ID type, in Arabic.	`1112233344`
`sellerGroupVatRegistrationNumber`	Conditional	string	The seller’s group VAT registration number, if there is one.	`300000000000003`
`additionalBuyerIdType`	Yes	string	The type of the buyer’s other ID. It must be one of these scheme IDs: 1. Tax identification number: `TIN` 2. Commercial registration number: `CRN` 3. MOMRA license: `MOM` 4. MLSD license: `MLS` 5. 700 number: `_700` 6. SAGIA license: `SAG` 7. National ID: `NAT` 8. GCC ID: `GCC` 9. Iqama number: `IQA` 10. Passport ID: `PAS` 11. Other ID: `OTH` If the buyer has more than one of these IDs, enter one of them in the order above.	`TIN`
`additionalBuyerIdNumber`	Yes	string	The buyer’s national ID number.	`311111111100003`
`additionalBuyerIdNumberAr`	Yes	string	The buyer’s national ID number in Arabic.	`311111111100003`
`buyerGroupVatRegistrationNumber`	Conditional	string	If the buyer belongs to a VAT group, the buyer’s group VAT number.	`311111111100003`
`specialTaxTreatment`	Conditional	string	When tax is not charged at the standard rate, a narration of the “tax treatment applied to the supply”, as Article 53 of the VAT Implementing Regulation requires. Enter the narration when tax is not charged at the basic rate.	`0`
`vatCurrency`	Conditional	string	Required when the document currency is not SAR. `vatTotal` is always in SAR, even when the document currency is not SAR.	`SAR`
`noteIssuanceReason`	Conditional	string	The reason for issuing a credit or debit note. Under Article 40 (paragraph 1) and Article 54 (3) of the KSA VAT regulations, a credit or debit note is issued in these 5 cases: 1. The supply is cancelled or suspended, wholly or partly, after it took place. 2. The supply changes in a way that changes the VAT due. 3. The supply value, agreed in advance between the supplier and the consumer, is amended. 4. Goods or services are refunded. 5. The seller’s or buyer’s information changes.	`Cancellation or suspension of the supplies after its occurrence either wholly or partially`
`currency`	Yes	string	The transaction currency of the document.	`SAR`
`paymentMeans`	Yes	string	The payment means used.	`CREDIT`
`documentId`	Yes	number	A unique identifier of the invoice: the invoice reference number (IRN).	`2022100627`
`documentIdAr`	Yes	number	A unique identifier of the invoice, the invoice reference number (IRN), in Arabic.	`2022100627`

Export invoices

For export invoices, these buyer address fields are mandatory:

Buyer address for an export invoicejson

{
  "addrLine1": "12, Masjid Street",
  "city": "Dammam",
  "country": "US"
}

These fields are also required for export invoices:

Buyer ID for an export invoicejson

{
  "additionalBuyerIdType": "CRN",
  "additionalBuyerIdNumber": "12345678"
}

Export invoice example

Request bodyjson

{
  "invoiceData": {
    "documentType": "DOC_B2B_INV",
    "referenceId": "",
    "documentIssueDateTime": "2023-10-02T04:33:41.000Z",
    "documentDueDateTime": "2023-10-02T04:33:41.000Z",
    "sellerName": "Acme Trading LLC",
    "sellerNameAr": "شركة أكمي للتجارة",
    "sellerAddress": {
      "addrLine1": "12, Masjid Street",
      "addrLine2": "Building 4",
      "additionalNo": "1234",
      "buildingNumber": "1234",
      "city": "Dammam",
      "state": "Riyadh",
      "zipCode": "12313",
      "district": "Riyadh",
      "country": "SA",
      "addrLine1Ar": "RB2",
      "addrLine2Ar": "Riyadh",
      "additionalNoAr": "1234",
      "buildingNumberAr": "1234",
      "cityAr": "Riyadh",
      "stateAr": "Riyadh",
      "zipCodeAr": "17555",
      "districtAr": "Riyadh",
      "countryAr": "SA"
    },
    "buyerName": "Example Customer LLC",
    "buyerNameAr": "شركة العميل النموذجي",
    "buyerAddress": {
      "addrLine1": "12, Masjid Street",
      "city": "Dammam",
      "country": "US"
    },
    "documentLineItems": [
      {
        "lineItemDesc": "LOGISTICS WITH VAT",
        "lineItemPrice": 1,
        "lineItemQty": 1,
        "lineItemTaxableAmount": 1,
        "discountOnLineItem": 0,
        "vatRateOnLineItem": 0,
        "lineItemVatAmount": 0.00,
        "lineItemSubTotal": 1.00,
        "vatCategoryCode": "Z",
        "vatExemptionReason": "Export of goods",
        "vatExemptionReasonCode": "VATEX-SA-32"
      }
    ],
    "totalExcludingVat": 1.00,
    "totalTaxableAmountExcludingVat": 0.00,
    "vatTotal": 0.00,
    "documentTotal": 1.00,
    "discountOnDocumentTotal": 0,
    "isSpecialBillingAgreement": "false",
    "isTransactionType": "false",
    "isSelfBilled": "false",
    "isThirdParty": "false",
    "isNominalSupply": "false",
    "isExport": "true",
    "isSummary": "false",
    "supplyDate": "2022-12-31T04:33:41.000Z",
    "sellerVatRegistrationNumber": "300000000000003",
    "sellerVatRegistrationNumberAr": "300000000000003",
    "sellerGroupVatRegistrationNumber": "",
    "additionalSellerIdType": "CRN",
    "additionalSellerIdNumber": "34523452345234",
    "additionalSellerIdNumberAr": "34523452345234",
    "specialTaxTreatment": "0",
    "additionalBuyerIdType": "CRN",
    "additionalBuyerIdNumber": "12345678",
    "additionalBuyerIdNumberAr": "1980792",
    "currency": "SAR",
    "paymentMeans": "CREDIT",
    "documentId": "23443434",
    "documentIdAr": "خمسة"
  }
}

Special conditions for B2C invoices

Export invoices cannot be used for B2C invoices.
If isTransactionType is true, either isSummary or isNominalSupply must be true.
- If isSummary is true, you must also send both supplyDate and supplyEndDate.

Buyer ID types for exports

For export invoices, both additionalBuyerIdType and additionalBuyerIdNumber are mandatory. Choose the type based on the buyer’s country:

TIN
NAT
Passport
Other

If the buyer is from a country other than Saudi Arabia, you can use:

CIN: use CRN
VAT, GST and similar numbers: use Other

Prepayments

Prepayment invoice example

This example is a prepayment invoice:

Request bodyjson

{
    "invoiceData": {
        "documentType": "DOC_B2B_PRE",
        "documentIssueDateTime": "2024-03-05T14:52:27.000Z",
        "documentDueDateTime": "2024-05-04T00:00:00.000Z",
        "sellerName": "Acme Trading LLC",
        "sellerAddress": {
            "addrLine1": "Jeddah",
            "buildingNumber": "1234",
            "city": "Jeddah",
            "zipCode": "23435",
            "district": "Ar Rawdah",
            "country": "SA"
        },
        "buyerName": "Example Customer LLC",
        "buyerAddress": {
            "addrLine1": "King Fahad Street\r\r13413 RIYADH\rSAUDI ARABIA",
            "buildingNumber": "5678",
            "city": "Riyadh",
            "zipCode": "13413",
            "district": "Riyadh",
            "country": "SA"
        },
        "documentLineItems": [
            {
                "lineItemDesc": "PrePayment",
                "lineItemPrice": 100.00,
                "lineItemQty": 1,
                "lineItemTaxableAmount": 100.00,
                "discountOnLineItem": 0,
                "vatRateOnLineItem": 15,
                "lineItemVatAmount": 15.00,
                "lineItemSubTotal": 115.00,
                "vatCategoryCode": "S"
            }
        ],
        "totalExcludingVat": 100.00,
        "totalTaxableAmountExcludingVat": 100.00,
        "vatTotal": 15.00,
        "documentTotal": 115.00,
        "isSpecialBillingAgreement": "false",
        "isTransactionType": "false",
        "supplyDate": "2024-03-05T00:00:00.000Z",
        "sellerVatRegistrationNumber": "300000000000003",
        "additionalSellerIdType": "CRN",
        "additionalSellerIdNumber": "1010000000",
        "additionalBuyerIdType": "TIN",
        "additionalBuyerIdNumber": "3111111111",
        "discountOnDocumentTotal": 0.00,
        "specialTaxTreatment": "0",
        "currency": "SAR",
        "paymentMeans": "CASH",
        "documentId": "PREPAY00Bbhjbhjy2C001"
    }
}

Invoice that adjusts a prepayment

This example is an invoice that adjusts an earlier prepayment. The prepayment goes in prePaymentItems:

Request bodyjson

{
    "invoiceData": {
        "documentType": "DOC_B2B_INV",
        "documentIssueDateTime": "2024-03-06T14:52:27.000Z",
        "documentDueDateTime": "2024-05-04T00:00:00.000Z",
        "sellerName": "Acme Trading LLC",
        "sellerAddress": {
            "addrLine1": "Jeddah",
            "buildingNumber": "1234",
            "city": "Jeddah",
            "zipCode": "23435",
            "district": "Ar Rawdah",
            "country": "SA"
        },
        "buyerName": "Example Customer LLC",
        "buyerAddress": {
            "addrLine1": "King Fahad Street\r\r13413 RIYADH\rSAUDI ARABIA",
            "buildingNumber": "5678",
            "city": "Riyadh",
            "zipCode": "13413",
            "district": "Riyadh",
            "country": "SA"
        },
        "documentLineItems": [
            {
                "lineItemDesc": "AMD CPU Desktop Ryzen 5 6C/12T 5600 (3.6/4.2GHz Boost,36MB,65W,AM4) Box",
                "lineItemPrice": 460.14,
                "lineItemQty": 1,
                "lineItemTaxableAmount": 460.14,
                "discountOnLineItem": 0,
                "vatRateOnLineItem": 15,
                "lineItemVatAmount": 69.02,
                "lineItemSubTotal": 529.16,
                "vatCategoryCode": "S"
            },
            {
                "lineItemDesc": "Transportation Charges Door to Door",
                "lineItemPrice": 5.22,
                "lineItemQty": 1,
                "lineItemTaxableAmount": 5.22,
                "discountOnLineItem": 0,
                "vatRateOnLineItem": 15,
                "lineItemVatAmount": 0.78,
                "lineItemSubTotal": 6,
                "vatCategoryCode": "S"
            }
        ],
        "prePaymentItems": [
            {
                "prePaymentId": "PREPAY00Bbhjbhjy2C001",
                "prePaymentIssueDateTime": "2024-02-01T14:52:27.000Z",
                "vatCategoryCodeOnPrePayment": "S",
                "vatRateOnPrePayment": 15.00,
                "prePaymentTaxAmount": 15.00,
                "prePaymentTaxableAmount": 100.00,
                "prePaymentAdjustmentAmount": 115.00
            }
        ],
        "totalExcludingVat": 465.36,
        "totalTaxableAmountExcludingVat": 465.36,
        "vatTotal": 69.02,
        "documentTotal": 529.16,
        "amountPaid": 115.00,
        "dueAmount": 414.16,
        "isSpecialBillingAgreement": "false",
        "isTransactionType": "false",
        "supplyDate": "2024-03-05T00:00:00.000Z",
        "sellerVatRegistrationNumber": "300000000000003",
        "additionalSellerIdType": "CRN",
        "additionalSellerIdNumber": "1010000000",
        "additionalBuyerIdType": "TIN",
        "additionalBuyerIdNumber": "3111111111",
        "discountOnDocumentTotal": 5.22,
        "specialTaxTreatment": "0",
        "currency": "SAR",
        "paymentMeans": "CASH",
        "documentId": "234234j2565564n"
    }
}

Watch the video on prepayment adjustments and important API elements.

Prepayment parameters

These fields go in each entry of prePaymentItems. They are conditionally mandatory: send them when the invoice adjusts an advance (prepayment) amount.

Parameter	Field in the example	Required	Type	Description
Prepayment ID	`prePaymentId`	Yes, when the invoice adjusts an advance amount	string	The sequential invoice number of the prepayment invoice the advance is adjusted against.
Prepayment issue date and time	`prePaymentIssueDateTime`	Yes, when the invoice adjusts an advance amount	date and time	The issue date and time of the prepayment invoice.
Prepayment document type code	Not shown	No (conditional, when the invoice adjusts an advance amount)	string	The invoice type code. It must be 386 by default.
Prepayment VAT category code	`vatCategoryCodeOnPrePayment`	Yes, when the invoice adjusts an advance amount	string	The VAT category code that applies to the prepayment.
Prepayment VAT rate	`vatRateOnPrePayment`	Yes, when the invoice adjusts an advance amount	number	The VAT rate that applies to the prepayment.
Prepayment taxable amount	`prePaymentTaxableAmount`	Yes, when the invoice adjusts an advance amount	number	Advance amount received × 100 ÷ (100 + VAT rate)
Prepayment tax amount	`prePaymentTaxAmount`	Yes, when the invoice adjusts an advance amount	number	Advance amount received × VAT rate ÷ (100 + VAT rate)
Prepayment adjustment amount	`prePaymentAdjustmentAmount`	Yes, when the invoice adjusts an advance amount	number	Prepayment taxable amount + prepayment tax amount

Exchange rate, discount and payment fields

Parameter	Field in the examples	Required	Type	Description	Example
Exchange rate	`exchangeRate`	Conditional: when the document currency is not SAR	number	The rate at which the document currency converts to SAR.
Additional discount at line level	`additionalDiscountAtLineLevel`	Yes	number	An additional discount amount applied to the line item.	`0`
Amount paid	`amountPaid`	Yes	number	The total amount paid so far against the invoice amount, including adjustments and advances.	`115`
Amount due for payment	`dueAmount`	Yes	number	Amount due = invoice total - amount paid	`0`

Additional discount at line level example

Request bodyjson

{
    "invoiceData": {
        "documentType": "DOC_B2B_INV",
        "documentIssueDateTime": "2024-07-08T15:28:08.000Z",
        "documentDueDateTime": "2024-07-08T15:28:08.000Z",
        "sellerName": "Acme Trading LLC",
        "sellerAddress": {
            "addrLine1": "King Saud Street",
            "addrLine2": "PO Box 1234",
            "buildingNumber": "1234",
            "additionalNo": "5678",
            "city": "Dammam",
            "zipCode": "32241",
            "district": "Industrial City",
            "country": "SA"
        },
        "buyerName": "Example Customer LLC",
        "pdfTemplates": "TEMPLATE_M",
        "buyerNameAr": "شركة العميل النموذجي",
        "buyerAddress": {
            "addrLine1": "منطقة المستودعات",
            "addrLine2": "منطقة المستودعات",
            "buildingNumber": "4321",
            "additionalNo": "4321",
            "city": "QATEEF",
            "cityAr": "القطيف",
            "zipCode": "32654",
            "district": "منطقة المستودعات",
            "country": "SA",
            "addrLine1Ar": "منطقة المستودعات",
            "addrLine2Ar": "منطقة المستودعات",
            "buildingNumberAr": "4321",
            "additionalNoAr": "4321",
            "zipCodeAr": "32654",
            "districtAr": "منطقة المستودعات"
        },
        "documentLineItems": [
            {
                "lineItemDesc": "Pipe welding machine set",
                "lineItemPrice": 1000.00,
                "lineItemQty": 11.00,
                "lineItemTaxableAmount": 10000.00,
                "discountOnLineItem": 0,
                "vatRateOnLineItem": 15,
                "additionalDiscountAtLineLevel": 1000.00,
                "lineItemVatAmount": 1500.00,
                "lineItemSubTotal": 11500.00,
                "vatCategoryCode": "S"
            }
        ],
        "totalExcludingVat": 10000.00,
        "totalTaxableAmountExcludingVat": 10000.00,
        "vatTotal": 1500.00,
        "documentTotal": 11500.00,
        "isTransactionType": "false",
        "isSpecialBillingAgreement": "false",
        "isSelfBilled": false,
        "isThirdParty": false,
        "isNominalSupply": false,
        "isExport": false,
        "isSummary": false,
        "supplyDate": "2024-07-08T15:28:08.000Z",
        "sellerVatRegistrationNumber": "300000000000003",
        "additionalSellerIdType": "CRN",
        "additionalSellerIdNumber": "2050000000",
        "buyerVatRegistrationNumber": "311111111100003",
        "additionalBuyerIdType": "TIN",
        "additionalBuyerIdNumber": "3111111111",
        "discountOnDocumentTotal": 0,
        "specialTaxTreatment": "0",
        "currency": "SAR",
        "documentId": "INV-2026-0142",
        "paymentMeans": "CREDIT",
        "customFields": {
            "DeliveryNoteNo": "DN-2026-0142",
            "SalesOrderNo": "SO-2026-0142"
        },
        "ccEmail": "finance@acme.example"
    },
    "serialNumber": "",
    "DocumentSequenceCheckEnabled": "false"
}

Watch the video on line-level and document-level discount fields.

Exchange rate example

If the document uses a currency other than SAR, use the exchangeRate field to give the rate to SAR.

Request bodyjson

{
    "invoiceData": {
        "documentType": "DOC_B2B_INV",
        "referenceId": "",
        "documentIssueDateTime": "2024-08-19T01:45:22.000Z",
        "documentDueDateTime": "2024-08-19T23:00:00.000Z",
        "sellerName": "Acme Trading LLC",
        "sellerNameAr": "",
        "sellerAddress": {
            "addrLine1": "1234 King Abdullah Rd",
            "addrLine2": "Al Sharafiyah, Riyadh 13214, Saudi Arabia",
            "additionalNo": "",
            "buildingNumber": "1234",
            "city": "Riyadh",
            "state": "Riyadh",
            "zipCode": "13214",
            "district": "Al Sharafiyah",
            "country": "SA",
            "addrLine1Ar": "",
            "addrLine2Ar": "",
            "additionalNoAr": "",
            "buildingNumberAr": "1234",
            "cityAr": "Riyadh",
            "stateAr": "Riyadh",
            "zipCodeAr": "13214",
            "districtAr": "",
            "countryAr": "SA"
        },
        "buyerName": "Example Customer LLC",
        "buyerNameAr": "شركة العميل النموذجي",
        "buyerAddress": {
            "addrLine1": "4321 Port Road",
            "addrLine2": "Jeddah Islamic Port, Jeddah 22233, Saudi Arabia",
            "additionalNo": "",
            "buildingNumber": "4321",
            "city": "Jeddah",
            "state": "Jeddah",
            "zipCode": "22233",
            "district": "Jeddah Islamic Port",
            "country": "SA",
            "addrLine1Ar": "",
            "addrLine2Ar": "",
            "additionalNoAr": "",
            "buildingNumberAr": "",
            "cityAr": "Jeddah",
            "stateAr": "Jeddah",
            "zipCodeAr": "22233",
            "districtAr": "",
            "countryAr": "SA"
        },
        "documentLineItems": [
            {
                "lineItemDesc": "Taxable Charge",
                "lineItemPrice": 123.10,
                "lineItemQty": 10.00,
                "lineItemTaxableAmount": 1231.00,
                "discountOnLineItem": 0.0,
                "vatRateOnLineItem": 15.00,
                "lineItemVatAmount": 184.65,
                "lineItemSubTotal": 1415.65,
                "vatCategoryCode": "S",
                "vatExemptionReason": "",
                "vatExemptionReasonCode": ""
            }
        ],
        "totalExcludingVat": 1231.00,
        "totalTaxableAmountExcludingVat": 1231.00,
        "vatTotal": 184.65,
        "documentTotal": 1415.65,
        "discountOnDocumentTotal": 0.00,
        "isSpecialBillingAgreement": false,
        "isTransactionType": false,
        "isSelfBilled": false,
        "isThirdParty": false,
        "isNominalSupply": false,
        "isExport": false,
        "isSummary": false,
        "supplyDate": "2024-08-19T00:00:00.000Z",
        "sellerVatRegistrationNumber": "300000000000003",
        "sellerVatRegistrationNumberAr": "",
        "sellerGroupVatRegistrationNumber": "",
        "additionalSellerIdType": "CRN",
        "additionalSellerIdNumber": "0011001100",
        "additionalSellerIdNumberAr": "0011001100",
        "specialTaxTreatment": "0",
        "additionalBuyerIdType": "TIN",
        "additionalBuyerIdNumber": "1234567890",
        "additionalBuyerIdNumberAr": "1234567890",
        "buyerGroupVatRegistrationNumber": "",
        "noteIssuanceReason": "",
        "currency": "USD",
        "vatCurrency": "SAR",
        "exchangeRate": "3.00",
        "paymentMeans": "",
        "documentId": "21832399424",
        "documentIdAr": ""
    }
}

Example response

Long Base64 values (clearedInvoice, encodedQRCode and pdfData) are shortened in the examples on this page.

Responsejson

{
    "statusCode": "OK",
    "clearInvoiceResponse": {
        "validationResults": {
            "infoMessages": [
                {
                    "type": "INFO",
                    "code": "XSD_ZATCA_VALID",
                    "category": "XSD validation",
                    "message": "Complied with UBL 2.1 standards in line with ZATCA specifications",
                    "status": "PASS"
                }
            ],
            "warningMessages": [],
            "errorMessages": [],
            "status": "PASS"
        },
        "clearanceStatus": "CLEARED",
        "clearedInvoice": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4K…",
        "invoiceXMLFileName": "300000000000003_20241017T113256_2.xml"
    },
    "status": "CLEARED",
    "documentMetric": "DOC_B2B_CLEARED",
    "encodedQRCode": "ARBBY21lIFRyYWRpbmcgTExDAg8zMDAwMDAwMDAwMDAwMDM…",
    "downloadDocumentResponse": {
        "pdfData": "JVBERi0xLjQK…",
        "pdfFileName": "300000000000003_20241017T113256_2.pdf"
    }
}

Response parameters

Parameter	Type	Description	Example
`statusCode`	string	Either accepted or rejected.	`OK`
`clearInvoiceResponse`	object	The response received after you submit an invoice.	`{"infoMessages": [{"type": "INFO", "code": "XSD_ZATCA_VALID", "category": "XSD validation", "message": "Complied with UBL 2.1 standards in line with ZATCA specifications", "status": "PASS"}], "warningMessages": [], "errorMessages": [], "status": "PASS"}`
`infoMessages`	list	Information messages received from ZATCA.	`[{"type": "INFO", "code": "XSD_ZATCA_VALID", "category": "XSD validation", "message": "Complied with UBL 2.1 standards in line with ZATCA specifications", "status": "PASS"}]`
`type`	string	The type of message.	`INFO`
`code`	string	The message code.	`XSD_ZATCA_VALID`
`category`	string	The message category.	`XSD validation`
`message`	string	The information message from ZATCA.	`Complied with UBL 2.1 standards in line with ZATCA specifications`
`status`	string	The status.	`PASS` inside `validationResults`; `CLEARED` or `REPORTED` at the top level of the response
`warningMessages`	list	The list of warning messages from ZATCA.
`errorMessages`	list	The list of error messages from ZATCA.
`clearanceStatus`	string	The clearance status from ZATCA.	`CLEARED`
`clearedInvoice`	string	The cleared invoice, Base64 encoded.	`PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4K…` (shortened)
`documentMetric`	string	The type of metric applied to the document.	`DOC_B2B_CLEARED`
`encodedQRCode`	string	The QR code, Base64 encoded.	`ARBBY21lIFRyYWRpbmcgTExDAg8zMDAwMDAwMDAwMDAwMDM…` (shortened)

If a request fails, see Error messages.

More examples

Each example shows a request and the response it returns. Long Base64 values in the responses are shortened.

Zero VAT rate

Request bodyjson

{
    "invoiceData": {
        "documentType": "DOC_B2B_INV",
        "referenceId": "",
        "documentIssueDateTime": "2023-10-02T04:33:41.000Z",
        "documentDueDateTime": "2023-10-02T04:33:41.000Z",
        "sellerName": "Acme Trading LLC",
        "sellerNameAr": "شركة أكمي للتجارة",
        "sellerAddress": {
            "addrLine1": "12, Masjid Street",
            "addrLine2": "Building 4",
            "additionalNo": "1234",
            "buildingNumber": "1234",
            "city": "Dammam",
            "state": "Riyadh",
            "zipCode": "12313",
            "district": "Riyadh",
            "country": "SA",
            "addrLine1Ar": "RB2",
            "addrLine2Ar": "Riyadh",
            "additionalNoAr": "1234",
            "buildingNumberAr": "1234",
            "cityAr": "Riyadh",
            "stateAr": "Riyadh",
            "zipCodeAr": "17555",
            "districtAr": "Riyadh",
            "countryAr": "SA"
        },
        "buyerName": "Example Customer LLC",
        "buyerNameAr": "شركة العميل النموذجي",
        "buyerAddress": {
            "addrLine1": "12, Masjid Street",
            "addrLine2": "Building 4",
            "additionalNo": "1234",
            "buildingNumber": "1234",
            "city": "Dammam",
            "state": "Riyadh",
            "zipCode": "12313",
            "district": "Riyadh",
            "country": "SA",
            "addrLine1Ar": "RB2",
            "addrLine2Ar": "Riyadh",
            "additionalNoAr": "1234",
            "buildingNumberAr": "1234",
            "cityAr": "Riyadh",
            "stateAr": "Riyadh",
            "zipCodeAr": "17555",
            "districtAr": "Riyadh",
            "countryAr": "SA"
        },
        "documentLineItems": [
            {
                "lineItemDesc": "LOGISTICS WITH VAT",
                "lineItemPrice": 1,
                "lineItemQty": 1,
                "lineItemTaxableAmount": 1,
                "discountOnLineItem": 0,
                "vatRateOnLineItem": 0,
                "lineItemVatAmount": 0.0,
                "lineItemSubTotal": 1.0,
                "vatCategoryCode": "Z",
                "vatExemptionReason": "Export of goods",
                "vatExemptionReasonCode": "VATEX-SA-32"
            }
        ],
        "totalExcludingVat": 1.0,
        "totalTaxableAmountExcludingVat": 0.0,
        "vatTotal": 0.0,
        "documentTotal": 1.0,
        "discountOnDocumentTotal": 0,
        "isSpecialBillingAgreement": "false",
        "isTransactionType": "false",
        "isSelfBilled": "false",
        "isThirdParty": "false",
        "isNominalSupply": "false",
        "isExport": "false",
        "isSummary": "false",
        "supplyDate": "2022-12-31T04:33:41.000Z",
        "sellerVatRegistrationNumber": "300000000000003",
        "sellerVatRegistrationNumberAr": "300000000000003",
        "sellerGroupVatRegistrationNumber": "",
        "additionalSellerIdType": "CRN",
        "additionalSellerIdNumber": "34523452345234",
        "additionalSellerIdNumberAr": "34523452345234",
        "specialTaxTreatment": "0",
        "additionalBuyerIdType": "CRN",
        "additionalBuyerIdNumber": "12345678",
        "additionalBuyerIdNumberAr": "1980792",
        "currency": "SAR",
        "paymentMeans": "CREDIT",
        "documentId": "21324",
        "documentIdAr": "خمسة"
    }
}

Responsejson

{
  "statusCode": "OK",
  "clearInvoiceResponse": {
    "validationResults": {
      "infoMessages": [
        {
          "type": "INFO",
          "code": "XSD_ZATCA_VALID",
          "category": "XSD validation",
          "message": "Complied with UBL 2.1 standards in line with ZATCA specifications",
          "status": "PASS"
        }
      ],
      "warningMessages": [],
      "errorMessages": [],
      "status": "PASS"
    },
    "clearanceStatus": "CLEARED",
    "clearedInvoice": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4K…"
  },
  "status": "CLEARED",
  "documentMetric": "DOC_B2B_CLEARED",
  "encodedQRCode": "ARBBY21lIFRyYWRpbmcgTExDAg8zMDAwMDAwMDAwMDAwMDM…"
}

Exempt VAT rate

Request bodyjson

{
    "invoiceData": {
        "documentType": "DOC_B2B_INV",
        "referenceId": "",
        "documentIssueDateTime": "2023-10-02T04:33:41.000Z",
        "documentDueDateTime": "2023-10-02T04:33:41.000Z",
        "sellerName": "Acme Trading LLC",
        "sellerNameAr": "شركة أكمي للتجارة",
        "sellerAddress": {
            "addrLine1": "12, Masjid Street",
            "addrLine2": "Building 4",
            "additionalNo": "1234",
            "buildingNumber": "1234",
            "city": "Dammam",
            "state": "Riyadh",
            "zipCode": "12313",
            "district": "Riyadh",
            "country": "SA",
            "addrLine1Ar": "RB2",
            "addrLine2Ar": "Riyadh",
            "additionalNoAr": "1234",
            "buildingNumberAr": "1234",
            "cityAr": "Riyadh",
            "stateAr": "Riyadh",
            "zipCodeAr": "17555",
            "districtAr": "Riyadh",
            "countryAr": "SA"
        },
        "buyerName": "Example Customer LLC",
        "buyerNameAr": "شركة العميل النموذجي",
        "buyerAddress": {
            "addrLine1": "12, Masjid Street",
            "addrLine2": "Building 4",
            "additionalNo": "1234",
            "buildingNumber": "1234",
            "city": "Dammam",
            "state": "Riyadh",
            "zipCode": "12313",
            "district": "Riyadh",
            "country": "SA",
            "addrLine1Ar": "RB2",
            "addrLine2Ar": "Riyadh",
            "additionalNoAr": "1234",
            "buildingNumberAr": "1234",
            "cityAr": "Riyadh",
            "stateAr": "Riyadh",
            "zipCodeAr": "17555",
            "districtAr": "Riyadh",
            "countryAr": "SA"
        },
        "documentLineItems": [
            {
                "lineItemDesc": "LOGISTICS WITH OUT VAT",
                "lineItemPrice": 5,
                "lineItemQty": 1,
                "lineItemTaxableAmount": 5,
                "discountOnLineItem": 0,
                "vatRateOnLineItem": 0,
                "lineItemVatAmount": 0.0,
                "lineItemSubTotal": 5,
                "vatCategoryCode": "E",
                "vatExemptionReason": "Financial services mentioned in Article 29 of the VAT Regulations",
                "vatExemptionReasonCode": "VATEX-SA-29"
            }
        ],
        "totalExcludingVat": 5.0,
        "totalTaxableAmountExcludingVat": 0.0,
        "vatTotal": 0.0,
        "documentTotal": 5.0,
        "discountOnDocumentTotal": 0,
        "isSpecialBillingAgreement": "false",
        "isTransactionType": "false",
        "isSelfBilled": "false",
        "isThirdParty": "false",
        "isNominalSupply": "false",
        "isExport": "false",
        "isSummary": "false",
        "supplyDate": "2022-12-31T04:33:41.000Z",
        "sellerVatRegistrationNumber": "300000000000003",
        "sellerVatRegistrationNumberAr": "300000000000003",
        "sellerGroupVatRegistrationNumber": "",
        "additionalSellerIdType": "CRN",
        "additionalSellerIdNumber": "34523452345234",
        "additionalSellerIdNumberAr": "34523452345234",
        "specialTaxTreatment": "0",
        "additionalBuyerIdType": "CRN",
        "additionalBuyerIdNumber": "12345678",
        "additionalBuyerIdNumberAr": "1980792",
        "currency": "SAR",
        "paymentMeans": "CREDIT",
        "documentId": "1321",
        "documentIdAr": "خمسة"
    }
}

This response passes with a warning, so status is WARNED:

Responsejson

{
    "statusCode": "ACCEPTED",
    "clearInvoiceResponse": {
        "validationResults": {
            "infoMessages": [
                {
                    "type": "INFO",
                    "code": "XSD_ZATCA_VALID",
                    "category": "XSD validation",
                    "message": "Complied with UBL 2.1 standards in line with ZATCA specifications",
                    "status": "PASS"
                }
            ],
            "warningMessages": [
                {
                    "type": "WARNING",
                    "code": "BR-KSA-EN16931-11",
                    "category": "KSA",
                    "message": "Invoice line net amount (BT-131) must equal (Invoiced quantity (BT-129) * (Item net price (BT-146) / item price base quantity (BT-149))) + Sum of invoice line charge amount (BT-141) - Sum of invoice line allowance amount (BT-136)",
                    "status": "WARNING"
                }
            ],
            "errorMessages": [],
            "status": "WARNING"
        },
        "clearanceStatus": "CLEARED",
        "clearedInvoice": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4K…"
    },
    "status": "WARNED",
    "documentMetric": "DOC_B2B_WARNED",
    "encodedQRCode": "ARBBY21lIFRyYWRpbmcgTExDAg8zMDAwMDAwMDAwMDAwMDM…",
    "downloadDocumentResponse": {
        "pdfData": "JVBERi0xLjQK…",
        "pdfFileName": "300000000000003_20231002T043341_202301306.pdf"
    }
}

Standard VAT rate

Request bodyjson

{
    "invoiceData": {
        "documentType": "DOC_B2B_INV",
        "referenceId": "",
        "documentIssueDateTime": "2023-10-02T04:33:41.000Z",
        "documentDueDateTime": "2023-10-02T04:33:41.000Z",
        "sellerName": "Acme Trading LLC",
        "sellerNameAr": "شركة أكمي للتجارة",
        "sellerAddress": {
            "addrLine1": "12, Masjid Street",
            "addrLine2": "Building 4",
            "additionalNo": "1234",
            "buildingNumber": "1234",
            "city": "Dammam",
            "state": "Riyadh",
            "zipCode": "12313",
            "district": "Riyadh",
            "country": "SA",
            "addrLine1Ar": "RB2",
            "addrLine2Ar": "Riyadh",
            "additionalNoAr": "1234",
            "buildingNumberAr": "1234",
            "cityAr": "Riyadh",
            "stateAr": "Riyadh",
            "zipCodeAr": "17555",
            "districtAr": "Riyadh",
            "countryAr": "SA"
        },
        "buyerName": "Example Customer LLC",
        "buyerNameAr": "شركة العميل النموذجي",
        "buyerAddress": {
            "addrLine1": "12, Masjid Street",
            "addrLine2": "Building 4",
            "additionalNo": "1234",
            "buildingNumber": "1234",
            "city": "Dammam",
            "state": "Riyadh",
            "zipCode": "12313",
            "district": "Riyadh",
            "country": "SA",
            "addrLine1Ar": "RB2",
            "addrLine2Ar": "Riyadh",
            "additionalNoAr": "1234",
            "buildingNumberAr": "1234",
            "cityAr": "Riyadh",
            "stateAr": "Riyadh",
            "zipCodeAr": "17555",
            "districtAr": "Riyadh",
            "countryAr": "SA"
        },
        "documentLineItems": [
            {
                "lineItemDesc": "LOGISTICS WITH VAT",
                "lineItemPrice": 5,
                "lineItemQty": 1,
                "lineItemTaxableAmount": 5,
                "discountOnLineItem": 0,
                "vatRateOnLineItem": 15,
                "lineItemVatAmount": 0.75,
                "lineItemSubTotal": 5.75,
                "vatCategoryCode": "S"
            },
            {
                "lineItemDesc": "LOGISTICS WITH OUT VAT",
                "lineItemPrice": 5,
                "lineItemQty": 1,
                "lineItemTaxableAmount": 5,
                "discountOnLineItem": 0,
                "vatRateOnLineItem": 0,
                "lineItemVatAmount": 0.0,
                "lineItemSubTotal": 5,
                "vatCategoryCode": "E",
                "vatExemptionReason": "Financial services mentioned in Article 29 of the VAT Regulations",
                "vatExemptionReasonCode": "VATEX-SA-29"
            }
        ],
        "totalExcludingVat": 10,
        "totalTaxableAmountExcludingVat": 5,
        "vatTotal": 0.75,
        "documentTotal": 10.75,
        "discountOnDocumentTotal": 0,
        "isSpecialBillingAgreement": "false",
        "isTransactionType": "false",
        "isSelfBilled": "false",
        "isThirdParty": "false",
        "isNominalSupply": "false",
        "isExport": "false",
        "isSummary": "false",
        "supplyDate": "2022-12-31T04:33:41.000Z",
        "sellerVatRegistrationNumber": "300000000000003",
        "sellerVatRegistrationNumberAr": "300000000000003",
        "sellerGroupVatRegistrationNumber": "",
        "additionalSellerIdType": "CRN",
        "additionalSellerIdNumber": "34523452345234",
        "additionalSellerIdNumberAr": "34523452345234",
        "specialTaxTreatment": "0",
        "additionalBuyerIdType": "CRN",
        "additionalBuyerIdNumber": "12345678",
        "additionalBuyerIdNumberAr": "1980792",
        "currency": "SAR",
        "paymentMeans": "CREDIT",
        "documentId": "i4928428492",
        "documentIdAr": "خمسة"
    }
}

Responsejson

{
  "statusCode": "OK",
  "clearInvoiceResponse": {
    "validationResults": {
      "infoMessages": [
        {
          "type": "INFO",
          "code": "XSD_ZATCA_VALID",
          "category": "XSD validation",
          "message": "Complied with UBL 2.1 standards in line with ZATCA specifications",
          "status": "PASS"
        }
      ],
      "warningMessages": [],
      "errorMessages": [],
      "status": "PASS"
    },
    "clearanceStatus": "CLEARED",
    "clearedInvoice": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4K…"
  },
  "status": "CLEARED",
  "documentMetric": "DOC_B2B_CLEARED",
  "encodedQRCode": "ARBBY21lIFRyYWRpbmcgTExDAg8zMDAwMDAwMDAwMDAwMDM…"
}

Exempt and standard VAT rates

The request is the same as the standard VAT rate example: one line at the standard rate and one exempt line.

Responsejson

{
  "statusCode": "OK",
  "clearInvoiceResponse": {
    "validationResults": {
      "infoMessages": [
        {
          "type": "INFO",
          "code": "XSD_ZATCA_VALID",
          "category": "XSD validation",
          "message": "Complied with UBL 2.1 standards in line with ZATCA specifications",
          "status": "PASS"
        }
      ],
      "warningMessages": [],
      "errorMessages": [],
      "status": "PASS"
    },
    "clearanceStatus": "CLEARED",
    "clearedInvoice": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4K…"
  },
  "status": "CLEARED",
  "documentMetric": "DOC_B2B_CLEARED",
  "encodedQRCode": "ARBBY21lIFRyYWRpbmcgTExDAg8zMDAwMDAwMDAwMDAwMDM…"
}