Skip to main content

Support Multi-entity in Zuora CPQ


Support Multi-entity in Zuora CPQ

To enable and support multiple entities in Zuora CPQ, you must have both Zuora Quotes 7.2 or later version and Zuora 360 3.2 or later version installed and configured as described in this article.

Currently, multi-entity and bundling cannot be enabled in the same Salesforce org.

This feature is in Limited Availability. If you want to have access to the feature, submit a request at Zuora Global Support

The following configurations were tested and certified between Zuora CPQ and Zuora in the Zuora Multi-entity environment:

  • Multiple Zuora entities synchronizing to one Salesforce org
  • One Zuora entity synchronizing to one Salesforce org 

If you are turning on Multi-entity in Zuora CPQ Q3 2016 release or earlier, make sure your tenant names are not longer than 38 characters, including special characters.

Set up Multi-entity in Zuora

When you add new entities or initially enable multiple entities in your Zuora tenant, perform the following tasks in each entity being enabled. The tasks listed are required for Zuora CPQ and is a subset of required tasks for Multi-entity in Zuora.

  1. In all your Zuora entities, enable the Multi-Entity setting.
  2. The Features setting must be the same in all entities. The setting should be either enabled for all of the Zuora entities or disabled for all of those Zuora entities.
  3. Set the prefixes in the Zuora settingsto be unique. The Subscription Number Prefix must be unique across all entities. We recommend the other prefix settings are set to be unique in all entities.
  4. In each entity, set the Zuora settings for Billing, Payment, Finance,Commerce, and Reporting.

Set up Multi-entity in Zuora CPQ

Follow the steps below to configure Zuora 360 to work with multiple Zuora entities:

  1. Install the Zuora Quotes, Version 7.2, and Zuora 360, Version 3.2, packages.
  2. Grant the permissions on the Billing Entity object in Zuora 360.
  3. Grant the field level permissions on the new entity id fields in Zuora 360.
  4. Update any page layout with the deprecated SKU field (zqu__SKU__c). Replace the SKU field (zqu__SKU__c) with the new SKU field (zqu__SKU2__c).
  5. For the custom fields defined in all your Zuora entities, create the corresponding fields in Salesforce with the same API name. 
  6. Enable the Multi-Entity setting in Zuora Quotes.
  7. Set the organization wide default values in Default Value Settings.
    The organization level default values are used as the default when making new entities.
  8. Run the 360 syncs from each new Zuora entity you want to connect to Zuora CPQ.
    1. Run the Product Catalog sync. The Product Catalog sync updates the Billing Entity information in Zuora Quotes with the information from Zuora.
    2. Run the Account and Related Objects sync.
  9. (Optional) Run a Salesforce report with the Entity Id field to verify that the accounts in each entity are synchronized correctly.
  10. In Zuora Quotes Connection Settings, test connections to all Zuora entities.
  11. Configure Zuora Config settings for each entity in Zuora Config Default Value Settings.
    • You must set the Subscription Name field to Auto-number for subscription names to be automatically generated in the Multi-entity setting.
  12. Migrate the previously synced data.
  13. Update WSDL to the version 76 in Zuora 360.
  14. If using Order Builder, update the settings in Connection Setup to use the Zuora WSDL version 76 in the Endpoint field. For example:
  15. Update your Order Builder code to add the Entity Ids in the zlogin method.
  16. Add the Billing Entity field to the Quote Template and Invoice Template page layouts.
  17. Open existing Quote Templates and set the Billing Entity field. 
  18. Add new Quote Templates for new entities.
  19. Open existing Invoice Templates and set the Billing Entity field. 
  20. Add new Invoice Templates for new entities.
  21. Open Communication Profile Settings in Zuora Config and click Refresh Profiles from Zuora.
  22. Open Payment Pages Settings in Zuora Config and click Refresh Payment Pages.

Grant the Object and Field Levels Permissions on the Billing Entity Object to Sync User Profile

To enable access to the new Billing Entity object added in this release, grant the Read, Create, Edit, and Delete permissions on the object to the sync user profile.

Additionally, grant the Read and Edit field level permissions on all fields in the new object to the same sync user profile.

To each sync user profile, grant permissions for the new Billing Entity custom object:

  1. Navigate to Setup > Manage Users > Profiles.
  2. Click the sync user profile to which you want to grant permissions.
  3. Click Object Settings.
  4. Click Billing Entities.
  5. On the Profile page, click Edit.
  6. In the Object Permissions section, select ReadCreateEdit, and Delete.
  7. In the Field Permission section, select Read and Edit for all the fields.
  8. Click Save.

