Skip to main content

Manage country-specific configurations for Saudi Arabia

Zuora

Manage country-specific configurations for Saudi Arabia

If you are a business provider selling products and services in Saudi Arabia, you can configure the E-Invoicing feature to generate e-invoice files for the mandates of invoice clearance.

As a taxpayer, you must have a unique Tax Identification Number (TIN), to be able to issue invoices. For more information on the TIN for Saudi Arabia, see Saudi Arabia TIN.

The Zuora E-Invoicing feature supports the following document types that are currently supported by Saudi Arabia:

  • Electronic invoices
    Electronic invoices (e-invoices) are a form of issuance of sales invoices electronically and are stipulated by the government of Saudi Arabia.
  • Credit notes
    A credit note allows taxable persons to amend previously issued valid invoices by adjusting the amounts payable.
  • Debit notes
    A debit note allows taxable persons to amend previously issued valid invoices by adjusting the amounts against any payment changes.

Configure e-invoicing in Sovos for Saudi Arabia

To configure e-invoicing for invoice clearance for Saudi Arabia, you must create a company profile in Sovos. Zuora handles the configuration process on your behalf in Sovos, ensuring a seamless setup.

ZATCA’s (Zakat, Tax and Customs Authority) Sandbox (UAT - User Acceptance Testing) environment is not fully dynamic, so no ZATCA credentials are issued. No prerequisite steps against ZATCA are required for UAT to perform Sovos configurations and then begin transmitting documents.

To get started with Sovos’ UAT environment, you need to provide the following information required for the configuration to Zuora. This information is used to configure a company in Sovos.

  • Company Name: Legal name of your business
  • Trade Name: Doing business as (DBA) name
  • Tax Identification Number (TIN): Unique tax identification number

The following instructions are from Sovos’ developer guide for Saudi Arabia Configuration in case you cannot access it.

To get started with Sovos’ Production environment, you must obtain an OTP (One Time Password) from the Fatoora Portal (ZATCA) and compose the CSR input data in the “Provision a Branch” request via Sovos’ API. Configuring a branch in Sovos consists of creating a branch and then provisioning, which requires the following fields:

  • otp (string): Set it to the OTP retrieved from the Fatoora Portal. The steps required to obtain it can be found under “Fatoora Portal User Manual”, available for download from the Fatoora Portal. For Sandbox testing, set the otp to 123345. Only one OTP can be used at the time, as the “multiple OTP” option is not supported by Sovos solution.
  • csrInput (string): A more detailed explanation of the fields of CSR input can be found in the “E-Invoicing Detailed Technical Guideline”, available for download in this government web page.
    • commonName (string): Unique name or asset tracking number of the organization unit. Free text, with the maximum limit of 500 characters.
      • organizationName (string): Organization/Taxpayer Name — not to be confused with YOUR-ORG-ID used in the request path. Free text, with a maximum limit of 500 characters.
        • countryName (string): Name of the country (2-letter ISO 3166 Alpha-2).
          • invoiceType (string): The 4-number document type that the Taxpayer’s solution unit will be issuing/generating. It can be one or a combination of Standard Tax Invoice & Simplified Tax Invoice:
            • 1000: Standard Tax Invoices only (B2B/B2G).
            • 0100: Simplified Tax Invoices only (B2C).
            • 1100: Simplified and Standard Tax Invoices (B2B/B2G & B2C). Free text.
    • location (string): The address of the Branch or location where the device or solution unit is primarily situated (could be a website address for e-commerce). Preferably in the Short Address format of the Saudi National Address. Free text, with a maximum limit of 500 characters.
    • industry (string): Industry or sector for which the device or solution will generate invoices. Free text, with a maximum limit of 500 characters. Example: “finance”.

Note that Sovos only provides APIs for the configuration without user interface support.

Manage field mapping for e-invoice file templates

In the e-invoicing clearance process in Saudi Arabia, ensure that the field mapping for e-invoice file templates is complete and correct. The default e-invoice file template for Saudi Arabia in Zuora is explained below. Keep in mind that you may need to customize the template if the default field mapping doesn't align with your business requirements.

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.

Service Provider

Provider

serviceProviderId

Yes

From the Provider list, select your e-invoicing service provider.

For Saudi Arabia, if the service provider is Sovos, the E-Invoice Process automatically changes to Clearance Only.

Digital Signature Enable PDF Digital Signature digitalSignatureEnable No

Specify whether the e-invoicing service provider signs PDF files for billing documents.

Click Yes to enable the setting. The default setting is NO.

For more information, see Digital Signature.

Billing Document Type
  • Invoice
  • Credit Memo
  • Debit Memo
  • invoiceEnabled
  • creditMemoEnabled
  • debitMemoEnabled
