Skip to main content

Troubleshoot Zuora CPQ


Troubleshoot Zuora CPQ

This topic provides troubleshooting information and the error message reference for Zuora CPQ.

Troubleshooting FAQ

Can I use the Discount Charge Model in Zuora CPQ?

Yes, this is supported in Zuora Quotes 5.x.

Are evergreen subscriptions supported in Zuora CPQ?

Yes, Evergreen subscriptions are supported in Zuora Quotes starting with version 4.2. Note that only new subscriptions can be created with the Evergreen option (amendments cannot be used to change Termed Subscriptions to Evergreen or vice versa). In addition, Evergreen subscriptions cannot be renewed.

Why is the product catalog not synced correctly when I change the charge model?

Changing the charge model in the product catalog is not currently supported, and can result in undefined behavior when synced to Salesforce.

How are subscription names generated? Are there any limitations?

Zuora Quotes uses the name of the Opportunity to create the Subscription. Because Subscription Names must be unique, this enforces a restriction of one Quote per Opportunity. Additionally, when creating Amendments or Renewals, Zuora Quotes further restricts this length to 50 characters or less. As a best practice, when creating an Opportunity enter a name of 50 characters or fewer. Longer names will result in an error when creating Amendments or Renewals.

Can I import the Zuora WSDL into Salesforce?

Yes, you can import Zuora WSDL to use it in Order Builder or Invoice PDF.

When you import the Zuora WSDL for the Order Builder, the Order Builder parses the WSDL and generates the objects and fields necessary for you to call the Zuora API.  

See the Order Builder documentation for more information.

How can I call Zuora APIs from Apex/Salesforce?

The Order Builder can be used to call Zuora APIs. See the Order Builder documentation for more information.

Why do some of my users not see organization information on the Quote PDF?

All users who use the Quote PDF functionality must have the View Setup and Configuration and the View All Data permissions in their Salesforce org.

Why can't I create an amendment in Zuora CPQ?

Amendments are available on Zuora Quotes version 3.0 and higher. If the option for modifying an existing subscription is grayed out and you cannot create an amendment in Zuora CPQ, check the following possible solutions:

  • The Enable Amendments option must be selected in the Quote Configuration Settings.
  • The subscription to be amended must be Active in Zuora.
  • Evergreen subscriptions cannot be amended in Zuora CPQ. They can be amended in Zuora.

Why is the subscription I created in Zuora CPQ not active?

When Zuora is set to use Service Activation Date and/or Customer Acceptance Date but Zuora CPQ is not, a subscription sent from Salesforce Zuora will leave these fields blank and in a status of Pending Active. Once the subscription is sent to Zuora, you must set the Service Activation Date and/or Customer Acceptance Date before the subscription is considered Active. Zuora recommends that you set up both systems with the same settings.

Do test class failures in the Zuora CPQ managed packages affect the required code coverage calculation for my Apex development?

Some of the test classes developed in the Zuora CPQ managed packages might fail in your Salesforce org because you might have data in your Salesforce org that cause the test case failures.

However, managed package code is not included in the required code coverage calculation in Salesforce. Therefore these test class failures in Zuora CPQ managed packages do not interfere with your Apex development .

General error messages

The following error messages and solutions apply to both Zuora Quotes and Zuora 360. 

Install Failed: Organization administration locked

Another Salesforce process, an installation or maintenance process, is running at the same time as the Zuora CPQ installation process. However, the Zuora CPQ package installation will continue as a background process. Do not reinstall Zuora CPQ.

In Salesforce, navigate to user name > Setup > View Installed Packages. The list shows whether a Zuora CPQ package installation is in progress.

Log out of Salesforce and then log in again. If Salesforce is currently performing software maintenance, it will display a notification with additional information.

Package install error

If you have a custom object, you must create a RecordType for the custom object before installing the Zuora CPQ packages. 

Attempt to de-reference a null object

