E-Invoice Object
An E-Invoice object has the following schema:
UBLVersionID
String
Equal: "2.1"
Optional. Default value: "2.1"
ProfileID
String
Equal: "reporting:1.0"
Mandatory. Business process type. Identifies a user-defined profile of the customization of UBL being used. Default value: "reporting:1.0"
UUID
String
letters, digits and dashes
Optional. Universally Unique invoice identifier. Globally unique reference identifying the invoice. Sample: 3cf5ee18-ee25-44ea-a444-2c37ba7f28be In case this is not sent, ClearTax will generate a UUID.
InvoiceTypeCode
Object
-
Mandatory. Invoice Type Code Object
IssueDate
String
Format:
YYYY-MM-DD
Mandatory. Invoice issue date (gregorian calendar). The date when the Invoice was issued as per Article 53 of the VAT Implementing Regulation. The document issue date must be less or equal to the current date.
IssueTime
String
Format: HH:mm:ss (24 hr format)
Mandatory. Invoice issue time. The time when the invoice was issued.
Delivery
Array
-
"Conditional. Required in case of Credit Debit Notes. Array of Delivery Objects. Default: []"
BillingReference
Array
-
Conditional. Required only in case the invoice type is Debit Note or Credit Note. Not required if the invoice type is Tax Invoice. Array of Billing Reference Objects.
OrderReference
Object
-
Optional. Order Reference Object. Default: null
ContractDocumentReference
Array
-
Optional. Array of Contract Document Reference Objects. Default: null
DocumentCurrencyCode
String
Enum: ISO code list 4217 alpha-3
Mandatory. Invoice currency code. The currency in which all Invoice amounts are given, except for the Total VAT amount in accounting currency. Default: "SAR".
TaxCurrencyCode
String
Enum: ISO code list 4217 alpha-3 Equal: "SAR"
Mandatory. Tax currency code. The currency used for VAT accounting and reporting purposes as accepted or required in the country of the Seller. Shall be used in combination with the Total VAT amount in accounting currency (BT-111). Default: "SAR".
AccountingSupplierParty
Object
-
Mandatory. Accounting Supplier Party Object
AccountingCustomerParty
Object
-
Mandatory. Accounting Customer Party Object
InvoiceLine
Array
-
Mandatory. Array of Invoice Line Item Objects
AllowanceCharge
Array
-
Conditional. Required in case of invoice level discount. Allowance Charge Object
TaxTotal
Array
-
Mandatory. Array of Tax Total Objects
LegalMonetaryTotal
Object
-
Mandatory. Legal Monetary Total Object
PaymentMeans
Array
-
Conditional. Required in case of Standard Tax Invoice, Standard Credit Note, Standard Debit Note, Simplified Credit Note and Simplified Debit Note. Not required in case of Simplified Tax Invoice. Array of Payment Means Object
CreditOrDebitValidationEnable
Boolean
-
To enable/disable validations on credit and debit notes. By default this field is always ‘TRUE’.
Note
-
Optional. Invoice note. A textual note that gives unstructured information that is relevant to the Invoice as a whole. Default: null
AdditionalDocumentReference
Array
NA
Read Only. Optional. Array of Additional Document Reference Objects. This array should contain:
1 Invoice counter value object (ICV both standard and simplified)
1 Previous invoice hash object (PIH both standard and simplified)
1 QR code object (QR only for simplified) Default: Clear will try to generate Invoice counter value, Previous invoice hash and QR Code based on the configuration.
QR is required in Phase I only for Simplified documents. ICV and PIH are required in Phase II.
Signature
Object
NA
Read Only. Optional. Signature Object. Default: Clear will try to generate a cryptographic stamp based on the configuration.
Invoice Type Code Object
value
String
Enum: 388, 383, 381, 386
Mandatory. A code specifying the functional type of the Invoice. The invoice type code must be equal to one of value from the subset of UN/CEFACT code list 1001, D.16B agreed for KSA electronic invoices. Allowed: 388 - Tax Invoice, 383 - Debit Note, 381 - Credit Note, 386 - Prepayment invoice (Advance invoice).
name
String
MinLen: 7
MaxLen: 7
regex: Numerals
Mandatory. A code of the invoice subtype and invoices transactions. The invoice transaction code must exist and respect the following structure: NNPNESB where - NN (positions 1 and 2) = invoice subtype: - 01 for tax invoice - 02 for simplified tax invoice. P (position 3) = 3rd Party invoice transaction, 0 for false, 1 for true N (position 4) = Nominal invoice transaction, 0 for false, 1 for true E (position 5) = Exports invoice transaction, 0 for false, 1 for true S (position 6) = Summary invoice transaction, 0 for false, 1 for true B (position 7) = Self billed invoice. Self-billing is not allowed (KSA-2, position 7 cannot be ""1"") for export invoices (KSA-2, position 5 = 1).
For simplified tax invoices and associated credit notes and debit notes (KSA-2, position 1 and 2 = 02), only the following are accepted: third party (KSA-2, position 3 = 1), nominal supply (KSA-2, position 4 = 1) and summary transactions (KSA-2,, position 6 = 1) XC
Code (Name)
String
Allowed values:
388 - Tax Invoice,
383 - Debit Note,
381 - Credit Note,
386 - Prepayment invoice (Advance invoice).
For Standard Tax Invoice (B2B) , name is 0100000
For Standard 3rd party Invoice (B2B) , name is 0110000
For Standard Nominal Invoice (B2B) , name is 0101000
For Standard Export Invoice (B2B) , name is 0100100
For Standard summary Invoice (B2B) , name is 0100010
For Standard Self Billing Invoice (B2B) , name is 0100001
For Prepayment Tax Invoice (B2B) , name is 0100000
For Simplified Tax Invoice (B2C) , name is 0200000
For Simplified 3rd party Invoice (B2C) , name is 0210000
For Simplified Nominal Invoice (B2C) , name is 0201000
For Simplified summary Invoice (B2C) , name is 0200010
For Prepayment Simplified Tax Invoice (B2C) , name is 0200000
Delivery Object
ActualDeliveryDate
String
Format: YYYY-MM-DD
Conditional. Supply date (gregorian calendar). The tax invoice ((invoice type code (BT-30) = 388) & (invoice transaction code (KSA-2) has “01” as first 2 digits)) must contain the supply date (KSA-5).
The date when the supply is performed. For credit and debit notes, it acts as the original supply date.
If the invoice contains a supply end date (KSA-2424), then the invoice must contain a supply date (KSA-5).
LatestDeliveryDate
String
Format: YYYY-MM-DD
Optional. Supply end date. Calendar field "End Date" for Continuous Supplies.
If the invoice contains a supply end date (KSA-2424), then this date must be greater than the supply date (KSA-5).
Default: null
Billing Reference Object
InvoiceDocumentReference
Object
-
Conditional. Required only in case the invoice type is Debit Note or Credit Note. Not required if the invoice type is Tax Invoice. Invoice Document Reference Object
InvoiceDocumentReference.ID
-
Conditional. Required only in case the invoice type is Debit Note or Credit Note. Not required if the invoice type is Tax Invoice. The sequential number (Invoice number BT-1) of the original invoice(s) that the credit/debit note is related to.
Order Reference Object
Param Name
Type
Validation
Description
ID
-
Optional. An identifier of a referenced purchase order, issued by the Buyer. Default: null
Contract Document Reference Object
Accounting Supplier Party Object
Party
Object
-
Mandatory. Supplier Party Object.
Party.PartyLegalEntity
Object
-
Mandatory. Seller Party Legal Entity Object
Party.PartyTaxScheme
Object
-
Conditional. The invoice must contain the seller VAT registration number (BT-31) and/or seller group VAT registration number (KSA-18). Seller VAT Object.
Party.PartyTaxScheme.CompanyID
String
Must contain 15 digits. The first and the last digits are “3”.
Mandatory. Seller VAT identifier - taxpayer entity Also known as Seller VAT identification number.
Party.PartyTaxScheme.TaxScheme
Object
-
Mandatory. Seller Party Tax Scheme object.
Party.PartyTaxScheme.TaxScheme.ID
String
Equal: "VAT"
Mandatory. Tax Scheme ID should be "VAT".
Party.PartyIdentification
Object
-
Mandatory. Supplier Party Identification Object.
Party.PartyIdentification.ID
Object
-
Mandatory. Supplier Party Identification ID Object.
Party.PartyIdentification.ID.value
String
Alphanumeric
Mandatory in Phase 2 - ONLY one of the Other seller ID from the below list:
Commercial registration number with "CRN" as schemeID
Momra license with "MOM" as schemeID
MLSD license with "MLS" as schemeID
Sagia license with "SAG" as schemeID
Other OD with "OTH" as schemeID
Party.PartyIdentification.ID.schemeID
String
Enum: CRN/MOM/MLS/SAG/OTH
Mandatory in Phase 2 - Other seller ID is one of the list:
"CRN" - Commercial registration number,
"MOM" - Momra license,
"MLS" - MLSD license,
"SAG" - Sagia license,
"OTH" - Other ID
Party.PostalAddress
Object
-
Mandatory. Seller Postal Address object. Seller address must contain additional number, street name, building number, postal code, city, Neighborhood, country code. For more information please access this link: https://www.address.gov.sa/en/a ddress-format/overview
Party.PostalAddress.StreetName
-
Mandatory. Seller address line 1 - the main address line in an address.
Party.PostalAddress.AdditionalStreetName
-
Optional. Seller address line 2 - an additional address line in an address that can be used to give further details supplementing the main line. Default: null
Party.PostalAddress.BuildingNumber
"Numerals MinLen: 4 MaxLen: 4"
Mandatory. Seller address building number. The seller address building number must contain 4 digits..
Party.PostalAddress.PlotIdentification
"Numerals MinLen: 4 MaxLen: 4"
Optional. Seller address additional number. Seller Address Additional number must be 4 digits.
Party.PostalAddress.CityName
-
Mandatory. The common name of the city, town or village, where the Seller's address is located. This field is mandatory as per ZATCA data dictionary but invoices get approved without this field with a warning and hasn’t been enforced yet by govt. and hence the validation is not yet enforced by ClearTax.
Party.PostalAddress.CitySubdivisionName
-
Mandatory. The name of the subdivision of the Seller city, town, or village in which its address is located, such as the name of its district or borough. This field is mandatory as per ZATCA data dictionary but invoices get approved without this field with a warning and hasn’t been enforced yet by govt. and hence the validation is not yet enforced by ClearTax.
Party.PostalAddress.PostalZone
String
"Numerals MinLen: 5 MaxLen: 5"
Mandatory. Seller post code. Seller postal code (BT-38) must be 5 digits.
Party.PostalAddress.Country
Object
-
Mandatory. Seller country object.
Party.PostalAddress.Country.IdentificationCode
String
Equal: "SA"
Mandatory. Seller country code. Country codes in an invoice MUST be coded using ISO code list 3166-1. The seller address country code (BT-40) must be “SA”.
Accounting Customer Party Object
Party
Object
-
Conditional. Required if it is a simplified tax invoice or an associated credit note or a debit note (KSA-2, position 1 and 2 = 02) AND the tax exemption reason code (BT-121) is equal with VATEX-SA-EDU or VATEX-SA-HEA. Required if it is a standard tax invoice or an associated credit note or a debit note.
Buyer Party Object.
For simplified documents, in case of private education and private healthcare to citizens, the Buyer name and Additional buyer ID is required only in Phase II. For standard documents, buyer details are mandatory in Phase I itself.
Party.PartyLegalEntity
Object
-
Conditional. Required if it is a simplified tax invoice or an associated credit note or a debit note (KSA-2, position 1 and 2 = 02) AND the tax exemption reason code (BT-121) is equal with VATEX-SA-EDU or VATEX-SA-HEA. Required if it is a standard tax invoice or an associated credit ntoe or a debit note.
Buyer Party Legal Entity Object
Party.PartyLegalEntity.RegistrationName
-
Mandatory for Standard Invoices, Conditional. Required if it is a simplified tax invoice or an associated credit note or a debit note (KSA-2, position 1 and 2 = 02) AND the tax exemption reason code (BT-121) is equal with VATEX-SA-EDU or VATEX-SA-HEA. Required if it is a standard tax invoice or an associated credit note or a debit note.
The full name of the Buyer.
Party.PartyTaxScheme
Object
-
Conditional. Required if invoice type is standard and not export. Buyer Party Tax Schema object.
Party.PartyTaxScheme.CompanyID
String
If not export, numerals
minLen: 15
maxLen: 15
first digit: 3
last digit: 3
Conditional. Required if invoice type is standard. The Buyer's VAT identifier (also known as Buyer VAT identification number).
If it exists in the invoice, and If it is not an export invoice (KSA-2, position 5 is false), the buyer VAT registration number (BT-48) must contain 15 digits. The first digit and the last digit is “3”.
If it is an export invoice (KSA-2, position 5 is true), the buyer VAT registration number (BT-48) and the buyer group VAT registration number (KSA-20) must not exist in the invoice.
Party.PartyTaxScheme.TaxScheme
Object
-
Conditional. Required if invoice type is standard and not export. Optional for Simplified. Buyer Party Tax Schema ID object.
Party.PartyTaxScheme.TaxScheme.ID
String
Equal: "VAT"
Mandatory. Tax Scheme ID should be "VAT".
Party.PartyIdentification
Object
-
Conditional. Required if it is a simplified tax invoice or an associated credit note or a debit note (KSA-2, position 1 and 2 = 02) AND the tax exemption reason code (BT-121) is equal with VATEX-SA-EDU or VATEX-SA-HEA. Required if it is a standard tax invoice or an associated credit note or a debit note. Buyer Party Identification Object.
Party.PartyIdentification.ID
Object
-
Conditional. Required if it is a simplified tax invoice or an associated credit note or a debit note (KSA-2, position 1 and 2 = 02) AND the tax exemption reason code (BT-121) is equal with VATEX-SA-EDU or VATEX-SA-HEA. Required if it is a standard tax invoice or an associated credit note or a debit note. Buyer Party Identification ID Object.
Party.PartyIdentification.ID.value
String
Alphanumeric
Conditional. Other Buyer ID must be one of the following list:
National ID with "NAT" as schemeID
Tax Identification Number "TIN" as schemeID
Iqama Number with "IQA" as schemeID
Passport ID with "PAS" as schemeID
Commercial registration number with "CRN" as schemeID
Momra license with "MOM" as schemeID
MLSD license with "MLS" as schemeID
Sagia license with "SAG" as schemeID
GCC ID with "GCC" as schemeID
Other ID with "OTH" as schemeID
If the tax exemption reason code (BT-121) is equal to VATEX-SA- EDU or VATEX-SA-HEA, then the other buyer ID (BT-46) is mandatory and must be national ID (BT-46-1 = NAT)
Party.PartyIdentification.ID.SchemeID
String
Enum: NAT/TIN/IQA/PAS/CRN/MOM/MLS/SAG/GCC/OTH
Mandatory in Phase 2 - Other Buyer ID must be one of the following list:
"NAT" - National ID
"TIN" - Tax Identification Number
"IQA" - Iqama Number
"PAS" - Passport ID
"CRN" - Commercial registration number
"MOM" - Momra license
"MLS" - MLSD license
"SAG" - Sagia license
"GCC" - GCC ID
"OTH" - Other ID
Party.PostalAddress
Object
-
"Conditional. An Invoice shall contain the Buyer postal address (BG-8). Not applicable for simplified tax invoices and associated credit notes and debit notes (KSA-2, position 1 and 2 = 02).
Buyer address must contain a street (BT-50), city (BT-52), postal code (BT-53), country code (BT- 55). This rule does not apply on the simplified tax invoices and associated credit notes and debit notes (KSA-2, position 1 and 2 = 02)."
Party.PostalAddress.StreetName
-
Buyer address line 1 - the main address line in an address. Mandatory for Standard Invoices, Optional for Simplified Invoices.
Party.PostalAddress.AdditionalStreetName
-
Optional. Buyer address line 2 - an additional address line in an address that can be used to give further details supplementing the main line.
Party.PostalAddress.BuildingNumber
-
Buyer address building number.
Mandatory for Standard Invoices, Optional for Simplified Invoices.
Party.PostalAddress.PlotIdentification
"Numerals
MinLen: 4
MaxLen: 4"
Buyer address additional number. Optional for both Standard Invoices and Simplified Invoices.
Party.PostalAddress.CityName
-
The common name of the city, town or village, where the Buyer's address is located. Mandatory for Standard Invoices, Optional for Simplified Invoices.
Party.PostalAddress.CitySubdivisionName
-
The name of the subdivision of the Buyer city, town, or village in which its address is located, such as the name of its district or borough. Mandatory for Standard Invoices, Optional for Simplified Invoices.
Party.PostalAddress.PostalZone
String
"If buyer country code is SA, Numerals
MinLen: 5
MaxLen: 5
Else no validation"
Buyer postal code. Mandatory for Standard Invoices, Optional for Simplified Invoices.
Party.PostalAddress.CountrySubentity
-
Buyer country subdivision. Optional for both Standard Invoices and Simplified Invoices.
Party.PostalAddress.Country
Object
-
Buyer country object. Mandatory for Standard Invoices, Optional for Simplified Invoices.
Party.PostalAddress.Country.IdentificationCode
String
Enum: ISO code list 3166-1
-->Mandatory. Buyer country code. Country codes in an invoice MUST be coded using ISO code list 3166-1. If the buyer country code (BT-55) exists in the invoice, and If it is not an export invoice (KSA-2, position 5 is false), then the country code (BT-55) must be “SA”. For more information please access this link: https://www.address.gov.sa/en/address-format/overview Mandatory for Standard Invoices, Optional for Simplified Invoices.
Invoice Line Object
ID
Number
-
"Mandatory. Each Invoice line (BG-25) shall have an Invoice line identifier (BT-126).
A unique identifier for the individual line within the Invoice.
An Invoice shall have at least one Invoice line (BG-25)"
Item
Object
-
Mandatory. Each Invoice line (BG-25) shall contain the Item name (BT-153).
Item.Name
-
"Mandatory. Each Invoice line (BG-25) shall contain the Item name (BT-153).
The description of goods or services as per Article 53 of the VAT Implementing Regulation". " In case of advance invoices the item name should always be “Prepayment adjustment”.
Item.BuyersItemIdentification
Object
-
Optional
Item.BuyersItemIdentification.ID
-
Optional. An identifier, assigned by the Buyer, for the item.
Item.SellersItemIdentification
Object
-
Optional
Item.SellersItemIdentification.ID
-
Optional. An identifier, assigned by the Seller, for the item.
Item.StandardItemIdentification
Object
-
Optional
Item.StandardItemIdentification.ID
-
"Optional. An item identifier based on a registered scheme.
This should include the product code type and the actual code. This list includes UPC (11 digit, 12 digit, 13 digit EAN), GTIN (14 digit), Customs HS Code and multiple other codes"
Item.ClassifiedTaxCategory
Object
-
Mandatory
Item.ClassifiedTaxCategory.ID
String
"Mandatory. Each Invoice line (BG-25) shall be categorized with an Invoiced item VAT category code (BT-151).
The VAT category code for the invoiced item.
An Invoice that contains a VAT breakdown group (BG-23) with a VAT category code (BT-118) ""Not subject to VAT"" shall not contain an Invoice line (BG-25) where the Invoiced item VAT category code (BT-151) is not ""Not subject to VAT"".
Invoice tax categories MUST be coded using UNCL5305 code list
VAT category code must contain one of the values (S, Z, E, O)."
Item.ClassifiedTaxCategory.Percent
String
"Min: 0.00
Max: 100.00"
"Mandatory. The VAT rate, represented as percentage that applies to the invoiced item as per Article 53 of the VAT Implementing Regulation
In an Invoice line (BG-25) where the Invoiced item VAT category code (BT-151) is ""Zero rated"" the Invoiced item VAT rate (BT-152) shall be 0 (zero). In an Invoice line (BG-25) where the Invoiced item VAT category code (BT-151) is ""Exempt from VAT"", the Invoiced item VAT rate (BT-152) shall be 0 (zero). An Invoice line (BG-2525) where the VAT category code (BT-151151) is ""Not subject to VAT"" shall not contain an Invoiced item VAT rate (BT-152152).
The VAT rates (BT-96119, BT-152) must be from 0.00 to 100.00, with maximum two decimals. Only numerals are accepted, the percentage symbol (%) is not allowed.
All the document amounts and quantities must be positive."
Item.ClassifiedTaxCategory.TaxScheme
Object
-
Mandatory. Tax scheme object.
Item.ClassifiedTaxCategory.TaxScheme.ID
String
-
Mandatory element. Use “VAT”
Price
Object
-
Mandatory. Each Invoice line shall contain the Item net price
Price.AllowanceCharge
Object
-
Conditional
Price.AllowanceCharge.ChargeIndicator
String
Equal: false
"Conditional.
An indicator that this AllowanceCharge describes a discount. The value of this tag indicating discount (Allowance) must be ""false"". This is in the context of the line item price level (not the line item level).
Charge on price level (BG-29) is NOT allowed. Only value 'false' allowed."
Price.AllowanceCharge.BaseAmount
Object
-
Conditional
Price.AllowanceCharge.BaseAmount.value
Number
-
"Conditional.
The unit price, exclusive of VAT, before subtracting Item price discount.
All the document amounts and quantities must be positive."
Price.AllowanceCharge.BaseAmount.currencyID
String
Enum: ISO code list 4217 alpha-3
Conditional. Required if parent context exists. Currency for item gross prices. This is in the context of the line item price level (not the line item level).
Price.AllowanceCharge.Amount
Object
- -
Conditional
Price.AllowanceCharge.Amount.value
Number
-
"Conditional.
The total discount subtracted from the Item gross price to calculate the Item net price. Only applies if the discount is provided per unit and if it is not included in the Item gross price. This is in the context of the line item price level (not the line item level).
All the document amounts and quantities must be positive."
Price.AllowanceCharge.Amount.currencyID
String
Enum: ISO code list 4217 alpha-3
Conditional. Required if parent context exists. Currency for item price discount
Price.PriceAmount
Object
-
Mandatory. This is item net price which is the price of an item, exclusive of VAT, after subtracting item price discount.
The Item net price has to be equal with the Item gross price minus the Item price discount.
Price.PriceAmount.value
Number
-
Mandatory. Value of item net price.
Price.PriceAmount.currencyID
String
Enum: ISO code list 4217 alpha-3
Optional. Currency for item net price. Will be considered as SAR if not provided in the payload as it is a mandatory field to be sent to ZATCA
Price.BaseQuantity
Object
-
Optional. Invoice line price base quantity.
Price.BaseQuantity.value
Number
-
"Optional. The number of item units to which the price applies.
All the document amounts and quantities must be positive."
Price.BaseQuantity.unitCode
String
Optional. Item price base quantity unit code.
DocumentReference
Object
-
Optional. Reference details of the advance invoice to be adjusted. Provide these details only if adjustment is done.
DocumentReference.ID
String
-
Conditional. The document ID of the advance invoice/prepayment receipt. Required only in case of adjustment invoices and if prepayment document reference is present.
DocumentReference.UUID
String
-
Conditional. The UUID of the advance invoice/prepayment receipt. Required only in case of adjustment invoices and if prepayment document reference is present.
DocumentReference.IssueDate
Date
-
Conditional. The Document Date of the advance invoice/prepayment receipt and has to be provided if prepayment document reference is present.
DocumentReference.IssueTime
String
Format: HH:mm:ss (24 hr format)
Conditional. The Document Time of the advance invoice/prepayment receipt and has to be provided if prepayment document reference is present.
DocumentReference.InvoiceTypeCode
String
The value can only be 386
Conditional. The value of invoice type code in the advance invoice/prepayment receipt and should be 386.
InvoicedQuantity
Object
-
Mandatory. The quantity of items object
InvoicedQuantity.value
Number
-
"Mandatory. Each Invoice line shall have an Invoiced quantity.
The quantity of items (goods or services) that is charged in the Invoice line.
All the document amounts and quantities must be positive." Unlimited decimal places allowed to facilitate accurate calculations. This is always zero in case of adjustment invoices where reference is to an advance invoice/prepayment receipt.
InvoicedQuantity.unitCode
String
Optional. The unit of measure that applies to the invoiced quantity.
AllowanceCharge[]
Array
-
"Conditional. Required only if there is invoice line item level allowance.
One or more Invoice level allowance charge objects."
AllowanceCharge[].ChargeIndicator
String
-
Conditional. Required in case of Standard Tax Invoice if parent context exists. Optional in the case of other standard and simplified documents.
An indicator that this AllowanceCharge describes a discount. The value of this tag indicating discount (Allowance) must be "false".
Allowance Indicator value MUST equal to 'false'
AllowanceCharge[].BaseAmount
Object
-
Conditional. Allowance base amount (BT-93, BT-137) must be provided when allowance percentage (BT-94, BT- 138) is provided.
AllowanceCharge[].BaseAmount.value
Number
-
Conditional. Allowance base amount (BT-93, BT-137) must be provided when allowance percentage (BT-94, BT- 138) is provided.
The base amount that may be used, in conjunction with the Invoice line allowance percentage, to calculate the Invoice line allowance amount.
The allowed maximum number of decimals for the Invoice line allowance base amount (BT- 137) is 2.
All the document amounts and quantities must be positive.
AllowanceCharge[].BaseAmount.currencyID
String
Enum: ISO code list 4217 alpha-3
Conditional. Required if parent context exists.
AllowanceCharge[].MultiplierFactorNumeric
Number
"Min: 0.00
Max: 100.00"
Conditional. Required in case of Standard Tax Invoice if parent context exists. Optional in case of other standard and simplified documents.
The percentage that may be used, in conjunction with the Invoice line allowance base amount, to calculate the Invoice line allowance amount.
The allowance percentage values (BT-94, BT-138) must be from 0.00 to 100.00, with maximum two decimals. Only numerals are accepted, the percentage symbol (%) is not allowed.
Allowance percentage (BT-94, BT-138) must be provided when the allowance base amount (BT-93, BT-137) is provided.
AllowanceCharge[].Amount
Object
-
Mandatory. Each Invoice line allowance (BG-27) shall have an Invoice line allowance amount (BT- 136).
AllowanceCharge[].Amount.value
Number
-
Mandatory. Each Invoice line allowance (BG-27) shall have an Invoice line allowance amount (BT- 136).
The amount of an allowance, without VAT.
Allowance amount (BT- 92, BT-136) must equal base amount (BT-93, BT- 137) * percentage (BT-94, BT-138) / 100 if base amount and percentage exists.
The allowed maximum number of decimals for the Invoice line allowance amount (BT-136) is 2.
All the document amounts and quantities must be positive.
AllowanceCharge[].Amount.currencyID
String
Enum: ISO code list 4217 alpha-3
Conditional. Required if parent context exists.
AllowanceCharge[].AllowanceChargeReason
-
Conditional. Each Invoice line allowance (BG-27) shall have an Invoice line allowance reason (BT139) or an Invoice line allowance reason code (BT-140). This is not applicable for Invoice line charge.
AllowanceCharge[].AllowanceChargeReasoncode
String
-
Conditional. Each Invoice line allowance (BG-27) shall have an Invoice line allowance reason (BT139) or an Invoice line allowance reason code (BT-140). This is not applicable for Invoice line charge.
LineExtensionAmount
Object
-
Mandatory. Invoice line extension amount object.
LineExtensionAmount.value
Number
-
Mandatory. Each Invoice line shall have an Invoice line net amount
The total amount of the Invoice line, including allowances (discounts). It is the item net price multiplied with the quantity. The amount is “net” without VAT.
Invoice line net amount must equal (Invoiced quantity * (Item net price / item price base quantity))- Sum of invoice line allowance amount
The allowed maximum number of decimals for the Invoice line net amount is 2.
All the document amounts and quantities must be positive. This is always zero in case of adjustment invoices where reference is to an advance invoice/prepayment receipt.
LineExtensionAmount.currencyID
String
Enum: ISO code list 4217 alpha-3
Conditional. Required if parent context exists. Currency for invoice line net amount
TaxTotal
Object
-
Conditional. Required only in case of standard documents. Not required for simplified documents.
TaxTotal.TaxAmount
Object
-
Conditional. VAT amount as per Article 53
TaxTotal.TaxAmount.value
Number
-
Conditional. The line VAT amount (KSA-11) is mandatory for tax invoice and associated credit notes and debit notes (KSA-2, position 1 and 2 = 01).
VAT amount as per Article 53
VAT amount at line level (KSA-11) must have a maximum two decimals.
The line VAT amount (KSA-11) must be Invoice line net amount (BT-131) x (Line VAT rate (BT- 152)/100).
All the document amounts and quantities must be positive. This is always zero in case of adjustment invoices where reference is to an advance invoice/prepayment receipt.
TaxTotal.TaxAmount.currencyID
String
Enum: ISO code list 4217 alpha-3
Conditional. Required if parent context exists. Currency for VAT line amount
TaxTotal.RoundingAmount
Object
-
Conditional. Line amount inclusive VAT
TaxTotal.RoundingAmount.value
Number
-
Conditional. The line amount with VAT (KSA- 12) is mandatory for tax invoice and associated credit notes and debit notes (KSA-2, position 1 and 2 = 01).
Line amount inclusive VAT.
Amount with VAT at line level (KSA-12) must have a maximum two decimals.
The line amount with VAT (KSA- 12) must be Invoice line net amount (BT-131) + Line VAT amount (KSA-11).
All the document amounts and quantities must be positive. This is always zero in case of adjustment invoices where reference is to an advance invoice/prepayment receipt.
TaxTotal.RoundingAmount.currencyID
String
Enum: ISO code list 4217 alpha-3
Conditional. Required if parent context exists. Currency for line amount inclusive VAT
TaxSubtotal[]
Array
-
Optional. One or more Tax Subtotal objects. This will be auto-computed if not provided for all invoices except adjustment invoices. In case of adjustment invoices the values have to be provided explicitly.
TaxSubtotal[].TaxableAmount
Object
-
Optional.This will be auto-computed if not provided for all invoices except adjustment invoices. In case of adjustment invoices the values have to be provided explicitly.
TaxSubtotal[].TaxableAmount.value
Number
-
Optional. The sum total of VAT category taxable amount subject to specific VAT Category code of the associated Prepayment invoice(s).
The allowed maximum number of decimals for the VAT category taxable amount is 2. Will be auto-computed if not provided for all invoices except adjustment invoices. In case of adjustment invoices the values have to be provided explicitly.
TaxSubtotal[].TaxableAmount.currencyID
String
Enum: ISO code list 4217 alpha-3
Conditional. Required if parent context exists. Currency for VAT category taxable amount.
TaxSubtotal[].TaxAmount
Object
-
Optional. Will be auto-computed if not provided for all invoices except adjustment invoices. In case of adjustment invoices the values have to be provided explicitly.
TaxSubtotal[].TaxAmount.value
Number
-
"Optional. Calculated by multiplying the VAT category taxable amount with the VAT category rate for the relevant VAT category.
VAT category tax amount = VAT category taxable amount x (VAT category rate / 100), rounded to two decimals.The sum total of VAT category tax amount subject to specific VAT Category code of the associated Prepayment invoice(s).
The allowed maximum number of decimals for the VAT category tax amount is 2.Will be auto-computed if not provided for all invoices except adjustment invoices. In case of adjustment invoices the values have to be provided explicitly.
TaxSubtotal[].TaxAmount.currencyID
String
Enum: ISO code list 4217 alpha-3
Conditional. Required if parent context exists. Currency for category tax amount.
TaxSubtotal[].TaxCategory
Object
-
Optional. Required for adjustment invoices.
TaxSubtotal[].TaxCategory.ID
String
Enum: S/Z/E/O
"Optional. The VAT category code of the associated Prepayment invoice(s). This is only required for prepayment adjustment invoices.
TaxSubtotal[].TaxCategory.Percent
String
"Min: 0.00
Max: 100.00"
"Optional.
The VAT rate of the specific VAT category code of the associated Prepayment invoice(s).
The VAT rates must be from 0.00 to 100.00, with a maximum of two decimals. Only numerals are accepted, the percentage symbol (%) is not allowed.This is only required for prepayment adjustment invoices.
TaxSubtotal[].TaxCategory.TaxExemptionReasonCode
String
-
"Conditional. Required if tax category is Z/E/O.
A coded statement of the reason for why the amount is exempted from VAT.
A VAT breakdown with VAT Category code ""Standard rate"" shall not have a VAT exemption reason Code. A VAT breakdown with VAT Category code ""Exempt from VAT"" shall have a VAT exemption reason code or a VAT exemption reason text. A VAT breakdown with VAT Category code ""Not subject to VAT"" shall have a VAT exemption reason code , meaning ""Not subject to VAT"" or a VAT exemption reason text "" Not subject to VAT"" (or the equivalent standard text in another language). A VAT breakdown with VAT Category code ""Zero rated"" shall have a VAT exception reason code and VAT exception reason text.
VAT exemption reason code must exists in the invoice, the codes Z, E must have Tax exemption (or exceptions) reason code and text - specific to Saudi Arabia"
TaxSubtotal[].TaxCategory.TaxExemptionReason
Dual String Object
-
"Conditional. Required if tax category is Z/E/O.
A textual statement of the reason why the amount is exempted from VAT or why no VAT is being charged
A VAT breakdown with VAT Category code ""Standard rate"" shall not have a VAT exemption reason text. A VAT breakdown with VAT Category code ""Exempt from VAT"" shall have a VAT exemption reason code or a VAT exemption reason text. A VAT breakdown with VAT Category code ""Not subject to VAT"" shall have a VAT exemption reason code, meaning ""Not subject to VAT"" or a VAT exemption reason text ""Not subject to VAT"" (or the equivalent standard text in another language). A VAT breakdown with VAT Category code ""Zero rated"" shall have a VAT exception reason code and VAT exception reason text."
TaxSubtotal[].TaxCategory.TaxScheme
Object
-
Optional. Required for prepayment adjustment invoices
TaxSubtotal[].TaxCategory.TaxScheme.ID
String
Equal: "VAT"
Optional. Use “VAT” for prepayment adjustment invoices.
Allowance Charge Object
ChargeIndicator
String
-
"Mandatory. An indicator that this AllowanceCharge describes a discount. The value of this tag indicating discount (Allowance) must be ""false""."
BaseAmount
Object
-
"Conditional. Allowance base amount (BT-93, BT-137) must be provided when allowance percentage (BT-94, BT- 138) is provided. Allowance Charge Base Amount object."
BaseAmount.value
Number
Positive number with maximum 2 decimal places.
"Conditional. Required if parent context exists.
The base amount that may be used, in conjunction with the Invoice line allowance percentage, to calculate the Invoice line allowance amount.
The allowed maximum number of decimals for the Document level allowance base amount (BT-93) is 2.
All the document amounts and quantities must be positive. "
BaseAmount.currencyID
String
Enum: ISO code list 4217 alpha-3
Conditional. Required if parent context exists. Currency for invoice line allowance base amount
MultipleFactorNumeric
Number
"Min: 0.00
Max: 100.00"
"Conditional. Allowance percentage (BT-94, BT-138) must be provided when the allowance base amount (BT-93, BT-137) is provided.
The allowance percentage values (BT-94, BT-138) must be from 0.00 to 100.00, with maximum six decimals. Only numerals are accepted, the percentage symbol (%) is not allowed.
The percentage that may be used, in conjunction with the document level allowance base amount, to calculate the document level allowance amount."
Amount
Object
-
Mandatory. Allowance Charge Amount object.
Amount.value
Number
Positive number with maximum 2 decimal places.
"Mandatory. Each Document level allowance (BG-20) shall have a Document level allowance amount (BT-92).
The allowed maximum number of decimals for the Document level allowance amount (BT-92) is 2.
Allowance amount (BT- 92, BT-136) must equal base amount (BT-93, BT- 137) * percentage (BT-94, BT-138) / 100 if base amount and percentage exists.
All the document amounts and quantities must be positive.
The amount of an allowance, without VAT."
Amount.currencyID
String
Enum: ISO code list 4217 alpha-3
Mandatory. Currency for line allowance amount
TaxCategory
Object
-
Mandatory. Allowance Charge Tax Category Object
TaxCategory.ID
String
"Mandatory. Each Document level allowance (BG-20) shall have a Document level allowance VAT category code (BT-95).
An Invoice that contains a VAT breakdown group (BG-23) with a VAT category code (BT-118) ""Not subject to VAT"" shall not contain Document level allowances (BG-20) where Document level allowance VAT category code (BT-95) is not ""Not subject to VAT"".
VAT category code must contain one of the values (S, Z, E, O).
A coded identification of what VAT category applies to the document level allowance."
TaxCategory.Percent
Number
"Min: 0.00
Max: 100.00"
"Mandatory. The VAT rate, represented as percentage that applies to the document level allowance.
In a Document level allowance (BG-20) where the Document level allowance VAT category code (BT-95) is ""Standard rated"" the Document level allowance VAT rate (BT-96) shall be greater than zero. In a Document level allowance (BG-20) where the Document level allowance VAT category code (BT-95) is ""Zero rated"" the Document level allowance VAT rate (BT-96) shall be 0 (zero). In a Document level allowance (BG-20) where the Document level allowance VAT category code (BT-95) is ""Exempt from VAT"", the Document level allowance VAT rate (BT-96) shall be 0 (zero). A Document level allowance (BG-2020) where VAT category code (BT-9595) is ""Not subject to VAT"" shall not contain a Document level allowance VAT rate (BT-96).
The VAT rates (BT-96119, BT-152) must be from 0.00 to 100.00, with maximum two decimals. Only numerals are accepted, the percentage symbol (%) is not allowed."
TaxCategory.TaxScheme
Object
-
Mandatory. Allowance Charge Tax Category Tax Scheme object.
TaxCategory.TaxScheme.ID
String
Equal: "VAT"
Mandatory. Use “VAT”
Tax Total Object
TaxAmount
Object
-
Mandatory.
TaxAmount.value
Number
-
"Mandatory. The total VAT amount for the Invoice.
The Invoice total VAT amount is the sum of all VAT category tax amounts.
The VAT total amount expressed in the accounting currency accepted or required in the country of the Seller. To be used when the VAT accounting currency (BT-6) differs from the Invoice currency code (BT-5). The VAT amount in accounting currency is not used in the calculation of the Invoice totals.
The allowed maximum number of decimals for the Invoice total VAT amount is 2. The allowed maximum number of decimals for the Invoice total VAT amount in accounting currency is 2"
TaxAmount.currencyID
String
Enum: ISO code list 4217 alpha-3
"Conditional. Required if parent context exists. Currency for total VAT amount Currency for invoice total VAT amount in accounting currency"
TaxSubtotal[]
Array
-
Mandatory. One or more Tax Subtotal objects.
TaxSubtotal[].TaxableAmount
Object
-
Mandatory. Each VAT breakdown shall have a VAT category taxable amount.
TaxSubtotal[].TaxableAmount.value
Number
-
"Mandatory. Each VAT breakdown shall have a VAT category taxable amount.
Sum of all taxable amounts subject to a specific VAT category code and VAT category rate (if the VAT category rate is applicable).
The sum of Invoice line net amount minus allowances on document level which are subject to a specific VAT category code and VAT category rate (if the VAT category rate is applicable).
In a VAT breakdown where the VAT category code is ""Not subject to VAT"" the VAT category taxable amount shall equal the sum of Invoice line net amounts minus the sum of Document level allowance amounts where the VAT category codes are ""Not subject to VAT"".
The allowed maximum number of decimals for the VAT category taxable amount is 2."
TaxSubtotal[].TaxableAmount.currencyID
String
Enum: ISO code list 4217 alpha-3
Conditional. Required if parent context exists. Currency for VAT category taxable amount
TaxSubtotal[].TaxAmount
Object
-
Mandatory. Each VAT breakdown shall have a VAT category tax amount.
TaxSubtotal[].TaxAmount.value
Number
-
"Mandatory. Each VAT breakdown shall have a VAT category tax amount.
Calculated by multiplying the VAT category taxable amount with the VAT category rate for the relevant VAT category.
VAT category tax amount = VAT category taxable amount x (VAT category rate / 100), rounded to two decimals.
The VAT category tax amount in a VAT breakdown where VAT category code is ""Standard rated"" shall equal the VAT category taxable amount multiplied by the VAT category rate. The VAT category tax amount in a VAT breakdown where VAT category code is ""Zero rated"" shall equal 0 (zero). The VAT category tax amount In a VAT breakdown where the VAT category code equals ""Exempt from VAT"" shall equal 0 (zero). The VAT category tax amount in a VAT breakdown where the VAT category code is ""Not subject to VAT"" shall be 0 (zero).
The allowed maximum number of decimals for the VAT category tax amount is 2."
TaxSubtotal[].TaxAmount.currencyID
String
Enum: ISO code list 4217 alpha-3
Conditional. Required if parent context exists. Currency for category tax amount
TaxSubtotal[].TaxCategory
Object
-
Mandatory.
TaxSubtotal[].TaxCategory.ID
String
"Mandatory. Each VAT breakdown shall be defined through a VAT category code.
Coded identification of a VAT category.
An Invoice that contains an Invoice line, a Document level allowance where the VAT category code is ""Zero rated"" shall contain in the VAT breakdown exactly one VAT category code equal with ""Zero rated"". An Invoice that contains an Invoice line, a Document level allowance where the VAT category code is ""Exempt from VAT"" shall contain exactly one VAT breakdown with the VAT category code equal to ""Exempt from VAT"". A VAT breakdown with VAT Category code ""Not subject to VAT"" shall have a VAT exemption reason code , meaning ""Not subject to VAT"" or a VAT exemption reason text "" Not subject to VAT"" (or the equivalent standard text in another language)."
TaxSubtotal[].TaxCategory.Percent
String
"Min: 0.00
Max: 100.00"
"Conditional. Each VAT breakdown shall have a VAT category rate, except if the Invoice is not subject to VAT.
The VAT rate, represented as percentage that applies for the relevant VAT category.
The VAT rates must be from 0.00 to 100.00, with maximum two decimals. Only numerals are accepted, the percentage symbol (%) is not allowed."
TaxSubtotal[].TaxCategory.TaxExemptionReasonCode
String
-
"Conditional. Required if tax category is Z/E/O.
A coded statement of the reason for why the amount is exempted from VAT.
A VAT breakdown with VAT Category code ""Standard rate"" shall not have a VAT exemption reason Code. A VAT breakdown with VAT Category code ""Exempt from VAT"" shall have a VAT exemption reason code or a VAT exemption reason text. A VAT breakdown with VAT Category code ""Not subject to VAT"" shall have a VAT exemption reason code , meaning ""Not subject to VAT"" or a VAT exemption reason text "" Not subject to VAT"" (or the equivalent standard text in another language). A VAT breakdown with VAT Category code ""Zero rated"" shall have a VAT exception reason code and VAT exception reason text.
VAT exemption reason code must exists in the invoice, the codes Z, E must have Tax exemption (or exceptions) reason code and text - specific to Saudi Arabia"
TaxSubtotal[].TaxCategory.TaxExemptionReason
-
"Conditional. Required if tax category is Z/E/O.
A textual statement of the reason why the amount is exempted from VAT or why no VAT is being charged
A VAT breakdown with VAT Category code ""Standard rate"" shall not have a VAT exemption reason text. A VAT breakdown with VAT Category code ""Exempt from VAT"" shall have a VAT exemption reason code or a VAT exemption reason text. A VAT breakdown with VAT Category code ""Not subject to VAT"" shall have a VAT exemption reason code, meaning ""Not subject to VAT"" or a VAT exemption reason text ""Not subject to VAT"" (or the equivalent standard text in another language). A VAT breakdown with VAT Category code ""Zero rated"" shall have a VAT exception reason code and VAT exception reason text."
TaxSubtotal[].TaxCategory.TaxScheme
Object
-
Mandatory.
TaxSubtotal[].TaxCategory.TaxScheme.ID
String
Equal: "VAT"
Mandatory element. Use “VAT”
Legal Monetary Total Object
LineExtensionAmount
Object
Mandatory
LineExtensionAmount.value
Number
-
Mandatory. Sum of all Invoice line net amounts in the Invoice without VAT
Sum of Invoice line net amount = Σ Invoice line net amount
The allowed maximum number of decimals for the Sum of Invoice line net amount is 2.
All the document amounts and quantities must be positive.
LineExtensionAmount.currencyID
String
Enum: ISO code list 4217 alpha-3
Conditional. Required if parent context exists. Currency for invoicetotal amount
AllowanceTotalAmount
Object
-
Conditional. Required if the allowance is provided.
AllowanceTotalAmount.value
Number
-
Conditional. Required if the allowance is provided. Sum of all allowances on document level in the Invoice.
Note: Allowances on line level are included in the Invoice line net amount which is summed up into the Sum of Invoice line net amount.
Sum of allowances on document level = Σ Document level allowance amount
The allowed maximum number of decimals for the Sum of allowances on document level is 2.
All the document amounts and quantities must be positive.
AllowanceTotalAmount.currencyID
String
Enum: ISO code list 4217 alpha-3
Conditional. Required if parent context exists. Currency for invoice total amount without VAT
TaxExclusiveAmount
Object
-
Mandatory. An Invoice shall have the Invoice total amount without VAT.
TaxExclusiveAmount.value
Number
-
"Mandatory. An Invoice shall have the Invoice total amount without VAT.
The total amount of the Invoice without VAT.
The allowed maximum number of decimals for the Sum of allowances on document level is 2.
All the document amounts and quantities must be positive."
TaxExclusiveAmount.currencyID
String
Enum: ISO code list 4217 alpha-3
Conditional. Required if parent context exists. Currency for invoice total amount without VAT
TaxInclusiveAmount
Object
-
Mandatory. An Invoice shall have the Invoice total amount with VAT.
TaxInclusiveAmount.value
Number
-
"Mandatory. An Invoice shall have the Invoice total amount with VAT.
The total amount of the Invoice with VAT. The Invoice total amount with VAT is the Invoice total amount without VAT plus the Invoice total VAT amount.
The allowed maximum number of decimals for the Sum of allowances on document level is 2.
All the document amounts and quantities must be positive."
TaxInclusiveAmount.currencyID
String
Enum: ISO code list 4217 alpha-3
Conditional. Required if parent context exists. Currency for invoice total amount with VAT
PrepaidAmount
Object
-
Conditional. Required only if there is advance paid.
PrepaidAmount.value
Number
-
"Conditional. Required only if there is advance paid.
The sum of amounts which have been paid in advance including VAT. This amount is subtracted from the invoice total amount with VAT to calculate the amount due for payment.
The allowed maximum number of decimals for the Sum of allowances on document level is 2.
All the document amounts and quantities must be positive."
PrepaidAmount.currencyID
String
Enum: ISO code list 4217 alpha-3
Conditional. Required if parent context exists. Currency for paid amount
PayableRoundingAmount
Number
PayableRoundingAmount = Payable Amount + PrepaidAmount - TaxInclusiveAmount
Optional. This is the amount which must be added to total in order to round off the payment amount to the payable amount expected from the buyer after accounting for halala differences.
PayableAmount
Object
-
Mandatory. An Invoice shall have the Amount due for payment.
PayableAmount.value
Number
-
Mandatory. An Invoice shall have the Amount due for payment.
The outstanding amount that is requested to be paid.
This amount is the Invoice total amount with VAT minus the paid amount that has been paid in advance. The amount is zero in case of a fully paid Invoice.
The allowed maximum number of decimals for the Sum of allowances on document level is 2.
All the document amounts and quantities must be positive.
PayableAmount.currecyID
String
Enum: ISO code list 4217 alpha-3
Conditional. Required if parent context exists. Currency for payable amount
Payment Means Object
PaymentMeansCode
String
Mandatory. The means, expressed as code, for how a payment is expected to be or has been settled.
A Payment instruction (BG-16) shall specify the Payment means type code (BT-81). Payment means in an invoice MUST be coded using UNCL4461 code list.
Payment means code (BT-81) in an invoice must contain one of the values: 10 - In cash, 30 - Credit, 42 - Payment to bank account , 48 - Bank card , 1 - Instrument not defined (Free text) .
In the simplified tax invoice and associated credit notes and debit notes (KSA-2, position 1 and 2 = 02) this value is optional.
InstructionNote
-
Conditional. Required in case of Debit and credit note (invoice type code (BT-3) is equal to 383 or 381).
Reasons for issuance of credit / debit note as per Article 40 (paragraph 1) of KSA VAT regulations, a Credit and Debit Note is issued for these 4 instances:
Cancellation or suspension of the supplies after its occurrence either wholly or partially (تم إلغاء أو وقف التوريد بعد حدوثه أو اعتباره كلياً أو جزئياً)
In case of essential change or amendment in the supply, which leads to the change of the VAT due (وجود تغيير أو تعديل جوهري في طبيعة التوريد بحيث يؤدي الى تغيير الضريبة المستحقة)
Amendment of the supply value which is pre-agreed upon between the supplier and consumer (تم الاتفاق على تعديل قيمة التوريد مسبقاً)
In case of goods or services refund (عند ترجيع السلع أو الخدمات)
In case of change in Seller's or Buyer's information (عند التعديل على بيانات المورد أو المشتري)
PayeeFinancialAccount
Object
-
Optional. Payee Financial Account Payment Note object. Default: null
PayeeFinancialAccount.PaymentNote
-
Optional. The payment terms, if mode of payment is credit. Free text. Default: null
Additional Document Reference Object
AdditionalDocumentReference[0].ID
String
Equal: "ICV"
Optional. Invoice counter value. Default: "ICV"
AdditionalDocumentReference[0].UUID
String
Numeric
Optional. Invoice counter value. Default: Clear will try to generate the ICV based on configuration.
AdditionalDocumentReference[1].ID
String
Equal: "PIH"
Optional. Previous Invoice Hash. Default: "PIH"
AdditionalDocumentReference[1].Attachment
Object
-
Optional. Attachment object. Default: Clear will try to generate based on configuration.
AdditionalDocumentReference[1].Attachment.EmbeddedDocumentBinaryObject
Object
-
Optional. Embedded Document Binary object. Default: Clear will try to generate based on configuration.
AdditionalDocumentReference[1].Attachment.EmbeddedDocumentBinaryObject.mimeCode
String
Equal: "text/plain"
Optional. Mime type of the embedded document binary object for Previous invoice hash. Default: "text/plain"
AdditionalDocumentReference[1].Attachment.EmbeddedDocumentBinaryObject.value
String
-
"Optional. The base64 encoded SHA256 hash of the previous invoice. This hash will be computed from the business payload of the previous invoice: UBL XML of the previous invoice without tags for QR code (KSA-14) and cryptographic stamp (KSA-15).
For the first invoice, the previous invoice hash is ""NWZlY2ViNjZmZmM4NmYzOGQ5NTI3ODZjNmQ2OTZjNzljMmRiYzIzOWRkNGU5MWI0NjcyOWQ3M2EyN2ZiNTdlOQ=="", the equivalent for base64 encoded SHA256 of ""0"" (zero) character.
Default: Clear will try to generate based on configuration."
AdditionalDocumentReference[2].ID
String
Equal: "QR"
Optional. QR Code. Default: "QR"
AdditionalDocumentReference[2].Attachment
Object
-
Optional. Attachment object. Default: Clear will try to generate based on configuration.
AdditionalDocumentReference[2].Attachment.EmbeddedDocumentBinaryObject
Object
-
Optional. Embedded Document Binary object. Default: Clear will try to generate based on configuration.
AdditionalDocumentReference[2].Attachment.EmbeddedDocumentBinaryObject.mimeCode
String
Equal: "text/plain"
"Optional. Mime type of the embedded document binary object for QR Code.
Mime code must be according to subset of IANA code list.
Default: ""text/plain"""
AdditionalDocumentReference[2].Attachment.EmbeddedDocumentBinaryObject.value
String
-
"Optional. QR code must contain:
Seller VAT number
Seller Name
VAT Total
Invoice Total (including VAT)
Invoice issue date and time
Hash of the XML invoice
Cryptographic stamp (For simplified tax invoices and associated notes, it will be applied by the seller's device. For the tax invoice and associated notes, it will be applied by ZATCA's portal)
Default: Clear will try to generate based on configuration."
Signature Object
ID
String
NA
Optional. Clear will try to generate this based on the configuration.
SignatureMethod
String
NA
Optional. Clear will try to generate this based on the configuration.
Validations
Validations on invoices/items, calculations, etc are as mentioned against each field.
Last updated