Grant the Field Level Permissions on the New Entity Id Fields to Sync User Profile

Grant the Read and Edit permissions to the sync user profile on the following new fields. 

The Entity Id field was added to the following objects.

Object New Field
Billing Account Entity ID
Communication Profile Billing Entity
Hosted Page Setting Billing Entity
Invoice Template Billing Entity
Payment Gateway Entity ID
Payment Method Entity ID
Payment Pages Setting Billing Entity
Payment Term Entity ID

Billing Entity

Entity ID

SKU (zqu__SKU2__c)

Product Rate Plan Entity ID
Product Rate Plan Charge Entity ID
Product Rate Plan Charge Tier Entity ID

Unit of Measure


Entity ID

Unit of Measure


Billing Entity
Feature Billing Entity


To each sync user profile, grant permissions for all newly added fields:

  1. Navigate to Setup > Manage Users > Profiles.
  2. Select the sync user profile to which you want to grant the field-level permissions.
  3. Click Object Settings.
  4. Click the object listed in the above table.
  5. Click Edit.
  6. In  the Field Permissions section, select the Read and Edit permissions for each new field.
  7. Click Save.
  8. Repeat the Steps 4 to 7 for each object listed in the above table.

Migrate Previously Synced Data

If you are upgrading from a single entity environment, a full sync is necessary to populate the entity on existing records. By default, previously synchronized Product and Account records are not migrated.

Take the following steps to trigger a full sync in the next 360 Sync. You need to get the entity id of the previously existing entity from your Zuora tenant.

  1. Navigate to Setup > Develop > Custom Settings and click Manage next to MigrationSettings.
  2. Click MultiEntity_BillingAccount_<your entity id>.
  3. Click Edit.
  4. Clear the Migrated field.
  5. Click Save.
  6. Click MultiEntity_Product_<your entity id>, and repeat the steps 3 through 5.

Run a Report to Verify Accounts Synced for Entity

Optionally, you can run a report in Salesforce to verify that the accounts in each entity are synchronized correctly.

To create and run a report on Billing Accounts:

  1. In the Reports tab, click New Report....
  2. Expand the Accounts & Contacts folder, and click Accounts with Billing Accounts.
  3. Click Create.
  4. In the Billing Account: Info folder, drag Entity ID and drop it in the Preview area.
  5. Click Run Report.
  6. Verify that the Billing Accounts belong to the correct Entity IDs.

Enable the Multi-Entity Setting 

To support multiple billing entities, the Enable Multi-Entity setting must be turned on in Zuora Quotes. The setting is automatically enabled at 0:00AM on the following day after the corresponding Zuora setting is enabled in your Zuora tenant. 

If you want to immediately update the Enable Multi-Entity setting before the next schedule permission check happens, you can manually run the permission check.

Before you manually run the permission check script, make sure:

  1. The API user has access permission to all the entities.
  2. The Test Connections are successful. See Test Zuora Config Connection Settings for details.
  3. In each entity, you are using the right Salesforce credentials under 360 Sync in the right Salesforce org.
  4. A Product Catalog Sync is run successfully.

To execute the permission check script:

  1. In Salesforce, open Developer Console.
  2. Navigate to Debug > Open Execute Anonymous Window.
  3. In the Enter Apex Code window, type:
  4. Click Execute.
  5. In Zuora Quotes, verify that the Enable Multi-Entity setting is correctly updated in Advanced Quoting Configuration Settings in the Zuora Config tab.

Test Zuora Config Connection Settings

To update the Zuora WSDL version and check connections to Zuora entities:

  1. In the Zuora Config tab, click Zuora Connection Settings.
  2. Click Edit Settings.
  3. Click Test Connection. Check the connection status to all your Zuora entities.
    The entity information is synchronized from each Zuora entity in the Product Catalog sync. Test Connection only tests the connections to the entities that have been synchronized by the Product Catalog sync.

Add Billing Entity to Quote Template and Invoice Template Page Layouts

To add the Billing Entity field to the Quote Template page layout:

  1. Navigate to Setup > Create > Objects.
  2. Click Quote Template.
  3. In the Page Layouts section, click Edit for Quote Template Layout - V5.0.
  4. Click Fields.
  5. Drag and drop Billing Entity to the Quote Template Detail section.
  6. Click Save.

To add the Billing Entity field to the Invoice Template page layout:

  1. Navigate to Setup > Create > Objects.
  2. Click Invoice Template.
  3. In the Page Layouts section, click Edit for Invoice Template Layout.
  4. Click Fields.
  5. Drag and drop Billing Entity to the Invoice Template Detail section.
  6. Click Save.