Yes Select one or more of the following billing document types to be supported:
  • Invoice
  • Credit Memo
  • Debit Memo
These document types are selected by default.
 

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.
Business Category BusinessCategory No

The following three options are available:

  • B2B (Business to Business)
  • B2C (Business to Consumer)
  • B2G (Business to Government)

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.

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.

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.

In the e-invoice file template, the Invoice > BillingReference > InvoiceDocumentReference > ID tag is used to pass the reference document identifier.

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

<cbc:ID>
    {{#Source|EqualToVal(AdhocFromInvoice)}}
    {{Invoice.InvoiceNumber}}
    {{/Source|EqualToVal(AdhocFromInvoice)}}
    {{#Source|EqualToVal(BillRun)}}
    {{#CreditMemoItems|Map(CreditFromInvoiceItem)|GroupBy(Invoice.InvoiceNumber)|Uniq}}
    {{Cmd_Assign(VAR,CreditFromItemId)}}
    {{Invoice.InvoiceNumber}}
    {{/CreditMemoItems|Map(CreditFromInvoiceItem)|GroupBy(Invoice.InvoiceNumber)|Uniq}}
    {{/Source|EqualToVal(BillRun)}}
    {{#Source|EqualToVal(AdhocFromPrpc)}}
    {{Account.PurchaseOrderNumber}}
    {{/Source|EqualToVal(AdhocFromPrpc)}}
    {{#Source|EqualToVal(API)}}
    {{#CreditMemoItems|Map(CreditFromInvoiceItem)|GroupBy(Invoice.InvoiceNumber)|Uniq}}
    {{Invoice.InvoiceNumber}}
    {{/CreditMemoItems|Map(CreditFromInvoiceItem)|GroupBy(Invoice.InvoiceNumber)|Uniq}}
    {{/Source|EqualToVal(API)}}
</cbc:ID>

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

<cbc:ID>
    {{#Source|EqualToVal(AdhocFromInvoice)}}
    {{Invoice.InvoiceNumber}}
    {{/Source|EqualToVal(AdhocFromInvoice)}}
    {{#Source|EqualToVal(AdhocFromCreditMemo)}}
    {{CreditMemoId}}
    {{/Source|EqualToVal(AdhocFromCreditMemo)}}
    {{#Source|EqualToVal(AdhocFromPrpc)}}
    {{Account.PurchaseOrderNumber}}
    {{/Source|EqualToVal(AdhocFromPrpc)}}
</cbc:ID>

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.

In the following example, the PONumberCMC__c custom field on the Credit Memo object is used to store the purchase order number:

<cbc:ID>
    …
    {{#Source|EqualToVal(AdhocFromPrpc)}}
    {{PONumberCMC__c}}
    {{/Source|EqualToVal(AdhocFromPrpc)}}
    …
</cbc:ID>

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.
    If you use the standard field ReasonCode in the e-invoice file template for Credit Memo or Debit Memo for Saudi Arabia, Zuora maps pre-populated reason codes for credit and debit memos to the reason codes that comply with Saudi Arabia VAT regulations. The mapping rules are as follows:

    Template type Before mapping (pre-populated reason code for memo documents in Zuora) After mapping
    Credit Memo Invoice Reversal Cancellation or suspension of the supply occurs after the supply has been processed entirely or partially (تم إلغاء أو وقف التوريد بعد حدوثه أو اعتباره كلياً أو جزئياً)

    Any other pre-populated reason codes for credit memos.

    For a complete list, see Pre-Populated and Default Reason Codes.

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

    Any pre-populated reason codes for debit memos.

    For a complete list, see Pre-Populated and Default Reason Codes.

    Change in the seller's or buyer's information occurs (عند التعديل على بيانات المورد أو المشتري)
  • 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 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.

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.

Language requirement for e-invoice file templates

ZATCA accepts e-invoice XML files in either English or Arabic. However, the invoice PDF files you share with your customers must be in Arabic.

The language requirement for e-invoice file templates depends on whether you use Sovos’ PDF template:

  • If you use Sovos’ PDF template, the text in e-invoice file templates must be in Arabic. In this case, Sovos can auto-generate the corresponding Arabic PDF files.
    Additionally, you can include other languages besides Arabic in e-invoice file templates. For more information, see Add multi-language information to e-invoice file templates.
  • If you opt not to use Sovos’ PDF template, the text information in e-invoice file templates can be in English or Arabic.

Add multi-language information to e-invoice file templates

To add multi-language information to e-invoice file templates, you must add a pipe symbol (|) between the information in different languages. See the following snippet as an example:

<cbc:StreetName> استخدام جسر مجمع الملك عبده عبد العزيز للاتصالات | KING ABDU AZIZ TELECOM COMPLEX BRIDGE USE</cbc:StreetName>
<cbc:CitySubdivisionName>النخيل | An Nakhil</cbc:CitySubdivisionName>
<cbc:CityName>الرياض | RIYADH</cbc:CityName>

It is recommended to store the information of different languages in separate fields and use merge fields in e-invoice file templates. Suppose that the City field stores the English city name and the CityNameInArabic__c custom field stores the Arabic city name. The cbc:CityName tag in the template should be as follows:

<cbc:CityName>{{CityNameInArabic__c}} | {{City}}</cbc:CityName>

Testing recommendations

Zuora has tested e-invoicing on various billing document types and operations using default e-invoice file templates.
The following table lists the test cases for your reference. 

Billing document type Document source Case category Description

Invoice

Subscription

One charge

Create a subscription containing one rate plan charge with taxation, generate a draft invoice from the subscription, and then post the invoice.

Credit Memo

Invoice

One charge

Create a credit memo from the invoice, and post the credit memo.

Debit Memo

Invoice

One charge

Create a debit memo from the invoice, and post the debit memo.

Credit Memo

Invoice

One charge

Generate an invoice from the subscription, and reverse the invoice to create a credit memo from the invoice.

Credit Memo

Invoice

One charge

Generate an invoice from the subscription, and write off the invoice to create a credit memo from the invoice.

Credit Memo

Subscription

One charge

Generate a credit memo from the subscription cancellation, and post the credit memo.

Debit Memo

Credit Memo

One charge

Reverse the credit memo to create a debit memo from the invoice.

Invoice

Subscription

Multiple charges

Create a subscription containing multiple charges with taxation, generate a draft invoice from the subscription, and then post the invoice.

Credit Memo

Invoice

Multiple charges

Create a credit memo from the invoice, and post the credit memo.

Debit Memo

Invoice

Multiple charges

Create a debit memo from the invoice, and post the debit memo.

Credit Memo

Invoice

Multiple charges

Generate an invoice from the subscription, and reverse the invoice to create a credit memo from the invoice.

Credit Memo

Invoice

Multiple charges

Generate an invoice from the subscription, and write off the invoice to create a credit memo from the invoice.

Credit Memo

Subscription

Multiple charges

Generate a credit memo from the subscription cancellation, and post the credit memo.

Debit Memo

Credit Memo

Multiple charges

Reverse the credit memo to create a debit memo from the invoice.

Invoice

Standalone

Multiple charges

Create a standalone invoice containing multiple items from product rate plan charges, and post the invoice.

Credit Memo

Standalone

Multiple charges

Create a standalone credit memo containing multiple items from product rate plan charges, and post the credit memo.

Debit Memo

Standalone

Multiple charges

Create a standalone debit memo containing multiple items from product rate plan charges, and post the debit memo.

Please note that the testing was performed in the Sovos Sandbox with a testing account, and the following assumptions apply:

  • Zuora uses testing Tax Identification Numbers for the business supplier and buyer, which are not real. 
  • All billing documents have taxation enabled. The documents without taxation have not been tested. If you have business scenarios where documents have no taxation, you must test those scenarios and modify the e-invoice file template accordingly.
  • The taxation addresses are test address data and do not represent the addresses of real business entities.
  • The billing documents include only regular charges, without discount charges. If you use Zuora discount charges, the e-invoice file template customization is required.

Refer to the following sections for more details on scenarios Zuora still needs to test. It is recommended to include these scenarios in your testing if they align with your business requirements.

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

Retrieve e-invoicing results

You can use the Retrieve e-invoicing results operation to retrieve e-invoice results according to the ID of a billing document. The document ID can be the ID of an invoice, a credit memo, or a debit memo.

The e-invoicing result fields might be different by country.

The e-invoicing result fields on EInvoiceData include the following fields for Saudi Arabia:

  • QrCode: This field stores the QR code data that has been Base64 decoded. In Saudi Arabia, this field stores the QR code data that is Base64-encoded Tag, Length, Value (TLV).
  • ReferenceNumber: This field stores a unique number generated by the tax authority. In Saudi Arabia, a unique identifier is assigned to each electronically submitted invoice by the Saudi Arabian tax authority, known as the Zakat, Tax, and Customs Authority (ZATCA). The information is obtained from the UUID field in the cleared document.
  • DocumentId: This field stores the ID of the billing document for which the e-invoice file is generated.
  • DocumentType: This field indicates the type of billing document for which the e-invoice file is generated.

The eInvoiceFileId field on the Invoice object stores the ID of the Base64-encoded e-invoice file, a cleared document in the format of UBL- XML.