Manage country-specific configurations for Saudi Arabia

Configure e-invoicing business regions for Saudi Arabia 

In the e-invoicing clearance process in Saudi Arabia, you must configure business regions according to the specific requirements of Saudi Arabia. 

The business region objects can be looked up according to the country and state, and their related fields can be mapped accordingly within the e-invoicing template. You must configure e-invoicing business regions for Saudi Arabia according to its requirements. 

The following table lists the business region settings you must configure in the Add Business Region dialog.

UI section	UI field	API field	Required	Description
Basic Info	Country	country	Yes	From the Country list, select a country or region where you must comply with e-invoicing requirements.
	Legal Business Name	businessName	Yes	In the Legal Business Name field, specify the full official name of the Seller registered with the relevant legal authority. Character limit: 1000
	Legal Business Number	businessNumber	Yes	In the Legal Business Number field, specify the unique identifier number of the legal entity or person you do business with. For Saudi Arabia, the value is the Tax Identification Number (TIN) issued by the General Authority for Zakat and Tax (GAZT) to all taxpayers and withholding entities (such as government ministries, agencies, and departments). GAZT is the Saudi Arabia's tax administrator. Once a TIN is issued to a taxpayer, it remains valid as long as the taxpayer is in operation. The taxpayer's TIN is used for all the taxes to which the taxpayer is liable.
	Business Number Schema Id	businessNumberSchemeId	No	In the Business Number Schema Id field, specify the identification scheme identifier that an official registrar issues to identify the Seller as a legal entity or person.
	Trade Name	tradeName	No	In the Trade Name field, specify the name that the Seller is known as, other than the legal business name.
	Tax Register Number	taxRegisterNumber	No	In the Tax Register Number field, specify the Seller's VAT identifier (also known as Seller VAT identification number) or the local identification (defined by the Seller’s address) of the Seller for tax purposes, or a reference that enables the Seller to state the registered tax status.
	E-Invoice Destination Code	endpointId	No	In the E-Invoice Destination Code field, specify the Seller's electronic address, to which the application-level response to the e-invoice file might be delivered.
	E-Invoice Destination Code Schema Id	endpointSchemeId	No	In the E-Invoice Destination Code Schema Id field, specify the identification scheme identifier of the Seller’s electronic address.
Business Address	Address 1	addressLine1	Yes	In the Address 1 field, specify the first line of the Seller’s address, which is often a street address or business name. For Saudi Arabia, it's the main address line in an address.  Character limit: 1000
	Address 2	addressLine2	Yes	In the Address 2 field, specify the second line of the Seller’s address, which is often the name of a building. For Saudi Arabia, it's the building number within a street.
	Postal Code	postalCode	Yes	In the Postal Code field, specify the short code that can identify the business address. For Saudi Arabia, the value is the postal identifier for this address according to the relevant national postal service, such as a ZIP code or postcode.
	City	city	Yes	In the City field, specify the name of the city where the business is located. For Saudi Arabia, it's the common name of a city, town, or village of the seller.  Character limit: 127
	State/Province	state	Yes	In the State/Province field, specify the name of the state or province where the business is located. For Saudi Arabia, it’s the name of the subdivision of the Seller's city, town, or village in which its address is located. For example, the name of its district or borough. Character limit: 127
Contact Info	Contact Name	contactName	No	In the Contact Name field, specify the name of the Seller contact to receive e-invoicing data.
	Email	email	No	In the Email field, specify the email address of the Seller contact to receive e-invoicing data.
	Business Phone Number	phoneNumber	No	In the Business Phone Number field, specify the business phone number of the Seller contact to receive e-invoicing data.

Configure e-invoicing profiles for accounts in Saudi Arabia

According to the specific requirements of Saudi Arabia, you must configure e-invoicing profiles for customer accounts involved in the e-invoicing business.

The following table lists the e-invoicing profile settings to configure for a customer account in Saudi Arabia.

