Skip to main content

Configure e-invoice file templates for billing documents

Zuora

Configure e-invoice file templates for billing documents

  1. Last updated
  2. Save as PDF

With the E-Invoicing feature, you must configure e-invoice file templates for your billing documents, including invoices, credit memos, and debit memos. 

To configure and manage e-invoice file templates for billing documents through the REST API, use the following operations: 

Zuora provides default e-invoice file templates that you can customize as required. For example, some country-specific fields like Harmonized System of Nomenclature (HSN) might be stored on product rate plan charges.

The E-Invoicing feature provides the following functionalities to simplify and enhance your e-invoice file template development experience through the Zuora UI.

  • Built-in default templates
    • You can jumpstart e-invoice file template creation with new built-in default templates tailored for countries like India, Italy, and Saudi Arabia.
    • You can also customize these templates based on your unique data configurations, significantly reducing the effort compared to starting from scratch.
  • Data schema and functions for templates
    • You can easily access a comprehensive view of all supported objects, fields, and functions available for your templates.
    • This functionality saves you from memorizing object or field names, functions, or their structures.

These enhancements empower you to develop e-invoice file templates more efficiently, providing a smoother and more intuitive experience.

E-invoice file template editor 

In the online e-invoice file template editor, you can switch between the Edit mode and Preview mode to configure and manage e-invoice file templates.

In Edit mode, you can create and customize e-invoice file templates for billing documents according to business demands.

The online e-invoice file template editor in Edit mode mainly consists of the following panels tabs to provide customization capabilities:

  • XML editor in the left panel
    You can configure and customize detailed contents for e-invoice file templates in the XML editor.
  • Data Schema and Functions tabs in the right panel
    • In the Data Schema tab, you can copy and search the objects and fields available to use in e-invoice file templates.
      By default, the root object with its data type is displayed. Invoice is the root object of e-invoice file templates configured for invoices. CreditMemo is the root object of e-invoice file templates configured for credit memos. DebitMemo is the root object of e-invoice file templates configured for debit memos.
      • Clicking the root object row expands all the nested fields and joined objects of the root object. Similarly, clicking a joined object row expands all the nested fields and joined objects of the corresponding object. You can expand at most seven layers of data schema.
      • When hovering over an object name or a field name in the left column, the detailed path of the object or field is displayed as a tooltip. When hovering over the data  type of an object or field in the right column, the copy icon is displayed to replace the original data type. You can click the icon to copy the path of an object or a field, and then paste it to the specific location in the XML editor where you want to apply the object or field. For example, if you click the copy icon in the Invoice > EInvoiceFileId row, the copied content is Invoice.EInvoiceFileId.
      • To search for an object or a field, you can enter keywords in the search bar under the tab name. The objects and fields containing the keyword are automatically displayed as search results.
    • In the Functions tab, you can see all the functions available to use in e-invoice file templates. 
      When hovering over a function name in the left column, the complete function is displayed as a tooltip, containing all available arguments and operators, and the copy icon is displayed in the right column. You can click the icon to copy the complete function, and then paste it to the specific location in the XML editor where you want to apply the function.

In Preview mode, you can select an account and a billing document to preview the rendered e-invoice file online.

Create and preview e-invoice file templates for billing documents through the Zuora UI

You can create e-invoice file templates for billing documents through the Zuora UI, including invoices, credit memos, and debit memos, and then preview e-invoice files.

