Skip to main content

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

Zuora

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

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

The high-level procedure is as follows:

  1. Prepare data for end-to-end testing.
  2. Create and test e-invoice file templates.
  3. Configure response field mapping.
  4. Complete end-to-end testing.

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.

Make sure that the Business Category of an account in your tenant complies with the country mandate configuration in Avalara. For example, Zuora follows the AU-B2B-PEPPOL mandate when submitting a billing document for Australian accounts with the Business Category configured to B2B. However, if you have not configured the B2B mandate for Australia in Avalara, the e-invoicing transaction will fail. For more information about how to configure country mandates in Avalara, see Configure Avalara sandbox environment.

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 Avalara 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 Avalara E-Invoicing, Zuora generates an Avalara-compliant electronic billing document based on the e-invoice file template and then submits the electronic billing document to Avalara.

For more information about Avalara’s file format regulations, see E-Invoicing mandate definitions in Avalara’s documents. On this page, you can view lists of required, conditional, and optional tags of each country mandate, along with the path and description of each tag.

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

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

Zuora provides default e-invoice file templates for pre-integrated countries such as Australia and Mexico. 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:

  1. 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.
  2. Customize the template as needed.
    If the mandate for a business category of a particular country differs from another business category of the same country in Avalara, you must customize the template to make it comply with all mandates you enabled in Avalara. For more information about the business category configuration, see Configure e-invoicing profile for customer accounts.
    You can use merge fields in e-invoicing file templates. The merge field syntax is the same as HTML templates, including supported objects, fields, and functions. For more information, see Merge field syntax for HTML templates.
    For example, the following code sample returns different tags for B2B, B2C, and other accounts by using an Expression:
    {{#Wp_Eval}}
        "{{Invoice.Account.EInvoiceProfile.BusinessCategory}}" == "B2B" ? "<B2BTag>Available for B2B accounts</B2BTag>" : "{{Invoice.Account.EInvoiceProfile.BusinessCategory}}" == "B2C" ? "<B2CTag>Available for B2C accounts</B2CTag>" : "<GeneralTag>Available for other accounts</GeneralTag>"
    {{/Wp_Eval}
    
  3. 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

You can create e-invoicing file templates for any country supported by Avalara, regardless of whether Zuora is pre-integrated with this country.

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

  1. 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.
  2. In the displayed e-invoice file template editor, edit the e-invoice file template content:
    1. Identify the country mandate XML sample code on the E-Invoicing mandate definitions page in Avalara’s documents.
    2. Replace everything in the Edit tab with the XML sample code in step a.
    3. Replace account and billing-document-related content with merge fields.
      All account and billing-document-related content are fixed values in the sample code. You must replace them with merge fields. For example, replace the invoice number with {{Invoice.InvoiceNumber}}.
      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.
    4. Customize the template as needed.
      If the mandate for a business category of a particular country differs from another business category of the same country in Avalara, you must customize the template to make it comply with all mandates you enabled in Avalara. For more information about the business category configuration, see Configure e-invoicing profile for customer accounts.
      For example, the following code sample returns different tags for B2B, B2C, and other accounts by using an Expression:
      {{#Wp_Eval}}
          "{{Invoice.Account.EInvoiceProfile.BusinessCategory}}" == "B2B" ? "<B2BTag>Available for B2B accounts</B2BTag>" : "{{Invoice.Account.EInvoiceProfile.BusinessCategory}}" == "B2C" ? "<B2CTag>Available for B2C accounts</B2CTag>" : "<GeneralTag>Available for other accounts</GeneralTag>"
      {{/Wp_Eval}}
    5. 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:

  1. Click your avatar in the upper right and click Settings > Billing.
  2. On the Billing Settings page, click E-Invoice.
  3. On the E-Invoice Settings page, scroll down to the Templates section.
  4. In the Templates section, locate the e-invoice file template you want to preview and click the Edit Content edit2.png icon. The e-invoice file template editor opens.
  5. Click Preview to switch from the Edit mode to the Preview mode.
  6. 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.
  7. If the validation fails, resolve the template format errors in the Edit mode.
    Error messages are displayed in the left panel.
    error_message.png
  8. If the E-Invoice Status is Failed in the Preview Settings section, click Download Logs and then click the Edit tab to resolve the error in the Edit mode. After that, click the Preview tab to switch back to the Preview mode and then click Regenerate E-Invoice. You can switch between two tabs to resolve errors until the E-Invoice Status changes to Success.
    The error can either be a Zuora-generated error or one returned by Avalara. 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.
    avalara_einvoice_file_template.png
  9. 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 Avalara successfully processes e-invoicing documents, Avalara 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 Australia and Mexico. 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 E-invoicing response field mapping for Avalara and 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 Avalara sandbox environment.

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

  1. Create a draft invoice with taxation items that comply with the country's tax laws.
    For more information, see Create subscriptions and invoices.
  2. Post the invoice.
  3. 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 Avalara 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.