This task guides you through integrating PEPPOL with Zuora, including setting up service providers, configuring business regions, and customizing e-invoice templates.

1. Create an e-invoicing service provider for PEPPOL in Zuora UI or through the REST API.

   To create a service provider in Zuora UI, see Set up your e-invoicing service provider through the Zuora UI . Remember to select PEPPOL from the Provider list for the configuration.

   Alternatively, you can use the Create an e-invoicing service provider API operation.

   The following is the endpoint and a sample request body.

   POST /v1/einvoice/service-providers

   {
       "name": "PEPPOL e-invoice service provider",
       "provider": "PEPPOL"
   }

   The following is a sample response body.

   {
       "id": "8a90d6128dfd1585018dfd356bb704ab",
       "provider": "PEPPOL",
       "apiKey": null,
       "test": false,
       "name": "PEPPOL e-invoice service provider",
       "companyIdentifier": null,
       "serviceProviderNumber": "EISP-00000002",
       "success": true
   }

2. Create e-invoicing business regions for the PEPPOL service provider

   After setting up a service provider for PEPPOL, you need to create one or more e-invoicing business regions for the PEPPOL service provider in Zuora UI or through the REST API.

   To create an e-invoicing business region in Zuora UI, see Create e-invoicing business regions through the Zuora UI . Remember to select the PEPPOL service provider you created in step 1 from the Provider list for the configuration.

   The following table lists the business region settings and field mapping in PEPPOL. You can modify the mapping to meet your business needs by customizing the e-invoice file templates. For more information, see Customize e-invoice file templates .

   UI section	UI field	API field	Required or optional	Default PEPPOL field mapping
   Basic Info	Country	country	Required	cac:PostalAddress->cac:Country
   	Legal Business Name	businessName	Required	cbc:PartyLegalEntity->cbc:RegistrationName
   	Legal Business Number	businessNumber	Optional	cac:PartyIdentification or cbc:PartyLegalEntity->cbc:CompanyID
   	Business Number Schema Id	businessNumberSchemeId	Optional	cac:PartyIdentification@schemeID or cbc:PartyLegalEntity->cbc:CompanyID@schemeID
   	Trade Name	tradeName	Optional	cac:PartyName
   	Tax Register Number	taxRegisterNumber	Optional	cbc:PartyTaxScheme->cbc:CompanyID
   	E-Invoice Destination Code	endpointId	Optional	cbc:EndpointID
   	E-Invoice Destination Code Schema Id	endpointSchemeId	Optional	cbc:EndpointID@schemeID
   Business Address	Address 1	addressLine1	Optional	cac:PostalAddress->cbc:StreetName
   	Address 2	addressLine2	Optional	cac:PostalAddress->cbc:AdditionalStreetName
   	Postal Code	postalCode	Optional	cac:PostalAddress->cbc:PostalZone
   	City	city	Optional	cac:PostalAddress->cbc:CityName
   	State/Province	state	Optional	cac:PostalAddress->cbc:CountrySubentity
   Contact Info	Contact Name	contactName	Optional	cac:Contact->cbc:Name
   	Email	email	Optional	cac:Contact->cbc:ElectronicMail
   	Business Phone Number	phoneNumber	Optional	cac:Contact->cbc:Telephone
   Service Provider	Provider	serviceProviderId	Required	(N/A)

   Alternatively, you can use the Create an e-invoicing business region API operation.

   The following is the endpoint and a sample request body.

   POST /v1/einvoice/business-regions

   {
       "country": "GB",
       "businessName": "UK ABC Corp.",
       "businessNumber": "20002039",
       "businessNumberSchemeId": "088",
       "tradeName": "Zuora",
       "taxRegisterNumber": "5544332211",
       "endpointId": "08992",
       "endpointSchemeId": "088",
       "addressLine1": "",
       "addressLine2": "",
       "postalCode": "",
       "city": "",
       "state": "",
       "contactName": "",
       "email": "",
       "phoneNumber": "",
       "serviceProviderId": "8a90d6128dfd1585018dfd356bb704ab"
   }

   The following is a sample response body.

   {
       "id": "8a90a04d8dfd2bda018dfdaa0ad50d8d",
       "country": "GB",
       "businessName": "UK ABC Corp.",
       "businessNumber": "20002039",
       "businessNumberSchemeId": "088",
       "tradeName": "Zuora",
       "endpointId": "08992",
       "endpointSchemeId": "088",
       "taxRegisterNumber": "5544332211",
       "state": "",
       "city": "",
       "postalCode": "",
       "addressLine1": "",
       "addressLine2": "",
       "contactName": "",
       "phoneNumber": "",
       "email": "",
       "serviceProviderId": "8a90d6128dfd1585018dfd356bb704ab",
       "businessRegionNumber": "EIBR-00000006",
       "digitalSignatureEnable": false,
       "digitalSignatureBoxEnable": false,
       "digitalSignatureBoxPosX": 0,
       "digitalSignatureBoxPosY": 0,
       "success": true
   }

