Configure e-invoice file template and complete end-to-end testing

Last updated
Save as PDF

This article describes how to prepare data for testing and complete end-to-end testing for e-invoicing with the Sovos sandbox environment.

The high-level procedure is as follows:

Prepare data for end-to-end testing.
Create and test e-invoice file templates.
Configure response field mapping.
Complete end-to-end testing.
Obtain UAT sign-off from Sovos.

Prepare data for end-to-end testing

Before conducting end-to-end testing, you must configure your Zuora tenant to prepare data for testing such as customer accounts, subscriptions, and invoices.

Configure country-specific settings

You might need to configure country-specific settings if you want to e-invoice your customers in particular countries. For example, specifying specific business information on business regions or creating custom fields on standard objects.

For more information, see Manage country-specific configurations.

Configure e-invoicing profile for customer accounts

You have the flexibility to enable e-invoicing for customers based on the regulatory requirements of countries. For example, you can enable e-invoicing only for business customers or customers from particular countries.

When enabling e-invoicing for a customer who acts as a buyer, you must collect the business profile of the customer and configure the e-invoicing profile during the customer account creation or modification. For more information about supported profile settings, see E-invoicing profile settings for accounts.

To configure the e-invoicing profile for a customer account in Zuora UI, see Configure e-invoicing profiles for accounts through the Zuora UI.

Alternatively, you can use the Create an account or Update an account API operation.

Create subscriptions and invoices

For testing purposes, you must create subscriptions and invoices with taxation information.

To create a subscription, see Create subscriptions.

When subscriptions are created, you can create bill runs to generate invoices. For more information, see Create bill runs.

Create and test e-invoice file templates

Before sending electronic billing documents to the Sovos sandbox environment, you must create e-invoice file templates in Zuora for Invoice, Credit Memo, and Debit Memo.

When a billing document is posted for a customer from a country that supports e-invoicing, Zuora generates a Sovos-compliant electronic billing document based on the e-invoice file template and then sends the electronic billing document to Sovos.

For more information about Sovos’ requirements regarding the document format, see Standard business documents for Sovos.

The procedure for creating an e-invoice file template varies depending on whether it is for a country with which Zuora is pre-integrated.

Create an e-invoice file template for a pre-integrated country

Zuora provides default e-invoice file templates for pre-integrated countries such as India, Italy, and Saudi Arabia. For a complete list of pre-integrated countries, see Pre-integrated countries.

To create an e-invoice file template for a pre-integrated country in Zuora UI, perform the following steps:

Perform steps 1 to 4 in Create and preview e-invoice file templates for billing documents through the Zuora UI.
Make sure to click Save And Edit Content in the last step.
In the displayed e-invoice file template editor, where a default template is available in the Edit tab, search for a Type tag with the value SenderSystemId and replace the value of the same-level Identifier tag with your sender system ID in Sovos. For more information about Sender System ID in Sovos, see Configure Sovos sandbox environment.
```
<Scope>
    <Type>SenderSystemId</Type> 
    <InstanceIdentifier/>
    <Identifier>YourSenderSystemId</Identifier> 
</Scope>
```
(Optional) Customize the template as needed.
You can customize XML tags or merge fields in the template to meet your specific business needs in the country. For example, configuring country-specific settings. For more information, see Manage country-specific configurations.
The merge field syntax in e-invoice file templates is the same as HTML templates, including supported objects, fields, and functions. For more information, see Merge field syntax for HTML templates.
Click Save in the upper right to save the e-invoice file template.

Alternatively, you can use the Create an e-invoice file template API operation.

Create an e-invoice file template for a country not pre-integrated with Zuora

Zuora provides common e-invoice file templates for all billing document types in non-pre-integrated countries. Unlike pre-integrated countries, you must modify the template according to Sovos’ regulations for each country before starting the e-invoicing service in that country.

To create an e-invoice file template for a country not pre-integrated with Zuora in Zuora UI, perform the following steps:

Perform steps 1 to 4 in Create and preview e-invoice file templates for billing documents through the Zuora UI.
Make sure to click Save And Edit Content in the last step.
In the displayed e-invoice file template editor, modify the template according to the country-specific request sample payload provided by Sovos and the Sovos Canonical Invoice (SCI) format requirements for that country.
1. Add the required XML tags if they are not included in the template.
2. Update the merge fields as needed.
  Zuora has pre-defined some merge fields in the common templates. These default merge fields might not meet your specific business needs in the country. For example, you must specify your Sovos sender system ID in the template. You can find more customization suggestions in the template comments.
  Additionally, if you use custom fields to track information on seller, buyer, or billing documents, you must update the relevant merge fields accordingly.
  The merge field syntax in e-invoicing file templates is the same as HTML templates, including supported objects, fields, and functions. For more information, see Merge field syntax for HTML templates.