This type of error happens when an unsupported feature, such as Discount Charge model or Pre-payment, is used in Zuora, followed by a sync to Salesforce.

Zuora Quotes error messages

The following error messages and solutions apply to Zuora Quotes. 

The Account Name must be 255 characters or less. Please change and re-send to Zuora

Zuora Quotes does not support account names longer than 255 characters.

There are no amendments on this quote to send to Zuora

This error indicates that there are no changes to the underlying subscription and nothing to send to Zuora.

Unable to Send: This subscription no longer exists in Zuora

The subscription has been deleted from Zuora.

Add Unit quantity cannot be less than 1

Currently, units can only be incremented in amendments and must be greater than zero.

The Bill To Contact in Zuora does not match any contacts on this account in Salesforce

Contacts may have been deleted in Salesforce or Contacts may not have been created in Salesforce. Note that Contacts are not synced over; only Bill To and Sold To are synced as fields.

Unable to Send: The subscription in Zuora does not match the base subscription in this quote

This error occurs when an amendment quote in Salesforce already exists, and the subscription in Zuora has been modified. Because the amendment quote has already been created in Salesforce prior to the changes on the subscription in Zuora, it is still using the older version of the subscription in Zuora. When the Salesforce user sends the amendment quote to Zuora, the system can not locate the older version that it is trying to amend.

To resolve this error, cancel the amendment quote which generated the error and create a new amendment quote within the opportunity so that it picks up the latest version of the subscription in Zuora.

Amendment send to Zuora error

Error: (zObject:[arrayfields={}, fields={Code=MISSING_REQUIRED_VALUE, Message=quantity is required for type onetime, recurring and model PerUnit,Tiered,Volume.}, ztype=Error])

Amendment send to Zuora error, Send to amendmentids size: 2 returned size: 0

The version of Zuora Quotes you are using does not support Discount Charge models. Update to the latest version of Zuora Quotes to resolve this error.

Collection size 1,317 exceeds maximum size of 1,000

The version of Zuora Quotes that you are using generates this error if the account for which the quote is being created has more than 1,000 contacts. This occurs because the process contacts are displayed in a list, which has limit of 1000 values in The latest version of Zuora Quotes allows you to customize the New Quote button to use the lookup option instead of the list. After creating the customized New Quote button, you can replace the default New Quote button created by Zuora Quotes on the Opportunity detail page and use your customized button.

No PaymentMethods found in Zuora. Please create the payment method in Zuora first

This error occurs when submitting a quote to Zuora, even though the payment methods are already configured. This error is caused by Salesforce not being able to call out to Zuora properly.  

Run a connection test via the Connection Test, located in Zuora Connection Settings. If you receive a connection error, update your credentials and try again. If you receive a successful connection and still experience the Salesforce error, contact Zuora Global Support.

Submit a request at Zuora Global Support to enable this feature or service.

Error: Number is too large

When creating a quote, users are allowed to change the effective price of the charge. However, the change must be within the range of +/-999%. This is to ensure that users do not enter an overly large discount or overcharge the customers. If there is a need to change the effective price to more than +/-999% instead of adding one charge, you can create multiple charges to the subscription that you want to create or amend.

If you enter a price that causes the discount to be greater than 999% or less than -999%, entering another price that is within the range will not make resolve the error condition. You must change the discount to 0%, then enter the new price.

saveRenewalAmendments: Save renewal amendment failed

This error can occur when renewing an amendment in Zuora Quotes. The reason and workaround is the same as for the previous error ("Error: Number is too large"). 

Insufficient Privileges: You do not have the level of access necessary to perform the operation you requested.

This error can occur when you click the New Quote button. Check your user permissions. Zuora Quotes may have been installed for admins only. To resolve this issue, you must uninstall and re-install the managed package.

The subscription number is already in use, please enter another subscription number

Every subscription name must be unique in Zuora, which is based on your Zuora CPQ configuration. If your Zuora Quotes is configured to use the OpporQuote Name, you may be attempting to create duplicate Subscription Names in Zuora.