To create and preview an e-invoice file template for a billing document, 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, click + Create in the Templates section.
  4. In the displayed Create Template - Basic Info dialog, configure the basic template information:
    1. In the Name field, specify a name for the e-invoice file template.
    2. In the Country field, select the country or region where you must comply with e-invoicing requirements.
    3. From the Provider list, select an e-invoicing service provider.
    4. From the Document Type list, select the type of billing documents that you want to create the e-invoice file template for.
    5. Click Save And Edit Content to save the settings and start to edit template content.
      You can also click Save to save the template and edit template content later.
  5. In the displayed e-invoice file template editor, customize and preview the e-invoice file template content.
    1. In the Edit tab of the left panel, customize the e-invoice file template content. 
      Tailored built-in default templates are available for countries including India, Italy, and Saudi Arabia. You can customize the templates based on business demands.
    2. Click Preview to switch to the Preview mode from the Edit mode.
    3. In the Preview Settings section, specify an account and billing document to load the data of the specified account and billing document into your template:

      • In the Account field, search for account keywords and select the account that you want to preview billing documents for.

      • From the Invoice, Credit Memo, or Debit Memo list, select the invoice, credit memo, or debit memo that you want to preview in the e-invoice file template.

        If you create a new account and billing document from another page when the current page is open, you can click the refresh icon icon-refresh.png to load the new account and billing document in the preceding fields. For example, you enable the Generate E-Invoice for Customer setting for an existing account.

    4. Optional. If you update an account and billing document from another page when the current page is open, you can click the refresh icon icon-refresh.png in the Preview tab to load the updated data. For example, you update a custom field on an invoice details page.
    5. Click Save in the upper right to save the e-invoice file template.

An e-invoice file template is created for invoices, credit memos, or debit memos.

The following information is a sample of an e-invoice file template for invoices in Saudi Arabia:

<?xml version="1.0" encoding="utf-8"?>
<StandardBusinessDocument xmlns="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader" xmlns:svs="http://www.sovos.com/namespaces/sovosDocument" xmlns:sci="http://www.sovos.com/namespaces/sovosCanonicalInvoice" xmlns:ad="http://www.sovos.com/namespaces/additionalData" xmlns:sov="http://www.sovos.com/namespaces/sovosExtensions" xmlns:enc="http://www.sovos.com/namespaces/base64Document" xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" >
    <StandardBusinessDocumentHeader>
        {{Cmd_Assign(BusinessRegion,EInvoiceBusinessRegions|FilterByValue(Country,EQ,'SA')|First(1),True)}}
        {{#BusinessRegion}}
        {{Cmd_Assign(VarBusinessNumber,BusinessNumber,True)}}
        {{/BusinessRegion}}
        {{#Invoice.InvoiceItems|FlatMap(TaxationItems)|GroupBy(TaxRateDescription)|First(1)}}
        {{Cmd_Assign(VarTaxCode,TaxRateDescription,True)}}
        {{/Invoice.InvoiceItems|FlatMap(TaxationItems)|GroupBy(TaxRateDescription)|First(1)}}
        <HeaderVersion>1.0</HeaderVersion>
        <Sender>
            <Identifier Authority="SA">{{VarBusinessNumber}}</Identifier>
            <ContactInformation>
                <Contact>{{VarBusinessNumber}}</Contact>
            </ContactInformation>
        </Sender>
        <Receiver>
            <Identifier Authority="SA">{{Invoice.Account.EInvoiceProfile.BusinessNumber}}</Identifier>
            <ContactInformation>
                <Contact>{{Invoice.Account.EInvoiceProfile.BusinessNumber}}</Contact>
            </ContactInformation>
        </Receiver>
        <DocumentIdentification>
            <Standard>urn:oasis:names:specification:ubl:schema:xsd:Invoice-2</Standard>
            <TypeVersion>2.1</TypeVersion>
            <InstanceIdentifier>{{Invoice.InvoiceNumber}}</InstanceIdentifier>
            <Type>Invoice</Type>
            <MultipleType>false</MultipleType>
            <CreationDateAndTime>{{Invoice.CreatedDate|Format(yyyy-MM-dd'T'HH:mm:ss'Z')}}</CreationDateAndTime>
        </DocumentIdentification>
        <BusinessScope>
            <Scope>
                <Type>Country</Type>
                <InstanceIdentifier/>
                <Identifier>SA</Identifier>
            </Scope>
            <Scope>
                <Type>Mapping.TransformDocument</Type>
                <InstanceIdentifier/>
                <Identifier>SCI-TO-LEGAL_INVOICE</Identifier>
            </Scope>
            <Scope>
                <Type>Mapping.OutputSchema</Type>
                <InstanceIdentifier/>
                <Identifier>UBLInvoice</Identifier>
            </Scope>
            <Scope>
                <Type>CompanyCode</Type>
                <InstanceIdentifier/>
                <Identifier>{{VarBusinessNumber}}</Identifier>
            </Scope>
            <Scope>
                <Type>SenderDocumentId</Type>
                <InstanceIdentifier/>
                <Identifier>{{Invoice.InvoiceNumber}}</Identifier>
            </Scope>
            <Scope>
                <Type>SenderSystemId</Type>
                <InstanceIdentifier/>
                <Identifier>ZUORASA</Identifier>
            </Scope>
            <Scope>
                <Type>ProcessType</Type>
                <InstanceIdentifier/>
                <Identifier>Outbound</Identifier>
            </Scope>
            <Scope>
                <Type>BusinessProcess</Type>
                <InstanceIdentifier/>
                <BusinessService>
                    <BusinessServiceName>Default</BusinessServiceName>
                </BusinessService>
            </Scope>
            <Scope>
                <Type>BusinessCategory</Type>
                <InstanceIdentifier/>
                <Identifier>B2B</Identifier>
            </Scope>
            <Scope>
                <Type>MetaSchema</Type>
                <InstanceIdentifier/>
            </Scope>
            <Scope>
                <Type>Version</Type>
                <InstanceIdentifier/>
                <Identifier>1.0</Identifier>
            </Scope>
            <Scope>
                <Type>Branch</Type>
                <InstanceIdentifier/>
                <Identifier>YOUR-BRANCH</Identifier><!-- will be configured by customer !-->
            </Scope>
        </BusinessScope>
    </StandardBusinessDocumentHeader>
    <svs:SovosDocument>
        <sci:SovosCanonicalInvoice>
            {{#Invoice}}
            <Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2">
                <cbc:ProfileID>reporting:1.0</cbc:ProfileID>
                <cbc:ID>{{InvoiceNumber}}</cbc:ID>
                <cbc:UUID>{{#Wp_Eval}} "{{Id}}".replaceAll("(.{8})(.{4})(.{4})(.{4})(.{12})", "$1-$2-$3-$4-$5") {{/Wp_Eval}}</cbc:UUID>
                <cbc:IssueDate>{{InvoiceDate}}</cbc:IssueDate>
                <cbc:IssueTime>00:00:00</cbc:IssueTime> <!-- Zuora doesn't store Time value !-->
                <cbc:InvoiceTypeCode name="0100000">388</cbc:InvoiceTypeCode>
                <cbc:DocumentCurrencyCode>{{Account.Currency}}</cbc:DocumentCurrencyCode>
                <cbc:TaxCurrencyCode>{{Account.Currency}}</cbc:TaxCurrencyCode>
                <cac:Signature>
                    <cbc:ID>urn:oasis:names:specification:ubl:signature:Invoice</cbc:ID>
                    <cbc:SignatureMethod>urn:oasis:names:specification:ubl:dsig:enveloped:xades</cbc:SignatureMethod>
                </cac:Signature>
                {{#BusinessRegion}}
                <cac:AccountingSupplierParty>
                    <cac:Party>
                        <cac:PartyIdentification>
                            <cbc:ID schemeID="CRN">{{VarBusinessNumber}}</cbc:ID>
                        </cac:PartyIdentification>
                        <cac:PostalAddress>
                            <cbc:StreetName>{{AddressLine1}}</cbc:StreetName>
                            <cbc:BuildingNumber>{{AddressLine2}}</cbc:BuildingNumber> <!-- This merge field should have Integer value with 4digits !-->
                            <cbc:CitySubdivisionName>{{State}}</cbc:CitySubdivisionName>
                            <cbc:CityName>{{City}}</cbc:CityName>
                            <cbc:PostalZone>{{PostalCode}}</cbc:PostalZone>
                            <cac:Country>
                                <cbc:IdentificationCode>SA</cbc:IdentificationCode>
                            </cac:Country>
                        </cac:PostalAddress>
                        <cac:PartyTaxScheme>
                            <cbc:CompanyID>{{VarBusinessNumber}}</cbc:CompanyID>
                            <cac:TaxScheme>
                                <cbc:ID>{{VarTaxCode}}</cbc:ID>
                            </cac:TaxScheme>
                        </cac:PartyTaxScheme>
                        <cac:PartyLegalEntity>
                            <cbc:RegistrationName>{{BusinessName}}</cbc:RegistrationName>
                        </cac:PartyLegalEntity>
                    </cac:Party>
                </cac:AccountingSupplierParty>
                {{/BusinessRegion}}
                <cac:AccountingCustomerParty>
                    <cac:Party>
                        <cac:PartyIdentification>
                            <cbc:ID schemeID="CRN">{{Account.EInvoiceProfile.BusinessNumber}}</cbc:ID>
                        </cac:PartyIdentification>
                        <cac:PostalAddress>
                            <cbc:StreetName>{{#Wp_Eval}} "{{BillToContact.Address1}}" != '' ? "{{BillToContact.Address1}}":"{{Account.BillTo.Address1}}"{{/Wp_Eval}}</cbc:StreetName>
                            <cbc:BuildingNumber>{{#Wp_Eval}} "{{BillToContact.Address2}}" != '' ? "{{BillToContact.Address2}}":"{{Account.BillTo.Address2}}"{{/Wp_Eval}}</cbc:BuildingNumber> <!-- This merge field should have Integer value with 4digits !-->
                            <cbc:CitySubdivisionName>{{#Wp_Eval}} "{{Invoice.BillToContact.State}}" != '' ? "{{Invoice.BillToContact.State}}":"{{Account.BillTo.State}}"{{/Wp_Eval}}</cbc:CitySubdivisionName>
                            <cbc:CityName>{{#Wp_Eval}} "{{Invoice.BillToContact.City}}" != '' ? "{{Invoice.BillToContact.City}}":"{{Account.BillTo.City}}"{{/Wp_Eval}}</cbc:CityName>
                            <cbc:PostalZone>{{#Wp_Eval}} "{{Invoice.BillToContact.PostalCode}}" != '' ? "{{Invoice.BillToContact.PostalCode}}":"{{Account.BillTo.PostalCode}}"{{/Wp_Eval}}</cbc:PostalZone>
                            <cac:Country>
                                <cbc:IdentificationCode>SA</cbc:IdentificationCode>
                            </cac:Country>
                        </cac:PostalAddress>
                        <cac:PartyTaxScheme>
                            <cac:TaxScheme>
                                <cbc:ID>{{VarTaxCode}}</cbc:ID>
                            </cac:TaxScheme>
                        </cac:PartyTaxScheme>
                        <cac:PartyLegalEntity>
                            <cbc:RegistrationName>{{Account.EInvoiceProfile.BusinessName}}</cbc:RegistrationName>
                        </cac:PartyLegalEntity>
                    </cac:Party>
                </cac:AccountingCustomerParty>
                <cac:Delivery>
                    <cbc:ActualDeliveryDate>{{Invoice.InvoiceDate}}</cbc:ActualDeliveryDate>
                    <cbc:LatestDeliveryDate>{{Invoice.InvoiceDate}}</cbc:LatestDeliveryDate>
                </cac:Delivery>
                <cac:PaymentTerms>
                    <cbc:Note>05</cbc:Note> <!-- Internal proposal to have value -5 !-->
                    <cbc:Amount currencyID="{{Account.Currency}}">{{Amount|Round(2)}}</cbc:Amount>
                </cac:PaymentTerms>
                <cac:TaxTotal>
                    <cbc:TaxAmount currencyID="{{Account.Currency}}">{{TaxAmount|Round(2)}}</cbc:TaxAmount>
                </cac:TaxTotal>
                <cac:TaxTotal>
                    <cbc:TaxAmount currencyID="{{Account.Currency}}">{{TaxAmount|Round(2)}}</cbc:TaxAmount>
                    {{#InvoiceItems|GroupBy(TaxCode)}}
                    {{Cmd_Assign(GroupedByTaxCode,_Group)}}
                    <cac:TaxSubtotal>
                        <cbc:TaxableAmount currencyID="{{Account.Currency}}">{{GroupedByTaxCode|Sum(ChargeAmount)|Round(2)}}</cbc:TaxableAmount>
                        <cbc:TaxAmount currencyID="{{Account.Currency}}">{{GroupedByTaxCode|FlatMap(TaxationItems)|Sum(TaxAmount)|Round(2)}}</cbc:TaxAmount>
                        {{#GroupedByTaxCode|FlatMap(TaxationItems)|First(1)}}
                        <cac:TaxCategory>
                            <cbc:ID>S</cbc:ID>
                            <cbc:Percent>{{#Wp_Eval}} {{TaxRate}} * 100|Round(2) {{/Wp_Eval}}</cbc:Percent>
                            <cac:TaxScheme>
                                <cbc:ID>{{TaxRateDescription}}</cbc:ID>
                            </cac:TaxScheme>
                        </cac:TaxCategory>
                        {{/GroupedByTaxCode|FlatMap(TaxationItems)|First(1)}}
                    </cac:TaxSubtotal>
                    {{/InvoiceItems|GroupBy(TaxCode)}}
                </cac:TaxTotal>
                <cac:LegalMonetaryTotal>
                    <cbc:LineExtensionAmount currencyID="{{Account.Currency}}">{{AmountWithoutTax|Round(2)}}</cbc:LineExtensionAmount>
                    <cbc:TaxExclusiveAmount currencyID="{{Account.Currency}}">{{AmountWithoutTax|Round(2)}}</cbc:TaxExclusiveAmount>
                    <cbc:AllowanceTotalAmount currencyID="{{Account.Currency}}">0.00</cbc:AllowanceTotalAmount>
                    <cbc:PrepaidAmount currencyID="{{Account.Currency}}">0.00</cbc:PrepaidAmount>
                    <cbc:PayableAmount currencyID="{{Account.Currency}}">{{Amount|Round(2)}}</cbc:PayableAmount>
                </cac:LegalMonetaryTotal>
                {{Cmd_Assign(LineSerialNumber,"1",true)}}
                {{#Invoice.InvoiceItems|FilterByValue(ProcessingType,NE,1)}}
                <cac:InvoiceLine>
                    <cbc:ID>{{#Wp_Eval}}{{LineSerialNumber}}+1|SetToVar(LineSerialNumber){{/Wp_Eval}}</cbc:ID>
                    <cbc:InvoicedQuantity unitCode="{{UOM}}">{{Quantity}}</cbc:InvoicedQuantity>
                    <cbc:LineExtensionAmount currencyID="{{Account.Currency}}">{{ChargeAmount|Round(2)}}</cbc:LineExtensionAmount>
                    <cac:PricingReference>
                        <cac:AlternativeConditionPrice>
                            <cbc:PriceAmount currencyID="{{Account.Currency}}">{{ChargeAmount|Round(2)}}</cbc:PriceAmount>
                            <cbc:PriceTypeCode>02</cbc:PriceTypeCode>
                        </cac:AlternativeConditionPrice>
                    </cac:PricingReference>
                    <cac:TaxTotal>
                        <cbc:TaxAmount currencyID="{{Account.Currency}}">{{TaxAmount|Round(2)}}</cbc:TaxAmount>
                        <cbc:RoundingAmount currencyID="{{Account.Currency}}">{{#Wp_Eval}} {{ChargeAmount|Round(2)}} + {{TaxAmount|Round(2)}} {{/Wp_Eval}}</cbc:RoundingAmount>
                    </cac:TaxTotal>
                    <cac:Item>
                        <cbc:Name>{{ChargeName}}</cbc:Name>
                        {{#TaxationItems}}
                        <cac:ClassifiedTaxCategory>
                            <cbc:ID>S</cbc:ID>
                            <cbc:Percent>{{#Wp_Eval}} {{TaxRate}} * 100|Round(2) {{/Wp_Eval}}</cbc:Percent>
                            <cac:TaxScheme>
                                <cbc:ID>{{TaxRateDescription}}</cbc:ID>
                            </cac:TaxScheme>
                        </cac:ClassifiedTaxCategory>
                        {{/TaxationItems}}
                    </cac:Item>
                    <cac:Price>
                        <cbc:PriceAmount currencyID="{{Account.Currency}}">{{UnitPrice}}</cbc:PriceAmount>
                    </cac:Price>
                </cac:InvoiceLine>
                {{/Invoice.InvoiceItems|FilterByValue(ProcessingType,NE,1)}}
            </Invoice>
            {{/Invoice}}
        </sci:SovosCanonicalInvoice>
    </svs:SovosDocument>
</StandardBusinessDocument>

Edit e-invoice file templates for billing documents through the Zuora UI

After an e-invoice file template is created for a billing document, you can edit its basic information and template contents as needed.

To edit an e-invoice file template created for a billing document, 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. To edit basic information about an e-invoice file template, perform the following steps:
    1. In the corresponding row of the e-invoice file template, click the more options icon and then click Edit Basic Information.
    2. In the displayed Create Template - Basic Info dialog, configure the basic template information and save the template.
  5. To edit the content of an e-invoice file template, perform the following steps:
    1. In the corresponding row of the e-invoice file template, click the Edit Content icon.
    2. In the displayed e-invoice file template editor, customize and preview the e-invoice file template content, and then click Save in the upper right to save the e-invoice file template.

The corresponding e-invoice file template is edited for invoices, credit memos, or debit memos.

Delete e-invoice file templates for billing documents through the Zuora UI

If an e-invoice file template is no longer used, you can delete it as needed.

To delete an e-invoice file template for a billing document through the Zuora UI, 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 corresponding row of the e-invoice file template, click the more options icon and then click Delete.
  5. In the displayed Confirm dialog, click Delete to confirm the deletion request.

The corresponding e-invoice file template is deleted for invoices, credit memos, or debit memos.

Create custom fields specific to e-invoicing

You are required to create and manage custom fields to store country-specific information for mapping to Sovos. It is best practice to use the objects and custom fields listed in the following table. 

Object Custom field Notes

Product Rate Plan Charge

HSN__c

Create this custom field of the string type to store HSN codes.

While configuring e-invoicing for India, ensure that you configure HSN codes for all your products and services under the Product Catalog. Electronic billing documents can be generated only with an HSN code. The use of HSN codes is mainly for dealers and trades. They must adopt 2-digit, 4-digit, and 8-digit HSN codes depending on the business turnover. For more information, see GST HSN Codes.

Account

SupplyType__c

Create this custom field of the picklist type to store the type of supply. This picklist field has the following options: 

  • B2B: business to business
  • SEZWP: SEZ with payment
  • SEZWOP: SEZ without payment
  • EXPWP: export with payment
  • EXPWOP: export with payment
  • DEXP: deemed export

Note that the values of the picklist field must use short names like B2B, SEZWP, and so on.

These custom fields are integral to the default e-invoice file templates. If you opt to define custom fields with different names or on alternative objects, you are required to make adjustments to the default templates.

Field mapping for e-invoice file templates

E-invoice file templates follow the same merge field syntax as HTML templates, and support the same set of objects and fields as HTML templates.