Click Save in the upper right to save the e-invoice file template.

Alternatively, you can use the Create an e-invoice file template API operation.

Preview and test e-invoice file templates

When e-invoice file templates are created, you must preview and test each e-invoice file template by specifying an account and billing document in the e-invoice file template editor.

To preview and test an e-invoice file template, perform the following steps:

Click your avatar in the upper right and click Settings > Billing.
On the Billing Settings page, click E-Invoice.
On the E-Invoice Settings page, scroll down to the Templates section.
In the Templates section, locate the e-invoice file template you want to preview and click the Edit Content icon. The e-invoice file template editor opens.
Click Preview to switch from the Edit mode to the Preview mode.
In the Preview Settings section, specify an account and billing document.
Zuora will load the data of the specified account and billing document into your template and validate the template.
For more information, see step 5 in Create and preview e-invoice file templates for billing documents through the Zuora UI.
If the validation fails, resolve the template format errors in the Edit mode.
Error messages are displayed in the left panel.
If the E-Invoice Status is Failed in the Preview Settings section, resolve the error and click Regenerate E-Invoice to confirm the error is resolved.
The error can either be a Zuora-generated error or one returned by Sovos. For more information about error types and resolutions, see View e-invoice file status and error information through the Zuora UI.
The E-Invoice Status field is available only if you have configured the e-invoicing profile for the account and posted the invoice. For more information, see Configure e-invoicing profile for customer accounts.
Click Save in the upper right to save the e-invoice file template.

Configure response field mapping

In certain countries, the tax authority generates a unique number or QR code that must be displayed on printed invoices.

When Sovos successfully processes e-invoicing documents, Sovos sends this information to Zuora in the response data, and Zuora stores the data in the EInvoiceData object.

Zuora has handled the response field mapping for countries with which Zuora is pre-integrated, such as India, Italy, and Saudi Arabia. For other countries, you can configure the response field mapping to store any data as needed.

For more information about supported response fields, field path format, and how to configure or retrieve e-invoicing response data, see Configure e-invoicing response field mappings.

Complete end-to-end testing

After creating e-invoice file templates for billing documents, you must ensure that invoices, credit memos, and debit memos can be successfully submitted to the Sovos sandbox environment.

To submit an invoice to the Sovos sandbox environment, perform the following steps:

Create a draft invoice with taxation items that comply with the country's tax laws.
For more information, see Create subscriptions and invoices.
Post the invoice.
Ensure the e-invoice file status of the invoice is Success.
For more information, see View e-invoice file status and error information through the Zuora UI.

The procedure for submitting credit memos or debit memos is similar to the preceding procedure.

Zuora recommends that you perform the following operations to ensure the billing documents are automatically submitted to the Sovos sandbox environment under different circumstances. It is optional to perform all operations listed below. You can tailor the operations according to your business needs.

Billing document	Operations
Invoice	Post an invoice.
Credit Memo	Post a credit memo generated from canceling a subscription. Create and post an ad-hoc credit memo from an invoice. Create and post a standalone credit memo from a product rate plan charge. Reverse an invoice to create a credit memo from the invoice. Write off an invoice to create a credit memo from the invoice.
Debit Memo	Create and post an ad-hoc debit memo from an invoice. Create and post a standalone debit memo from a product rate plan charge. Reverse a credit memo generated from a bill run. It creates a debit memo from the credit memo. Write off a credit memo to create a debit memo from the credit memo.

Obtain UAT sign-off from Sovos

When the end-to-end testing is complete and successful, you must obtain UAT (sandbox) sign-off from Sovos. The sign-off is country-specific, which means that a UAT sign-off is needed for each country in which you want to enable the Sovos e-invoicing service.

Sovos evaluates your API calls and e-invoicing data format in the sandbox environment. If they fulfill Sovos’ requirements, Sovos will grant you a sign-off, which is a prerequisite for sending data to the Sovos production environment.

You need to collect the following information when executing the end-to-end tests and provide it to Sovos for evaluation:

Correlation ID: The unique ID of an API call. Once you successfully submit the e-invoice data to Sovos, you can download the logs and obtain the Correlation ID.
Document ID: The UUID of the billing document in Zuora. For example, an invoice ID such as 1bc3ecd26911a3c77072d0eff9fcd550.