Try in playground

Saudi Arabia: fields

Every GETS field a Saudi document can carry, when it is required and the values it accepts.

  • Field is the name the Integration engine shows.
  • Requirement covers every document type, modifier and variant. Mandatory fields are always required and optional ones never are. Conditional fields are required only when the condition in their description is met.
  • Enums lists the values a field accepts when it takes only a fixed set.
  • To see the fields for one document type, modifier and variant next to a sample request, open List with sample request.

Payload fields

334 fields · conditional fields are required only when the condition in their description is met

DescriptionEnums
Invoice CurrencyMandatorystringDocument currency
Document NumberMandatorystringUnique document number
Document BaseMandatorystringThe base document type, such as tax_invoice or credit_note. Each country’s values are listed under Enums on its fields page.
tax_invoiceTax invoicecredit_noteCredit notedebit_noteDebit notesimplified_invoiceSimplified invoicesimplified_credit_noteSimplified credit notesimplified_debit_noteSimplified debit note
Issue DateMandatorydateDocument issue date
Issue TimeMandatorystringTime the document was issued, as hh:mm:ss, or hh:mm:ssZ in UTC. BR-KSA-70: the e-invoice must carry the issue time (KSA-25).
Tax Accounting CurrencyMandatorystringCurrency the VAT amounts are accounted in (BT-6). Always SAR in Saudi Arabia. BR-KSA-68 and BR-KSA-EN16931-02: the VAT accounting currency (BT-6) is required and must be SAR, whatever the document currency.
Invoice UUIDMandatorystringUnique identifier of the document (KSA-1), as a UUID. BR-KSA-03: every document must carry a UUID (KSA-1) made of letters, digits and dashes. Use a new one for each document. If you leave it out, header.documentId is used when it is a UUID.
Exchange RateConditionalnumberExchange rate when currency differs from tax currency Mandatory with the export modifier. Export requires exchange rate
Invoice Period EndConditionaldateEnd date of the invoiced period Mandatory with the summary or continuous_supply modifier. Summary invoice periodContinuous supply period
Invoice Period StartConditionaldateStart date of the invoiced period Mandatory with the summary or continuous_supply modifier. Summary invoice periodContinuous supply period
Note Issuance ReasonConditionalstringReason for credit/debit note Mandatory for credit notes, debit notes, simplified credit notes and simplified debit notes; optional for tax invoices and simplified invoices. ZATCA credit note requires note issuance reasonZATCA debit note requires note issuance reason
Reference IDConditionalstringOriginal invoice reference ID Mandatory for credit notes, debit notes, simplified credit notes and simplified debit notes; optional for tax invoices and simplified invoices. BR-KSA-56: credit and debit notes must carry the billing reference ID (BT-25) of the invoice they correct.
Additional NotesOptionalstringA textual note that gives unstructured information that is relevant to the Invoice as a whole.
Document IDOptionalstringInternal system document identifier (UUID or database ID)
Document ModifiersOptionalarrayModifiers that apply to the document, such as export. Send [] when none apply. Each country’s values are listed under Enums on its fields page.
exportExportsummarySummarycontinuous_supplyContinuous supplyb2gB2Gthird_partyThird partynominal_supplyNominal supplynominalNominalself_billedSelf billed
Document VariantOptionalstringA variant of the base document type: prepayment. Leave it out for an ordinary document.
prepaymentPrepayment
Due DateOptionaldatePayment due date
Exchange Rate DateOptionaldateExchange rate date
Exchange Source CurrencyOptionalstringExchange rate source currency
Exchange Target CurrencyOptionalstringExchange rate target currency
Invoice Period FrequencyOptionalstringFrequency of the billing period (monthly, weekly, etc.)
Reference NumbersOptionalarrayReference to original invoice (notes)
Seller Building NumberMandatorystringSeller building number BR-KSA-09: the seller address must have the street, building number, postal code, city, district and country code.
Seller DistrictMandatorystringSeller district BR-KSA-09: the seller address must have the street, building number, postal code, city, district and country code.
Seller Address Line 1MandatorystringThe main address line in an address. BR-KSA-09: the seller address must have the street, building number, postal code, city, district and country code.
Seller CityMandatorystringThe common name of the city, town or village, where the Seller address is located.
Seller CountryMandatorystringSeller country code
Seller Postal CodeMandatorystringThe identifier for an addressable group of properties according to the relevant postal service. BR-KSA-09: the seller address must have the street, building number, postal code, city, district and country code.
Seller NameMandatorystringSeller company name
Seller Registration TypeMandatorystringSeller registration type
CRNMOMMLSSAGOTH700
Seller Registration ValueMandatorystringAn identifier issued by an official registrar that identifies the Seller as a legal entity or person.
Seller Tax ID TypeMandatorystringThe scheme of the TAX identifier.
Seller Tax ID ValueMandatorystringSeller tax ID value
Seller Access Code BuildingOptionalstringseller access code building
Seller Access Code GateOptionalstringseller access code gate
Seller Access Code IntercomOptionalstringseller access code intercom
Seller Address TypeOptionalstringseller address type
Seller Address UsageOptionalstringseller address usage
Seller ApartmentOptionalstringseller apartment
Seller Attention ToOptionalstringseller attention to
Seller Building NameOptionalstringseller building name
Seller Business Hours CloseOptionalstringseller business hours close
Seller Business Hours DaysOptionalarrayseller business hours days
Seller Business Hours OpenOptionalstringseller business hours open
Seller Care OfOptionalstringseller care of
Seller Delivery InstructionsOptionalstringseller delivery instructions
Seller Delivery PointOptionalstringseller delivery point
Seller Additional NumberOptionalstringAdditional address number for seller (ZATCA requirement).
Seller FloorOptionalstringseller floor
Seller Geo Location LatitudeOptionalnumberseller geo location latitude
Seller Geo Location LongitudeOptionalnumberseller geo location longitude
Seller LandmarkOptionalstringseller landmark
Seller Plus CodeOptionalstringseller plus code
Seller PO BoxOptionalstringseller po box
Seller Post OfficeOptionalstringseller post office
Seller Room NumberOptionalstringseller room number
Seller Street NameOptionalstringseller street name
Seller Street NumberOptionalstringseller street number
Seller Sub DistrictOptionalstringseller sub district
Seller Time ZoneOptionalstringseller time zone
Seller Valid FromOptionaldateseller valid from
Seller Valid ToOptionaldateseller valid to
Seller Verification DateOptionaldateseller verification date
Seller Verification SourceOptionalstringseller verification source
Seller VerifiedOptionalstringseller verified
Seller WardOptionalstringseller ward
Seller What Three WordsOptionalstringseller what three words
Seller ZoneOptionalstringseller zone
Seller Address Line 2OptionalstringAn additional address line in an address that can be used to give further details supplementing the main line.
Seller Address Line 3OptionalstringSeller address line 3
Seller State/ProvinceOptionalstringThe subdivision of a country. Such as a region, a county, a state, a province etc..
Seller Business ActivityOptionalstringSeller business activity
Seller Contact EmailOptionalstringAn e-mail address for the contact point.
Seller Contact NameOptionalstringA contact point for a legal entity or person.
Seller Contact PhoneOptionalstringA phone number for the contact point.
Seller Industry Classification CodeOptionalstringIndustry classification code
Seller Industry Classification DescriptionOptionalstringIndustry classification description
Seller Industry Classification SchemeOptionalstringIndustry classification scheme
Seller Party IDOptionalstringSeller internal party ID
Seller Trade NameOptionalstringSeller trade name
Buyer NameMandatorystringBuyer company/name
Buyer Building NumberConditionalstringBuyer building number Conditional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes. BR-KSA-63: for a buyer in Saudi Arabia, the address must have the street, building number, postal code, city and district.
Buyer DistrictConditionalstringBuyer district Conditional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes. BR-KSA-63: for a buyer in Saudi Arabia, the address must have the street, building number, postal code, city and district.
Buyer Address Line 1ConditionalstringThe main address line in an address. Conditional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes. BR-KSA-63: for a buyer in Saudi Arabia, the address must have the street, building number, postal code, city and district. BR-KSA-10: for a buyer elsewhere, a standard (not simplified) document needs the street and city.
Buyer CityConditionalstringThe common name of the city, town or village, where the Buyer’s address is located. Conditional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes. BR-KSA-63: for a buyer in Saudi Arabia, the address must have the street, building number, postal code, city and district. BR-KSA-10: for a buyer elsewhere, a standard (not simplified) document needs the street and city.
Buyer CountryConditionalstringBuyer country code Mandatory for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Postal CodeConditionalstringThe identifier for an addressable group of properties according to the relevant postal service. Conditional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes. BR-KSA-63: for a buyer in Saudi Arabia, the address must have the street, building number, postal code, city and district.
Buyer Registration TypeConditionalstringBuyer registration type Mandatory for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
TINCRNMOMMLS700SAG
Buyer Registration ValueConditionalstringAn identifier issued by an official registrar that identifies the Buyer as a legal entity or person. Mandatory for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Access Code BuildingOptionalstringbuyer access code building Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Access Code GateOptionalstringbuyer access code gate Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Access Code IntercomOptionalstringbuyer access code intercom Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Address TypeOptionalstringbuyer address type Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Address UsageOptionalstringbuyer address usage Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer ApartmentOptionalstringbuyer apartment Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Attention ToOptionalstringbuyer attention to Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Building NameOptionalstringbuyer building name Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Business Hours CloseOptionalstringbuyer business hours close Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Business Hours DaysOptionalarraybuyer business hours days Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Business Hours OpenOptionalstringbuyer business hours open Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Care OfOptionalstringbuyer care of Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Delivery InstructionsOptionalstringbuyer delivery instructions Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Delivery PointOptionalstringbuyer delivery point Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Additional NumberOptionalstringAdditional address number for buyer (ZATCA requirement). Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer FloorOptionalstringbuyer floor Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Geo Location LatitudeOptionalnumberbuyer geo location latitude Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Geo Location LongitudeOptionalnumberbuyer geo location longitude Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer LandmarkOptionalstringbuyer landmark Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Plus CodeOptionalstringbuyer plus code Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer PO BoxOptionalstringbuyer po box Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Post OfficeOptionalstringbuyer post office Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Room NumberOptionalstringbuyer room number Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Street NameOptionalstringbuyer street name Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Street NumberOptionalstringbuyer street number Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Sub DistrictOptionalstringbuyer sub district Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Time ZoneOptionalstringbuyer time zone Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Valid FromOptionaldatebuyer valid from Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Valid ToOptionaldatebuyer valid to Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Verification DateOptionaldatebuyer verification date Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Verification SourceOptionalstringbuyer verification source Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer VerifiedOptionalstringbuyer verified Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer WardOptionalstringbuyer ward Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer What Three WordsOptionalstringbuyer what three words Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer ZoneOptionalstringbuyer zone Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Address Line 2OptionalstringAn additional address line in an address that can be used to give further details supplementing the main line. Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Address Line 3OptionalstringBuyer address line 3 Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer State/ProvinceOptionalstringThe subdivision of a country. Such as a region, a county, a state, a province etc.. Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Business ActivityOptionalstringBuyer business activity Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Contact EmailOptionalstringAn e-mail address for the contact point. Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Contact NameOptionalstringA contact point for a legal entity or person. Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Contact PhoneOptionalstringA phone number for the contact point. Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Industry Classification CodeOptionalstringBuyer industry code Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Industry Classification DescriptionOptionalstringBuyer industry description Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Industry Classification SchemeOptionalstringBuyer industry scheme Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Party IDOptionalstringBuyer internal party ID Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Tax ID TypeOptionalstringThe scheme of the TAX identifier. Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Tax ID ValueOptionalstringThe Buyer’s VAT identifier (also known as Buyer VAT identification number). The Buyer’s tax identifier (also known as Buyer tax identification number). For buyers in UAE which are registered under VAT should provide the Tax Registration Number (TRN). Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Buyer Trade NameOptionalstringBuyer trade name Optional for tax invoices, credit notes and debit notes; not used in simplified invoices, simplified credit notes and simplified debit notes.
Delivery CountryConditionalstringA code that identifies the country. Mandatory with the third_party modifier. Third-party billing requires delivery party country
Delivery Party NameConditionalstringDelivery party name Mandatory with the third_party modifier. Third-party billing requires delivery party name
Delivery Tax ID ValueConditionalstringDelivery tax ID value Mandatory with the third_party modifier. Third-party billing requires delivery party tax ID
Delivery Access Code BuildingOptionalstringdelivery access code building
Delivery Access Code GateOptionalstringdelivery access code gate
Delivery Access Code IntercomOptionalstringdelivery access code intercom
Delivery Address TypeOptionalstringdelivery address type
Delivery Address UsageOptionalstringdelivery address usage
Delivery ApartmentOptionalstringdelivery apartment
Delivery Attention ToOptionalstringdelivery attention to
Delivery Building NameOptionalstringdelivery building name
Delivery Building NumberOptionalstringdelivery building number
Delivery Business Hours CloseOptionalstringdelivery business hours close
Delivery Business Hours DaysOptionalarraydelivery business hours days
Delivery Business Hours OpenOptionalstringdelivery business hours open
Delivery Care OfOptionalstringdelivery care of
Delivery Delivery InstructionsOptionalstringdelivery delivery instructions
Delivery Delivery PointOptionalstringdelivery delivery point
Delivery DistrictOptionalstringdelivery district
Delivery FloorOptionalstringdelivery floor
Delivery Geo Location LatitudeOptionalnumberdelivery geo location latitude
Delivery Geo Location LongitudeOptionalnumberdelivery geo location longitude
Delivery LandmarkOptionalstringdelivery landmark
Delivery Plus CodeOptionalstringdelivery plus code
Delivery PO BoxOptionalstringdelivery po box
Delivery Post OfficeOptionalstringdelivery post office
Delivery Room NumberOptionalstringdelivery room number
Delivery Street NameOptionalstringdelivery street name
Delivery Street NumberOptionalstringdelivery street number
Delivery Sub DistrictOptionalstringdelivery sub district
Delivery Time ZoneOptionalstringdelivery time zone
Delivery Valid FromOptionaldatedelivery valid from
Delivery Valid ToOptionaldatedelivery valid to
Delivery Verification DateOptionaldatedelivery verification date
Delivery Verification SourceOptionalstringdelivery verification source
Delivery VerifiedOptionalstringdelivery verified
Delivery WardOptionalstringdelivery ward
Delivery What Three WordsOptionalstringdelivery what three words
Delivery ZoneOptionalstringdelivery zone
Delivery Address Line 1OptionalstringThe main address line in an address.
Delivery Address Line 2OptionalstringAdditional delivery address line
Delivery Address Line 3OptionalstringThird delivery address line
Delivery CityOptionalstringThe common name of the city, town or village, where the deliver to address is located.
Delivery Post CodeOptionalstringPostal code for delivery address
Delivery Country SubdivisionOptionalstringState, emirate or province for delivery address
Delivery Business ActivityOptionalstringDelivery business activity
Delivery Contact EmailOptionalstringDelivery contact email
Delivery Contact NameOptionalstringDelivery contact name
Delivery Contact PhoneOptionalstringDelivery contact phone
Actual Delivery DateOptionaldateActual delivery date
Actual Delivery TimeOptionalstringActual delivery time
Customs Declaration NumberOptionalstringcustoms declaration number
Destination PortOptionalstringDestination port
Export DateOptionaldateexport date
FreightOptionalstringfreight
Freight DocumentOptionalstringfreight document
IncotermsOptionalstringDelivery terms (Incoterms)
Origin PortOptionalstringOrigin port
Special TermsOptionalstringspecial terms
Transport ModeOptionalstringtransport mode
Delivery Industry Classification CodeOptionalstringDelivery industry classification code
Delivery Industry Classification DescriptionOptionalstringDelivery industry classification description
Delivery Industry Classification SchemeOptionalstringDelivery industry classification scheme
Delivery Party IDOptionalstringIdentifier for delivery party
Delivery Peppol IDOptionalstringDelivery party's Peppol network identifier
Deliver to Legal Registration TypeOptionalstringType of registration for delivery party
Deliver to Legal RegistrationOptionalstringRegistration number for delivery party
Delivery Tax ID TypeOptionalstringDelivery tax ID type
Delivery Trade NameOptionalstringDelivery party trade name
Line Item IDMandatorystringLine item identifier
Line Item TotalMandatorynumberLine item total
Line Item NameMandatorystringLine item name/description
Item Net PriceMandatorynumberNet unit price excluding VAT.
Line Item QuantityMandatorynumberThe quantity of items (goods or services) that is charged in the Invoice line.
Line Item Tax AmountMandatorynumberTax amount for the line item, excluding the net line amount.
Line Item Unit CodeMandatorystringUnit code (PCE, KGM, etc.)
Buyer Item CodeOptionalstringBuyer item code
Commodity Classification CodeOptionalstringCommodity classification code
Commodity Classification DescriptionOptionalstringCommodity classification description
Commodity Classification SchemeOptionalstringThe identification scheme shall be chosen from the entries in UNTDID 7143 [6].
Commodity CodeOptionalstringTariff/commodity code
Country Of OriginOptionalstringThe code identifying the country from which the item originates.
Line Item DescriptionOptionalstringA description for an item.
Line Discount/Charge AmountOptionalnumberDiscount/Charge amount
Line Discount/Charge Base AmountOptionalnumberDiscount/Charge base amount
Line Discount/Charge IDOptionalstringDiscount/Charge ID
Line Discount/Charge is ChargeOptionalbooleanIs charge or discount
Line Discount/Charge PercentageOptionalnumberDiscount/Charge percentage
Line Discount/Charge ReasonOptionalstringDiscount/Charge reason
Line Discount/Charge Reason CodeOptionalstringDiscount/Charge reason code
Line Discount/Charge Tax AmountOptionalnumberDiscount/Charge tax amount
Line Discount/Charge Tax CategoryOptionalstringDiscount/Charge tax category
Line Discount/Charge Tax RateOptionalnumberDiscount/Charge tax rate
Line Taxable ValueOptionalnumberThe total amount of the Invoice line (before tax).
Line TypeOptionalstringLine type
Base QuantityOptionalnumberThe number of item units to which the price applies.
Base Quantity Unit CodeOptionalstringBase quantity unit code
Item Gross PriceOptionalnumberUnit price before a price-level discount, excluding VAT.
Line Related Document TypeOptionalstringRelated document type
Line Related Document IDOptionalstringRelated document ID
Seller Item CodeOptionalstringSeller item code
Standard Item Code IDOptionalstringAn item identifier based on a registered scheme.
Standard Item Code SchemeOptionalstringThe identification scheme identifier of the Item standard identifier.
Line Tax CategoryOptionalstringThe VAT category code for the invoiced item.
SStandard rateZZero ratedEExempt from taxOServices outside scope of tax / Not subject to tax
Tax Exemption ReasonOptionalstringA textual statement of the reason why the line amount is exempted from VAT or why no VAT is being charged.
Tax Exemption Reason CodeOptionalstringA coded statement of the reason for why the line amount is exempted from VAT.
Line Tax RateOptionalnumberThe VAT rate, represented as percentage that applies to the invoiced item.
Line Rounding AmountOptionalnumberKSA line-level RoundingAmount (ZATCA Phase 2).
Amount DueMandatorynumberThe outstanding amount that is requested to be paid.
Total Amount Excluding TaxMandatorynumberTotal excluding tax
Total Amount Including TaxMandatorynumberTotal including tax
Total Line Taxable AmountMandatorynumberSum of line taxable values
Total Tax AmountMandatorynumberTotal tax amount
Prepaid AmountOptionalnumberThe sum of amounts which have been paid in advance.
Rounding AmountOptionalnumberRounding adjustment
Total AllowancesOptionalnumberSum of all allowances on document level in the Invoice.
Total ChargesOptionalnumberSum of all charges on document level in the Invoice.
Tax Total AmountConditionalnumberTotal tax amount of the document. Optional as a group: if you leave taxTotals out, the VAT breakdown is calculated from the line items. A tax total you send needs its tax amount and, for each VAT category, the taxable amount, tax amount and category.
Tax Subtotal PercentageConditionalnumberTax rate of this category, as a percentage. Optional as a group: if you leave taxTotals out, the VAT breakdown is calculated from the line items. A tax total you send needs its tax amount and, for each VAT category, the taxable amount, tax amount and category.
Tax Subtotal Taxable AmountConditionalnumberSum of the taxable amounts in this tax category and rate. Optional as a group: if you leave taxTotals out, the VAT breakdown is calculated from the line items. A tax total you send needs its tax amount and, for each VAT category, the taxable amount, tax amount and category.
Tax Subtotal AmountConditionalnumberTax amount for this tax category and rate. Optional as a group: if you leave taxTotals out, the VAT breakdown is calculated from the line items. A tax total you send needs its tax amount and, for each VAT category, the taxable amount, tax amount and category.
Tax Subtotal CategoryConditionalstringTax category code of this part of the breakdown, such as S for the standard rate. Optional as a group: if you leave taxTotals out, the VAT breakdown is calculated from the line items. A tax total you send needs its tax amount and, for each VAT category, the taxable amount, tax amount and category.
SStandard rateZZero ratedEExempt from taxOServices outside scope of tax / Not subject to tax
Tax Subtotal Exemption ReasonConditionalstringWhy this category is exempt from tax, as text. Optional as a group: if you leave taxTotals out, the VAT breakdown is calculated from the line items. A tax total you send needs its tax amount and, for each VAT category, the taxable amount, tax amount and category.
Tax Subtotal Exemption Reason CodeConditionalstringWhy this category is exempt from tax, as a code. Optional as a group: if you leave taxTotals out, the VAT breakdown is calculated from the line items. A tax total you send needs its tax amount and, for each VAT category, the taxable amount, tax amount and category.
Tax Subtotal SchemeOptionalstringTax scheme of this part of the breakdown, normally VAT. Optional as a group: if you leave taxTotals out, the VAT breakdown is calculated from the line items. A tax total you send needs its tax amount and, for each VAT category, the taxable amount, tax amount and category.
Invoice Discount/Charge AmountOptionalnumberAllowance/charge amount
Invoice Discount/Charge Base AmountOptionalnumberBase amount
Invoice Discount/Charge Line IDOptionalstringAllowance/Charge ID
Invoice-level Is ChargeOptionalbooleanCharge (true) or allowance (false)
Invoice Discount/Charge PercentageOptionalnumberPercent applied
Invoice Discount/Charge ReasonOptionalstringReason for allowance/charge
Invoice Discount/Charge Reason CodeOptionalstringReason code
Invoice Discount/Charge Tax AmountOptionalnumberTax amount
Invoice Discount/Charge Tax CategoryOptionalstringTax category
SStandard rateZZero ratedEExempt from taxOServices outside scope of tax / Not subject to tax
Invoice Discount/Charge Tax RateOptionalnumberTax rate
Payee Account IDConditionalstringA unique identifier of the financial payment account, at a payment service provider, to which payment should be made.
Card Holder NameOptionalstringCard holder name
Card NetworkOptionalstringCard network ID
Card PANOptionalstringCard primary account number
Payee Account NameOptionalstringThe name of the payment account, at a payment service provider, to which payment should be made.
Payee Institution BranchOptionalstringAn identifier for the payment service provider where a payment account is located.
Direct Debit Mandate Ref IDOptionalstringDirect debit mandate reference
Payer Financial AccountOptionalstringPayer financial account
Payment IDOptionalstringPayment identifier
Payment Means CodeOptionalstringHow the payment is made, as a UNTDID 4461 payment means code, for example 30 for a credit transfer or 10 for cash.
10In cash20Cheque30Credit transfer424849Direct debit
Payment Means TextOptionalstringPayment method description
Discount AmountOptionalnumberThe payment amount that these terms apply to. When relevant, the amount includes tax.
Discount Due DateOptionaldateDiscount due date
Payment Terms NoteOptionalstringA textual description of the payment terms that apply to the amount due for payment (Including description of possible penalties).
Penalty AmountOptionalnumberPenalty amount
Penalty PercentageOptionalnumberPenalty percent
Settlement Discount PercentageOptionalnumberSettlement discount percent
Supporting Document TypeConditionalstringType of supporting document Mandatory with the b2g modifier. B2G requires supporting document type
Supporting Document IDConditionalstringSupporting document identifier Mandatory with the b2g modifier. B2G requires supporting document ID
Attachment ChecksumOptionalstringAttachment checksum
Attachment ContentOptionalstringAttachment base64 content
Attachment Content URLOptionalstringAttachment content URL
Attachment DescriptionOptionalstringAttachment description
Attachment FilenameOptionalstringAttachment file name
Attachment Mime CodeOptionalstringA code identifying the file type.
application/pdfimage/pngimage/jpegtext/csvapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheetapplication/xmlapplication/vnd.oasis.opendocument.spreadsheet
Attachment SizeOptionalnumberAttachment size
Supporting Document DescriptionOptionalstringDescription of supporting document
Supporting Document Issue DateOptionaldateSupporting document issue date
Supporting Document URLOptionalstringReference URL
Invoice Counter ValueMandatorystringInvoice counter value (ICV) for ZATCA invoice sequencing. BR-KSA-33: every document must carry its invoice counter value (KSA-16), in digits only (BR-KSA-34).
Contract ReferenceOptionalstringContract reference for KSA XML rendering.
Digital SignatureOptionalstringBase64 encoded digital signature for ZATCA compliance.
Previous Invoice HashOptionalstringPrevious invoice hash (PIH) for ZATCA invoice chaining.
Prepayment Adjustment AmountOptionalnumberAdjustment amount for the prepayment.
Prepayment DateOptionaldateDate of the prepayment.
Prepayment IDOptionalstringIdentifier for prepayment reference.
Prepayment Taxable AmountOptionalnumberTaxable amount for the prepayment.
Prepayment Tax AmountOptionalnumberTax amount for the prepayment.
Prepayment Tax CategoryOptionalstringTax category for the prepayment.
Prepayment Tax RateOptionalnumberTax rate for the prepayment.
Prepayment Type CodeOptionalstringType code for the prepayment.
Purchase Order ReferenceOptionalstringPurchase order reference for KSA XML rendering.
QR CodeOptionalstringBase64 encoded QR code for ZATCA compliance.
Destination AuthorityOptionalstringDestination authority
Destination BodyOptionalstringEmail body
Destination CountryOptionalstringDestination country
Destination Document TypeOptionalstringDestination document type
Destination Participant IDOptionalstringPeppol participant ID
Destination RecipientsOptionalarrayEmail recipients
Destination SubjectOptionalstringEmail subject
Destination TypeOptionalstringDestination type for submission
Is B2BOptionalbooleanBusiness to Business flag
Is TestbedOptionalbooleanTestbed document flag
PurposeOptionalstringDocument purpose (e.g., testbed, e-invoicing, mapping)
ModeOptionalstringDocument processing mode
OperationOptionalstringDocument operation type
Source IDOptionalstringSource identifier
Source NameOptionalstringSource name
Source TypeOptionalstringSource type
Source VersionOptionalstringSource version
VersionOptionalstringDocument version