3. Configure e-invoice file templates for billing documents.

   There are two sub-steps for configuring e-invoice file templates for billing documents:

   1. Create e-invoice file templates

      An e-invoice file template applies to a specific billing document type such as Invoice, Credit Memo, or Debit Memo. You can create an e-invoice file template in Zuora UI or through the REST API.

      Note that Zuora provides a default e-invoice file template only for the Invoice billing document type. If you need e-invoice file templates for Credit Memo or Debit Memo, you must build the templates from scratch.

      In addition, the default e-invoice file template for Invoice does not support discount charges and standalone invoices. You need to customize the template to support these features.

      To create an e-invoice file template in Zuora UI, see Create and preview e-invoice file templates for billing documents through the Zuora UI . Pay attention to the following fields for the configuration:

      • Provider: Select PEPPOL from the list.

      • Country: Select the country in the PEPPOL business region created in step 2.

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

      The following is the endpoint and a sample request body for creating an e-invoice file template for Invoice.

      POST /v1/einvoice/templates

      {
          "name": "PEPPOL e-invoice template for Invoice - UK",
          "country": "GB",
          "provider": "PEPPOL",
          "documentType": "Invoice",
          "content": "<base64 encoded content>"
      }

      The following is a sample response body.

      {
          "id": "8a90d6128dfd3d13018dfdda246a0d78",
          "country": "GB",
          "name": "PEPPOL e-invoice template for Invoice - UK",
          "documentType": "Invoice",
          "provider": "PEPPOL",
          "templateNumber": "EITEMP-00000029",
          "content": "<base64 encoded content>",
          "success": true
      }

      Note that you must specify the content for the template when creating e-invoice templates through the REST API. If the template is for Invoice, the content will overwrite the default template provided by Zuora.

   2. (Optional) Customize e-invoice file templates

      One advantage of using PEPPOL is the flexibility to customize e-invoice templates to accommodate country-specific mappings and customer-specific configurations.

      After creating an e-invoice file template for a PEPPOL business region, you can customize the template in Zuora UI or through the REST API.

      To customize an e-invoice file template in Zuora UI, see E-invoice file template editor and Edit e-invoice file templates for billing documents through the Zuora UI .

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

      The following is the endpoint and a sample request body for updating an e-invoice file template for Invoice.

      PUT /v1/einvoice/templates/<key>

      {
          "country": "GB",
          "provider": "PEPPOL",
          "documentType": "Invoice",
          "content": "<base64 encoded content>"
      }

      The following is a sample response body.

      {
          "id": "8a90d6128dfd3d13018dfdda246a0d78",
          "country": "GB",
          "name": "PEPPOL e-invoice template for Invoice - UK",
          "documentType": "Invoice",
          "provider": "PEPPOL",
          "templateNumber": "EITEMP-00000029",
          "content": "<base64 encoded content>",
          "success": true
      }