To verify your settings, go to the Default Value Settings page in your Salesforce account and check the Subscription Name configuration.

  • If Subscription Name is set to Opportunity Name, you must create a new opportunity with a different name, then create a new quote under this opportunity. Depending on your business model, you may consider amending the existing subscription rather than creating a brand new subscription.
  • If Subscription Name is set to Quote Name, you must change the name of the quote.

Missing Organization Feature

Salesforce returns the error message, "Missing Organization Feature: fieldname.RecordType" if you have a custom object without an associated RecordType. 

To fix this error, create the required RecordType in Salesforce. See the Salesforce help topic Creating Record Types for more information. 

Error when Creating a Subscription

The following error message appears when you click Send to Zuora, or Create Subscription in older versions:

resultzObject:[arrayfields={}, fields={Code=MISSING_REQUIRED VALUE, Message=SubscriptionData.SubscriptionRatePlan[0].ProductRatePlanId is invalid.}, ztype=Errpr]

Verify that the API URL connection setting and the user credentials are correct. See Configure Zuora 360 Connection Settings for the list of URLs.

Error when Saving a Quote

This error is triggered when attempting to save a quote:

3ZQRenewalMgr.saveRenewalAmendments: Save renewal amendment failed.:System.DmlException:Upsert failed. First exception on row 0; first error: NUMBER_OUTSIDE_VALID_RANGE, Discount: value outside of valid range on numeric field: -2000000: [zqu__Discount__c]:(zqu) External entry point

An unexpected error has occurred. Your solution provider has been notified. (zqu)

The maximum discount percentage you can apply is 1000%. If you change the effective price (list price) of the quote to a very large number, it will exceed the 1000% limit and return this error message.

Zuora 360 error messages

The following error messages and solutions apply to Zuora 360

Accounts and related objects Errors

INVALID_FIELD_FOR_INSERT_UPDATE:<object>: bad field names on insert/update call: <fields>

This error can occur if you are using the following:

  • Salesforce Professional Edition
  • Zuora 360/Order Builder
  • Any or all of the sync features

During a sync session, you may encounter an error like the following:

INVALID_FIELD_FOR_INSERT_UPDATE:Zuora__CustomerAccount__c: bad field names on insert/update call: Zuora__External_Id__c, Zuora__CreditBalance__c

The table and field names might be different. 

This error is caused by a limitation in Professional Edition about field-level security. To resolve this error, edit the page layout for the object that caused the error (in the example error message, the object is Zuora__CustomerAccount__c) and ensure that all fields available on the object are added to the page layout. This will make the fields accessible during the sync process and will stop the error from occurring.

$0 invoices are not syncing to Salesforce

This occurs if you are using an older version of Zuora 360 that syncs only invoices with a positive balance. To sync all invoices to Salesforce, upgrade to the latest version of Zuora 360

INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY:insufficient access rights on cross-reference id

An operation affects an object that is cross-referenced by the specified object, but the logged-in user does not have sufficient permissions on the cross-referenced object. For example, if the logged-in user attempts to modify an account record, that user might not have permission to approve, reject, or reassign a ProcessInstanceWorkitem that is submitted after that action.

The reason for failed sync accounts is that you have permissions set that does not allow the Zuora User ID to access them. Alternatively, there could be a trigger on the accounts, which prevents them from being accessed. Refer to documentation for setting Quote Custom Objects

ENTITY_IS_DELETED:entity is deleted

You cannot reference an object that has been deleted. That this status code only occurs in version 10.0 of the Salesforce API and later. Previous releases of the API use INVALID_ID_FIELD for this error.

A data object in Salesforce was deleted. If an object was deleted with an account in Salesforce, any links created as a result of the sync will break.

Submit a request at Zuora Global Support to enable this feature or service.

ERROR: Failed to create new billing account. Could not update CRM Account Id field. Please retry.

