# 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.

> **Legacy API v2**
>
> This page documents API v2, which is no longer developed. New integrations should use the current API: see [Unify](https://docs.complyance.io/api-reference/unify/) and [Saudi Arabia](https://docs.complyance.io/countries/sa/).

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](https://docs.complyance.io/legacy/v2/ksa/egs-onboarding/), 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](https://docs.complyance.io/legacy/v2/ksa/api-key-generation/). For example `EXAMPLEapiKEY00000000000000000000000000`. |
| `Content-Type` | `application/json` |
| `env` | `sandbox` |

## Example request

```json title="Request body"
{
    "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:

```json title="Buyer address for an export invoice"
{
  "addrLine1": "12, Masjid Street",
  "city": "Dammam",
  "country": "US"
}
```

These fields are also required for export invoices:

```json title="Buyer ID for an export invoice"
{
  "additionalBuyerIdType": "CRN",
  "additionalBuyerIdNumber": "12345678"
}
```

### Export invoice example

```json title="Request body"
{
  "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:

```json title="Request body"
{
    "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`:

```json title="Request body"
{
    "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](https://www.youtube.com/watch?v=utCg7FGbMlA).

### 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

```json title="Request body"
{
    "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](https://www.youtube.com/watch?v=zLuiHyWq-OI).

## Exchange rate example

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

```json title="Request body"
{
    "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.

```json title="Response"
{
    "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](https://docs.complyance.io/legacy/v2/ksa/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

```json title="Request body"
{
    "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": "خمسة"
    }
}
```

```json title="Response"
{
  "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

```json title="Request body"
{
    "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`:

```json title="Response"
{
    "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

```json title="Request body"
{
    "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": "خمسة"
    }
}
```

```json title="Response"
{
  "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](https://docs.complyance.io/legacy/v2/ksa/unify/#standard-vat-rate) example: one line at the standard rate and one exempt line.

```json title="Response"
{
  "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…"
}
```

Source: https://docs.complyance.io/legacy/v2/ksa/unify/