4. Configure the e-invoicing profile for customer accounts.

   You can configure the e-invoicing profile when creating or updating a customer account in Zuora UI or through the REST API.

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

   The following table lists the e-invoicing profile settings and field mapping in PEPPOL. You can modify the mapping to meet your business needs by customizing the e-invoice file templates. For more information, see Customize e-invoice file templates .

   UI field	API field	Required or optional	Default PEPPOL field mapping
   Generate E-Invoice for Customer	enabled	Optional	(N/A)
   Legal Business Name	businessName	Optional	cbc:PartyLegalEntity->cbc:RegistrationName
   Legal Business Number	businessNumber	Optional	cac:PartyIdentification or cbc:PartyLegalEntity->cbc:CompanyID
   Business Number Schema Id	businessNumberSchemeId	Optional	cac:PartyIdentification@schemeID or cbc:PartyLegalEntity->cbc:CompanyID@schemeID
   Trade Name	tradeName	Optional	cac:PartyName
   Tax Register Number	taxRegisterNumber	Optional	cbc:PartyTaxScheme->cbc:CompanyID
   E-Invoice Destination Code	endpointId	Optional	cbc:EndpointID
   E-Invoice Destination Code Schema Id	endpointSchemeId	Optional	cbc:EndpointID@schemeID

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

   The following is the endpoint and a sample request body for creating an account and an associated e-invoicing profile.

   POST /v1/accounts

   {
       "additionalEmailAddresses": [
           "contact1@example.com",
           "contact2@example.com"
       ],
       "autoPay": false,
       "billCycleDay": 0,
       "billToContact": {
           "address1": "",
           "city": "",
           "country": "United Kingdom",
           "firstName": "John",
           "lastName": "Smith",
           "workEmail": "smith@example.com",
           "zipCode": "94404"
       },
       "creditMemoReasonCode": "Unsatisfactory service",
       "currency": "EUR",
       "hpmCreditCardPaymentMethodId": "2c92c0f93cf64d94013cfe2d20db61a7",
       "invoiceDeliveryPrefsEmail": true,
       "invoiceDeliveryPrefsPrint": false,
       "name": "Zuora Test Account",
       "notes": "This account is for demo purposes.",
       "paymentTerm": "Due Upon Receipt",
       "einvoiceProfile": {
          "enabled" : "true",
          "businessName" : "legal business name",
          "businessNumber" : "20002039",
          "businessNumberSchemeId" : "088",
          "taxRegisterNumber" : "TAX393999",
          "endpointId" : "08992",
          "endpointSchemeId" : "088"
       }
   }

   The following is the endpoint and a sample request body for creating an e-invoicing profile by updating an existing account.

   PUT /v1/accounts/<account-key>

   {
      "additionalEmailAddresses": [
          "contact3@example.com",
          "contact4@example.com"
      ],
      "paymentGateway": "Test Gateway",
      "einvoiceProfile": {
          "enabled" : "true",
          "businessName" : "legal business name",
          "businessNumber" : "20002039",
          "businessNumberSchemeId" : "088",
          "taxRegisterNumber" : "TAX393999",
          "endpointId" : "08992",
          "endpointSchemeId" : "088"
       }
   }

5. Create custom events and notifications for e-invoice file generations.

   This is an optional step that creates custom events and notifications for e-invoice file generations.

   The custom events will be triggered when e-invoice files are generated and ready for extraction, and Zuora will send callout notifications to your system. After the notifications are detected in your system, you can extract the e-invoice files from Zuora and distribute them to your business partners via the PEPPOL network.

   You can skip this step if the PEPPOL distribution in your system relies on a billing document querying approach against Zuora. For more information, see Extract the generated e-invoice files .

   The procedures for creating custom events and notifications for different billing documents (Invoice, Credit Memo, and Debit Memo) are similar. The following sections use Invoice as an example.

   1. Create a custom event for e-invoice file generations

      You can create the custom event in Zuora UI or through the REST API.

      To create the custom event in Zuora UI, see Create a custom event . Remember to enable Advanced (JEXL) and specify the following condition in the Set Conditions field:

      changeType == 'UPDATE' && Invoice.EInvoiceStatus == 'Generated' && Invoice.EInvoiceStatus_old != 'Generated'

      Alternatively, you can use the Create an event trigger API operation.

      The following is the endpoint and a sample request body.

      POST /events/event-triggers

      {
          "active": true,
          "baseObject": "Invoice",
          "condition": "changeType == 'UPDATE' && Invoice.EInvoiceStatus == 'Generated' && Invoice.EInvoiceStatus_old != 'Generated'",
          "description": "Trigger an event when an e-invoice file for invoice is generated.",
          "eventType": {
              "description": "An e-invoice file for invoice is generated.",
              "displayName": "E-Invoice File Generated",
              "name": "EInvoiceFileGenerated"
          }
      }

   2. Create a notification for e-invoice file generations

      You can create the associated notification in Zuora UI or through the REST API.

      To create the notification in Zuora UI, see Create a notification . Remember to select the custom event for e-invoice file generations from the Related Events list and specify the callout settings for your system, such as Base URL and Callout Authentication .

      Alternatively, you can use the Create a notification definition API operation.

      The following is the endpoint and a sample request body.

      POST /notifications/notification-definitions

      {
          "name": "E-Invoice file generated",
          "description": "An e-invoice file for invoice has been generated.",
          "eventTypeName": "EInvoiceFileGenerated",
          "eventTypeNamespace":"user.notification",
          "active": true,
          "calloutActive": true,
          "callout": {
              "active": true,
              "calloutBaseurl": "<the callout URL of your system>",
              "calloutRetry": true,
              "description": "Callout when an e-invoice file for invoice has been generated.",
              "eventTypeName": "EInvoiceFileGenerated",
              "httpMethod": "POST",
              "name": "Callout for E-Invoice file generated"
          }
      }