Required fields by document type

The table’s requirements as lists of GETS paths. A conditional field is required only when the condition in its description is met. Fields a modifier or variant makes mandatory are listed under it.

Every document type

Mandatory: header.documentType.base, header.documentNumber, header.issueDate, header.issueTime, header.currency, header.taxCurrency, parties.seller.name, parties.seller.address.country, parties.seller.address.city, parties.seller.taxIds[].type, parties.seller.taxIds[].value, parties.seller.registrationNumbers[].type, parties.seller.registrationNumbers[].value, parties.seller.address.addressLine1, parties.seller.address.postalCode, parties.seller.address.additionalAddressData.buildingNumber, parties.seller.address.additionalAddressData.district, parties.buyer.name, lineItems[].id, lineItems[].name, lineItems[].quantity, lineItems[].unitCode, lineItems[].lineTotal, lineItems[].taxAmount, lineItems[].price.amount, totals.totalAmountExcludingTax, totals.totalAmountIncludingTax, totals.amountDue, totals.totalLineTaxableAmount, totals.totalTaxAmount, extensions.sa_icv, header.uuid

Conditional: payment.paymentMeans[].creditTransferInfo.payeeFinancialAccountId, taxTotals[].taxAmount, taxTotals[].taxSubtotals[].taxableAmount, taxTotals[].taxSubtotals[].taxAmount, taxTotals[].taxSubtotals[].taxCategory, taxTotals[].taxSubtotals[].percent, taxTotals[].taxSubtotals[].taxExemptionReason, taxTotals[].taxSubtotals[].taxExemptionReasonCode