UI field	API field	Required	Description
Generate E-Invoice for Customer	enabled	Yes	Enable the e-invoicing profile for the customer account.  If the following conditions are met, all billing documents for one account can be submitted to an e-invoicing service provider to be generated in electronic format: The account must be configured to generate e-invoice files for billing documents. The billing document must be in Posted status. A business region must be created for the billing country contact, and be linked to an e-invoicing service provider.
Legal Business Name	businessName	Yes	In the Legal Business Name field, specify the full official name that the Buyer is registered with the relevant legal authority. Character limit: 1000
Legal Business Number	businessNumber	Yes	In the Legal Business Number field, specify the unique identifier number of the legal entity or person that you do business with. The value is the tax identification number for VAT purposes. The first two characters represent the country (IT, DE, ES, and so on), and the remaining characters (up to a maximum of 28) are the actual code, which, for the residents of Saudi Arabia, corresponds to their VAT number.
Business Number Schema Id	businessNumberSchemeId	No	In the Business Number Schema Id field, specify the identification scheme identifier that an official registrar issues to identify the Buyer as a legal entity or person.
Trade Name	tradeName	No	In the Trade Name field, specify the name that the Buyer is known as, other than the legal business name.
Tax Register Number	taxRegisterNumber	No	In the Tax Register Number field, specify the Buyer's VAT identifier (also known as the Buyer's VAT identification number) or the local identification (defined by the Buyer’s address) of the Buyer for tax purposes, or a reference that enables the Buyer to state the registered tax status.
E-Invoice Destination Code	endpointId	No	In the E-Invoice Destination Code field, specify the Buyer's electronic address, to which the application-level response to the invoice/billing document might be delivered.
E-Invoice Destination Code Schema Id	endpointSchemeId	No	In the E-Invoice Destination Code Schema Id field, specify the identification scheme identifier of the Buyer’s electronic address.
Name	name	No	In the Name field, specify the name on the Account object. The value is used as the trading name or company name of the Buyer/Orderer to be entered for a non-natural person.

Configure sold-to contacts for accounts in Saudi Arabia

You must configure sold-to contacts for customer accounts involved in the e-invoicing business in Saudi Arabia.

The following table lists the contact-related fields involved in the e-invoicing business in Saudi Arabia.

UI field	API field	Required	Description
Country	country	Yes	From the Country list, select Saudi Arabia.
Address 1	addressLine1	Yes	In the Address 1 field, specify the first line of the Buyer’s address, which is often a street address or business name.  For Saudi Arabia, it's the main address line in an address.
Address 2	addressLine2	Yes	In the Address 2 field, specify the second line of the Buyer’s address, which is often the name of a building.  For Saudi Arabia, it's the building number within a street.
Postal Code	postalCode	Yes	In the Postal Code field, specify the short code that can identify the business address. For Saudi Arabia, the value is the postal identifier for this address according to the relevant national postal service, such as a ZIP code or postcode.
City	city	Yes	In the City field, specify the name of the city where the business is located. For Saudi Arabia, it's the common name of a city, town, or village of the seller.
State/Province	state	Yes	In the State/Province field, specify the name of the state or province where the business is located. For Saudi Arabia, it’s the name of the subdivision of the Buyer's city, town, or village in which its address is located. For example, the name of its district or borough.

Specify building numbers on contacts and business regions

In the e-invoicing clearance process in Saudi Arabia, both the Seller and the Buyer must provide their address building numbers.

• The building number is mandatory for the business region, which holds the business details of the Seller, and mandatory for the bill-to-contact, which contains the address of the Buyer.
• It is best practice to use the address line 2 of the business region and bill-to-contact to store the building number. The addressLine2 field is mandatory for the business region, which holds the address building number of the Seller, and for the Bill To Contact, which contains the address building number of the Buyer.
•  If you store the building number in a standard or custom field, you must change the template accordingly.

Business Category

The e-invoice data transmitted to SDI supports two types of business categories, identified by the following codes:

• B2C for end-users
• B2B for private companies and professionals

The tag in the e-invoice file template is as follows: 

<Scope>
    <Type>BusinessCategory</Type>
    <InstanceIdentifier/>
    <Identifier>B2B</Identifier>
</Scope> 

Zuora's default e-invoice file template is configured to B2B. Zuora's testing covers the business category B2B only. B2C as the business category has not been tested.