This occurs when you are attempting to change the CRM Account ID. This can be a result of merging accounts in Salesforce, which loses the mapping of the CRM ID.

To resolve this error, locate the ZuoraId and ExternalId on the Billing Account (you might need to edit the layout to expose the fields). If those fields are blank, populate both fields with the Zuora Customer Account ID. Return to Zuora to edit the CRM AccountId. Then run the Zuora 360 sync to ensure that the Customer Account is mapping correctly to the Salesforce Billing Account.

Product Catalog sync errors


The error is a result of associating a Zuora environment to two or more Salesforce environments. For this reason, the product objects in Zuora have already been synced to and have existing IDs. When the sync is started for the same objects in the Zuora environment, the validation logic looks for those IDs but fails because they are located on a different org instance.

The resolution is to perform Product Clean Up to remove all Zuora product data from Salesforce and allow for a fresh sync to a new org. 

Submit a request at Zuora Global Support to enable this feature or service.

INVALID_CROSS_REFERENCE_KEY:invalid cross-reference id

The specified value in the relationship field is not valid, or data is not of the expected type. The error likely occurred because changes were made on the Salesforce side that was not reflected in Zuora, thus resulting in an error with the Product Catalog sync.

The resolution is to perform Product Clean Up to remove all Zuora product data from Salesforce and allow for a fresh sync to a new Salesforce org. 

Submit a request at Zuora Global Support to enable this feature or service.

NUMBER_OUTSIDE_VALID_RANGE:List Price: value outside of valid range on numeric field: <value>

This error occurs if the ProductRatePlanCharge record has a 7-digit value for the Price. By design, a Zuora CPQ product rate plan charge's price can have up to 6 digits. Because of this error, this record cannot be synced to Salesforce.

Edit the Price value to be 6 digits or less to successfully sync to Salesforce.

General Zuora 360 Errors

Invalid login, password or token

Verify that the correct Salesforce credentials are entered in Synchronize Data under the Commerce Settings . This includes you user name, password, and security token.

The security token is changed every time a user resets their password.

Supported jQuery versions

The following table lists the deprecated and supported versions of jQuery in Zuora Quotes managed package versions.

Quotes version Supported jQuery version Deprecated jQuery version
10.7 and above jQuery-ui-1.13.1.js jQuery-ui-1.12.1.min.js
10.4 to 10.6.1 angular-animate.1.8.2.js angular-animate.1.3.15.js
9.32.2 to 10.3.1 datatables-1.10.23.min.js,
jQuery-3.5.1, and

jQuery-1.9.1, and

Troubleshoot jQuery deprecation issue

The following approaches do not support quotes versions less than 10.

Approach 1
  • Insert the respective static resource again in the Salesforce org (as its for local use only).
  • Downloaded jQuery 1.9.1 from here -
  • In accordance with your needs, the org is now free to use this resource anywhere it likes for custom implementations. 
  • Change the reference of <apex:includeScript value="{!$Resource.zqu__jquery_1_9_1}"/>, zqu__jquery_1_9_1 to the new file name for 1.9.1 which will be reuploaded in static resources.
  • Make sure that the references are changed in every place where it is used.
Approach 2
  • Use the default Zuora Quotes managed package static resource that has been upgraded to the latest secure versions.
  • With that Feb-2021 push, we upgraded jQuery 1.9.1 to 3.5.1, and more dependencies on the ImagesAndJavascriptZip static resource were added. Regardless of which version of jQuery is being used in the Visualforce Pages, the functional implementation should support it.

Replace <apex:includeScript value="{!$Resource.zqu__jquery_1_9_1}"/> With the following 

<apex:includeScript value="{!URLFOR($Resource.zqu__ImagesAndJavascriptZip, '/js/jquery-3.5.1.min-compressed.js')}" /> 

<apex:includeScript value="{!URLFOR($Resource.zqu__ImagesAndJavascriptZip, '/js/jquery-migrate-3.3.2.min-compressed.js')}" />