Tax invoice (tax_invoice)

Also mandatory: parties.buyer.address.country, parties.buyer.registrationNumbers[].type, parties.buyer.registrationNumbers[].value

Also conditional: parties.buyer.address.addressLine1, parties.buyer.address.city, parties.buyer.address.postalCode, parties.buyer.address.additionalAddressData.buildingNumber, parties.buyer.address.additionalAddressData.district

Credit note (credit_note)

Also mandatory: header.noteIssuanceReason, header.referenceId, parties.buyer.address.country, parties.buyer.registrationNumbers[].type, parties.buyer.registrationNumbers[].value

Also conditional: parties.buyer.address.addressLine1, parties.buyer.address.city, parties.buyer.address.postalCode, parties.buyer.address.additionalAddressData.buildingNumber, parties.buyer.address.additionalAddressData.district

Debit note (debit_note)

Also mandatory: header.noteIssuanceReason, header.referenceId, parties.buyer.address.country, parties.buyer.registrationNumbers[].type, parties.buyer.registrationNumbers[].value

Also conditional: parties.buyer.address.addressLine1, parties.buyer.address.city, parties.buyer.address.postalCode, parties.buyer.address.additionalAddressData.buildingNumber, parties.buyer.address.additionalAddressData.district

Simplified invoice (simplified_invoice)

Nothing beyond the fields every document type needs.

Simplified credit note (simplified_credit_note)

Also mandatory: header.noteIssuanceReason, header.referenceId

Simplified debit note (simplified_debit_note)

Also mandatory: header.noteIssuanceReason, header.referenceId

Modifiers and variants

  • export (modifier): mandatory: header.exchangeRate.rate.
  • summary (modifier): mandatory: header.invoicePeriod.startDate, header.invoicePeriod.endDate.
  • continuous_supply (modifier): mandatory: header.invoicePeriod.startDate, header.invoicePeriod.endDate.
  • b2g (modifier): mandatory: supportingDocuments[].id, supportingDocuments[].documentType.
  • third_party (modifier): mandatory: parties.delivery.name, parties.delivery.taxIds[].value, parties.delivery.address.country.
  • nominal_supply (modifier): no further mandatory fields.
  • nominal (modifier): no further mandatory fields.
  • self_billed (modifier): no further mandatory fields.
  • prepayment (variant): no further mandatory fields.