Invoice type description and type code

In the e-invoice file template, you must specify a code for the functional type of the Invoice. Zuora has only tested with the Invoice Type Description as 0100000. If you have other invoice subtypes, you must customize the e-invoice file template and plan the testing accordingly. 

Specify the invoice type description and type code

In the e-invoice file template, specify a code for the functional type of the Invoice. NNPNESB is the type code for your invoices. For example, 1100110 is the description code you must use in the e-invoice template. Refer to the table below for more information on specifying description codes for your invoices. 

Code	Description	True/False	Example	Description code
N	01 for Tax invoice  02 Simplified tax invoice	NA	Tax invoice	0 1
N
P	3rd party invoice transaction	0 for false and 1 for true	False	0
N	Nominal invoice transaction		False	0
E	Exports invoice transaction		True	1
S	Summary invoice transaction		True	1
B	Self-billed invoice transaction		False	0

By default, Zuora configures the e-invoice file template with the invoice type description code 0100000. For a B2C scenario, It’s assumed that the invoice is a tax invoice and not a simplified tax invoice.

Suppose you have other types of invoices. For example, if your business falls in the Exports Invoice Transaction category, you must use the description code 0100100 and customize the e-invoice file template accordingly.

Specify the referenced document for credit memo and debit memo

A credit or debit memo requires an identifier for the referenced document (order number, agreement number, and so on). In the default e-invoice file template, for a credit or debit memo, use the invoice number as the identifier of the referenced document if they are created from an invoice or generated from subscriptions due to subscription cancellation and product removal. When they are a standalone credit or debit memo from a product rate plan charge, PurchaseOrderNumber on the Account is used.

To modify these default mappings, you should customize the e-invoice file template. For example, if you want to use the purchase order number as the reference for an individual credit or debit memo. You can store the purchase order number on a credit or debit memo.

Reasons for issuing credit and debit memos

The reason for issuing a credit or debit note applies to the credit and debit memo e-invoice file templates.

According to Saudi Arabia VAT regulations, a credit or debit note is issued in the following five cases:

• Cancellation or suspension of the supply occurs after the supply has been processed entirely or partially (تم إلغاء أو وقف التوريد بعد حدوثه أو اعتباره كلياً أو جزئياً).

• Essential change or amendment in the supply leads to the change of the VAT due (وجود تغيير أو تعديل جوهري في طبيعة التوريد بحيث يؤدي الى تغيير الضريبة المستحقة).

• Amendment of the supply value is pre-agreed upon between the supplier and consumer (تم الاتفاق على تعديل قيمة التوريد مسبقاً).

• Goods or services are refunded (عند ترجيع السلع أو الخدمات).

• Change in the seller's or buyer's information occurs (عند التعديل على بيانات المورد أو المشتري).

In the e-invoice file template, the InstructionNote tag in the PaymentMeans tag in the Invoice tag is used to pass the reason. 

Zuora default e-invoice file templates use the standard field ReasonCode on the CreditMemo and DebitMemo objects. The CBC tag in the default e-invoice file template is as follows:

<cbc:InstructionNote>{{ReasonCode}}</cbc:InstructionNote>

You can use one of the following fields in the {{ReasonCode}} merge field:

• The standard field ReasonCode on the CreditMemo and DebitMemo objects is populated by default. However, before using the ReasonCode, you need to configure the reason code names for the credit memo and debit memo in the Zuora Billing based on the five cases above. See  Creating and Editing Reason Codes.

• You can also replace the {{ReasonCode}} merge field with a custom field on the CreditMemo and DebitMemo objects. Before replacing {{ReasonCode}} with the custom field, create the custom field by yourself based on the five cases above, and modify the e-invoice file template to align with the custom field.

Payment means type code

Payment means type code is used to specify whether the payment mode is cash, credit/debit cards, bank transfer, credit, and/or others. Payment means type code applies to the credit and debit memo e-invoice file templates.

In the e-invoice file template, the PaymentMeansCode tag in the PaymentMeans tag in the Invoice tag is used to pass the payment means type code. 

The CBC tag in the default e-invoice file template is as follows:

<cbc:PaymentMeansCode>30</cbc:PaymentMeansCode>

Zuora default e-invoice file templates use 30 as the default code. 30 indicates that the means of payment is the credit transfer. The allowed codes are listed in the UNTDID 4461 code list, see unece org website. If 30 is not appropriate for your business, change it to another one in the UNTDID 4461 code list.

Identification scheme for supplier and consumer

Zuora default e-invoice file template uses CRN (Commercial Registration Number) as the scheme ID, and its value is Tax Identification Number (TIN). The scheme ID applies to invoice, credit memo, and debit memo e-invoice file templates. 

Supplier

For the supplier party, the CAC tag in the default e-invoice file template is as follows:

<cac:PartyIdentification>
    <cbc:ID schemeID="CRN">{{VarBusinessNumber}}</cbc:ID>
</cac:PartyIdentification>

The default schemeID is CRN. For supplier, you can use one of the following schemeID to replace the default one:

• Commercial registration number with "CRN" as schemeID

• MOMRAH license with "MOM" as schemeID

• MHRSD license with "MLS" as schemeID

• 700 Number with "700" as schemeID

• MISA license with "SAG" as schemeID

• Other OD with "OTH" as schemeID

In case multiple IDs exist, then one of the above must be entered following the sequence specified above. 

If the schemeID is CRN, default e-invoice file template uses {{VarBusinessNumber}} merge field, and the value is the legal business number configured in the business region for the supplier. 

Consumer

For the customer party, the CAC tag in the default e-invoice file template is as follows:

<cac:PartyIdentification>
    <cbc:ID schemeID="CRN">{{Account.EInvoiceProfile.BusinessNumber}}</cbc:ID>
</cac:PartyIdentification>

The default schemeID is CRN. For consumer, you can use one of the following schemeID to replace the default one:

• Tax Identification Number "TIN" as schemeID

• Commercial registration number with "CRN" as schemeID

• MOMRAH license with "MOM" as schemeID

• MHRSD license with "MLS" as schemeID

• 700 Number with "700" as schemeID

• MISA license with "SAG" as schemeID

• National ID with "NAT" as schemeID

• GCC ID with "GCC" as schemeID

• Iqama Number with "IQA" as schemeID

• Passport ID with "PAS" as schemeID

• Other ID with "OTH" as schemeID

In case multiple IDs exist, then one of the above must be entered following the sequence specified above. The “Other ID” is required only if buyer is not VAT registered.

If the schemeID is CRN, the default e-invoice file template uses the {{Account.EInvoiceProfile.BusinessNumber}} merge field, and the value is the legal business number configured in the E-Invoice section on the account.

Quantity on Invoice Line

The quantity applies to invoice, credit memo, and debit memo e-invoice file templates.
CBC tag in the default template is as follows: 

<cbc:InvoicedQuantity unitCode="{{UOM}}">{{Quantity}}</cbc:InvoicedQuantity>

The quantity includes the following information:

• {{Quantity}}: The quantity of items (for example, goods or services) that is charged in the Invoice line. Zuora default e-invoice file template uses a Quantity field on the line items. The line items refer to Zuora InvoiceItem, CreditMemoItem, and DebitMemo Item objects. 
• {{UOM}}: The unit of measure that applies to the invoiced quantity. Zuora default e-invoice file template uses a unit of measure field on the line items. The unit of measure has different field names on the line items, that is, the UOM field on the Invoice Item object, and the UnitOfMeasure field on the CreditMemoItem and DebitMemoItem objects.

We recommend you use these default mappings. You can change the default templates if the default field mappings don’t meet your needs.

Business Category

The e-invoice data transmitted to SDI supports two types of business categories: B2B and B2C.

Zuora's default e-invoice template is configured to B2B. Zuora's testing covers the business category B2B only. B2C as the business category has not been tested.

Invoice type description and type code

In the e-invoice file template, you need to specify a code for the functional type of the Invoice. Zuora only tested with the Invoice Type Description as 0100000. If you have other types of invoice subtypes, you’ll need to customize the e-invoice file template and plan the testing accordingly. For more information, see Specify the invoice type description and type code.