Skip to main content

Zuora Release 2021.12.R1


Zuora Release 2021.12.R1

Welcome to the release notes for Zuora Release 2021.12.R1. This article is a consolidated page of all release notes for the following Zuora products:

For the latest release notes of Zuora Revenue, see Zuora Revenue release notes.

We welcome and appreciate your feedback on this release notes article. Please use the Feedback button to let us know what you think about the new release notes. For more information about the recent changes to the Zuora release management process, see Attention: Changes To The Zuora Release Management Process in Zuora Community.

Release schedule

See this release notification for details.

Join Release Notifications in Zuora Community to receive timely notifications about Zuora Billing, Collect, and Central Platform.

Zuora Billing

here_black.png Zuora UI Enhancements

New navigation bar (Production only)

In an effort to drive consistency across all Zuora products and improve the user experience when interacting with the product user interface (UI), Zuora UI has been reviewed and restyled across multiple products. The enhancements around the Zuora UI will be continuously delivered in the next few months.

In this production release, the look and feel of the navigation bar on the left side of the UI are presented with new fonts, colors, and higher contrast. The previous functionality to expand or collapse all navigation items is removed. When you scroll on the navigation bar, the content displayed on the right side will stay the same instead of scrolling with the navigation bar. The currently clicked item on the navigation bar is also highlighted by a green dot in front of the navigation item and a green vertical bar in front of the navigation session.

Before After
old-nav-bar.png new-nav-bar.png

here_black.png Orders and Subscriptions

A new setting is now available for force deleting an account

A setting called "Enable force deletion for Account?" is now available in Billing Settings > Define Default Subscription and Order Settings. By changing this setting to Yes, the validation for account removal will be skipped for the account that is the subscription owner of a subscription while the invoice owner is a different account. Force deleting this account deletes all its subscriptions, but the relevant invoices will not be impacted.

See Define Default Subscription and Order Settings and Cancel and Delete Customer Accounts for more details.

UI enhancement to display cancel date and suspend date on the subscription details page

The subscription details page has been enhanced to support displaying the exact dates for subscription cancelation and subscription suspension. For a canceled subscription, you can now see the exact cancel date. For a suspended subscription, you can now see the exact suspend date.

Orders UI enhancement to support linking an order line item to a related subscription

The Orders UI has been enhanced to support linking an order line item to a related subscription. For example, hardware items can be linked to their respective software subscriptions. You can now specify the related subscription number through the Orders UI when creating an order line item or updating an order line item. A Subscription Link section has been added respectively to the Add Order Line Item, Edit Order Line Item, and Order Line Item details pages. Previously, you could only specify the related subscription number through the Orders API or Order Line Items API.

See Create an order line item and Create an order line item with a new subscription for more details.

New accounting codes are now available on the Order Line Item object for Zuora Billing - Revenue Integration

The following accounting codes are now available on the Order Line Item object for customers using Zuora Billing - Revenue Integration:

  • contractAssetAccountingCode
  • contractLiabilityAccountingCode
  • contractRecognizedRevenueAccountingCode
  • unbilledReceivablesAccountingCode
  • adjustmentLiabilityAccountingCode
  • adjustmentRevenueAccountingCode

You can access them through the Order Line Item data sourceOrders API, and Order Line Items API.

Limitation imposed on quantity for order line items

A limitation has been imposed on quantity for order line items. Negative values for the quantity field on order line items are not allowed. An error is returned if a negative value is set either through the Zuora API or UI.

See Order Line Items limitations.

here_black.png Usage and Rating

Ability to access the Processed Usage object through SOAP API calls

You can now query the Processed Usage object synchronously through SOAP API calls to retrieve information about billed usage records. This ability helps to retrieve the usage records that correspond to invoice items. This ability should enable a variety of use cases, including integration with an external invoice presentation system.

See Query processed usage for more information.

here_black.png Invoicing and Invoice Settlement

HTML Templates now available for invoices

The HTML Templates feature is generally available for invoices as of Zuora Release 2022.02.R2, and for credit and debit memos as of Zuora Release 2022.05.R1.

The HTML Templates feature provides key capabilities to design and customize HTML invoice templates using an online editor. All public objects and fields are available for presence on the template, including custom objects and custom fields. 

In the HTML invoice template, you can perform the following operations:

  • Configure tables with flexible data manipulation including grouping, filtering, and sorting on all available fields
  • Format date and numeric fields based on the default locale or a specified locale
  • Preview invoices in HTML template with the real invoice data within the online editor

See Configuring HTML invoice templates for more information.

Enhancement on tax code configuration to use multiple Connect Tax Engines

You can now set up a tax code to select multiple Connect Tax Engines based on a mapping formula. By associating the tax code to the product you sell in different markets, you can assign a specific Connect Tax Engine to handle tax calculation for a particular market without duplicating the product catalog. This enhancement helps you to sell across borders with efficiency and flexibility.

See the following articles for more information:

Direct Avalara Integration supports multi-threading

Direct Avalara Tax Integration now scales with multi-threading bill runs by calculating tax in multiple threads concurrently. This enhancement reduces bill run processing time and improves your operational efficiency.

See Multi-threading support for bill runs and payment runs for more information.

Scheduled bill runs with pause and resume

Zuora has added flexibility to billing operations by enabling the Pause and Resume on scheduled bill runs to help you efficiently manage bill runs with other complex tasks, such as production maintenance, tax engine deployment, updating billing document templates.

You can now pause one or more scheduled bill runs and resume them at a later time. You may also resume them with a one-time bill run to catch up on your billing immediately. This enhancement is available in Zuora UI and will be available through Zuora API in the near future too. 

See Manage scheduled bill runs for more information.

Billing preview run supports multiple batches through the Zuora API

You can now forecast the unbilled amount for multiple customer batches in a single billing preview run. Specify the batches field using the following API operations: 

  • REST API (zuora-version header set to 314.0 or later): 
    • Create a billing preview run
    • Retrieve a billing preview run
  • SOAP API (WSDL 113.0 or later)
    • BillingPreview() call 
    • BillingPreviewRun

Standalone invoices support negative invoice items in the Zuora UI

When you create or edit a standalone invoice through the Zuora UI, you can now enter a negative amount in the Price field on an invoice item. The subtotal of the invoice cannot be negative.

Note that standalone invoices are available only if you have the Unified Invoicing feature enabled.

Support for creating zero-amount memos from invoices

You can now create credit memos with zero total amount from invoices through both the Zuora UI and REST API. 

For example, by creating zero-amount credit memo items from an invoice, you can issue a zero total credit memo to correct the personal data in the invoice, such as the VAT number or company name.

Previously, zero-amount memo items were not supported, except for in the tax-only credit or debit memos where all the memo items had zero amount but taxation items had non-zero amount.

here_black.png Zuora CPQ

Zuora Quotes

The 2021.12.R1 enhancements of Zuora Quotes consist of the following parts:

CPQ X enhancements

The following enhancements are only applicable to CPQ X.

Default action dates configurability for amendment quotes 

For better configurability and usability of amendment quotes, we have changed the default behavior of the update product actions in amendment quotes in CPQ X. If an update is made on an original product, the update action is now triggered on the Quote Start Date by default. 

With this change, the following Quote Studio admin settings are now available:

  • Update Amendment Quotes as of Original/Subscription Term Start Date: Enabling this setting brings back the legacy behavior. The Contract Effective Date of the update action on an existing product will default to the original subscription start date.
  • View Amendment Quotes as of Quote Start Date: With this setting enabled, on an amendment quote, CPQ X will consider the quote to start from the Quote Start Date instead of the subscription term start date, thus will filter out original actions before that.
  • Prohibit Backdate Actions: With this setting enabled, the Contract Effective Date of update actions cannot be set to earlier than the Quote Start Date. 
    Note that if Update Amendment Quotes as of Original/Subscription Term Start Date is also enabled, you still can update original products as of the original trigger date.

You can optionally enable one or multiple of these settings based on your business requirements.

See Configure Quote Studio admin settings for more information.

Related contacts available for selection for Bill to Contact and Sold to Contact in Quote Studio

When you configure the Bill to Contact and Sold to Contact dropdown lists on the Quote Studio page, in addition to primary contacts, related contacts associated with the account are now also available for selection. 

Previously, only primary contacts could be selected for both dropdown lists.

Enhanced text area usability in Quote Studio

We have enhanced text areas in Quote Studio for better usability. Text areas that allow for rich text and long plain text are now displayed in a more intuitive way so that they can be easily distinguished from short plain text areas. A text formatting toolbar is also available in rich text areas.

Previously, all text areas were equally displayed as short plain text areas.

General enhancements 

The enhancements in this section are applicable to Zuora Quotes, or both Zuora Quotes and CPQ X.

Zuora Connection Settings page reorganization

We have reorganized the layout of the Zuora Connection Settings page for improved user experience. 

  • If you are an existing Zuora Quotes user, no update is required.
  • If you are new to Zuora Quotes, you need to specify the following fields to connect your Salesforce organization to your Zuora tenant:
    • SOAP API URL: Specify the SOAP API URL provided by Zuora, including the WSDL version that you want to use. The REST API URL field will be automatically populated based on the specified SOAP API URL.
    • API User Name: The user name provided by Zuora
    • API Password: The password provided by Zuora

See Zuora Connection Settings for more information.

JavaScript library updated

We have updated our existing JavaScript libraries to avoid potential security issues. If you have been using the JavaScript libraries provided in the Zuora Quotes package, you should update the reference to the new JavaScript libraries or manage your own libraries. 

Note that we do not provide any support to third-party libraries if you use your own JavaScript libraries.

up-arrow.png Back to Table of Contents

Zuora Collect

here_black.png Payments

New fields available in the Create a payment method REST API

The following new fields are now available in the request body of the Create a payment method operation:

  • creditCardMaskNumber
  • skipValidation

See API Reference: Billing for more information.

Enhancement on support for Indian recurring mandates

In accordance with the Reserve Bank of India’s (RBI) regulatory changes taking effect on December 31st, 2021 for network tokenization, the creation of Indian recurring mandates through one-time payment flows is enhanced by supporting Credit Card Reference Transaction payment methods on the Stripe v2 payment gateway integration. For now, this enhancement applies to customers who make transactions in Indian Rupees (INR) through the Stripe v2 gateway and want to store an end user's card on file. 

You can pass in fields required for the generation of a mandate through a one-time payment flow with Payment Pages 2.0, with or without the payment data. The generated mandate ID will be stored on the Credit Card Reference Transaction payment method.

With this enhancement, you can take advantage of the flow of adding or updating a payment method to create an Indian recurring mandate without being required to make a payment. You can also create an Indian recurring mandate, complete a payment, and store the details as a fully tokenized payment method.

See Implement Payment Pages 2.0 to support processing payments in India for more information.

Change of the option name in the type selection list when creating a Payment Page

For better clarity and consistency, when creating a Payment Page, the option name for the Payment Page that can work with the CyberSource Tokenization gateway is changed from Credit Card Reference to CyberSource Token

A new Credit Card Reference option is available in the list for creating a Credit Card Reference Payment Page working with the Stripe v2 gateway. This feature is in Controlled Release. If you want to use this feature, submit a request to Zuora Global Support.

See Configure Payment Pages 2.0 for more information.

Support for creating mandate information for CCRef payment methods through Zuora REST APIs

You can use the Create a payment method API operation to create and update mandate information, including mandate ID, mandate status, and mandate reason, for the Credit Card Reference Transaction (CCRef) payment methods.

The mandate information will be stored on the payment method in Zuora. To retrieve the mandate information, use any of the following methods:

New field available in the Create a payment run REST API

In the request body of the Create a payment run operation, a new nested field called accountNumber is now available in the data field. You can specify the number of a customer account with this field. Previously, only accountId was available for specifying the customer account identification.

IfaccountNumber is specified in the Create a payment run operation, this field will also be available in the response body of the Retrieve payment run data operation.

Increased passthrough parameter limit supported by Payment Pages 2.0

The passthrough parameters can be used to return the information that is not captured in your Payment Pages 2.0 form to the callback function or callback URL. The maximum number of the passthrough parameters has been increased from 5 to 15.

See Client parameters for Payment Pages 2.0 for more information.

up-arrow.png Back to Table of Contents

Zuora Central Platform

here_black.png Custom Objects

Maximum length limit for filterable text fields in custom object definitions

When you create or update a custom object definition through the Zuora UI or API, Zuora now validates the maximum length of filterable text fields. If the custom object definition has a filterable text field with maximum length greater than 512, the operation fails.

If you have already created a custom object definition that has a filterable text field with maximum length greater than 512, Zuora has ensured that you can continue to use the field.

here_black.png Events and Notifications

Amount fields in custom events based email notifications now rendered based on your currency customization 

Zuora now supports localizing amount fields in email notifications for custom events. 

For the following merge fields in custom event based email templates, the currencies are determined based on the currency related to your customer’s accounts, and the amounts are formatted based on the format configured for the corresponding currency in your Zuora tenant:

Object Field Merge field tag
  • TotalAmount
  • Balance
  • <Invoice.TotalAmount>
  • <Invoice.Balance>
Credit Memo
  • TotalAmount
  • <CreditMemo.TotalAmount>
Debit Memo
  • TotalAmount
  • Balance
  • <DebitMemo.TotalAmount>
  • <DebitMemo.Balance>
  • Amount
  • <Payment.Amount>
  • Amount
  • <Refund.Amount>
  • CMRR
  • TCV
  • <Subscription.CMRR>
  • <Subscription.TCV>

Date fields in custom events based notifications now returned by communication profile localization

Zuora now supports localizing date fields in notifications for custom events. Localization is determined by base object for the custom events. See Custom events for the available base objects.

More data sources available in email templates for standard events

To extend the merge field availability for email templates, Zuora now provides the following data sources in the email templates for standard events. You can use the fields of these data sources as merge fields in the corresponding email templates:

Standard event category New available data source
  • Account
  • Bill to 
  • Bill to invoice owner
  • Default payment method
  • Payment
  • Payment method snapshot
  • Parent account
  • Sold to
  • Sold to invoice owner
  • Subscription
Payment Method
  • Account
  • Bill to
  • Bill to invoice owner
  • Default payment method
  • Payment
  • Payment method snapshot
  • Parent account
  • Sold to
  • Sold to invoice owner
  • Subscription
Payment Method Expiration
  • Account
  • Bill to
  • Bill to invoice owner
  • Default payment method
  • Payment
  • Payment method snapshot
  • Parent account
  • Sold to
  • Sold to invoice owner
  • Subscription
  • Account
  • Bill to
  • Bill to invoice owner
  • Default payment method
  • Parent account
  • Sold to
  • Sold to invoice owner
  • Subscription
Upcoming Renewal
  • Account
  • Bill to
  • Bill to invoice owner
  • Default payment method
  • Parent account
  • Sold to
  • Sold to invoice owner
  • Subscription

Support for returning empty strings as null in custom event triggered callouts

Zuora now provides the flexibility for you to configure whether empty values are transformed to "null" or kept empty in the response of callouts triggered by custom events.

The For custom events triggered callouts, return empty string as "null" setting is now available on the Callout Settings page. With this setting enabled, all empty strings in callouts triggered by custom events are returned as "null".

Note that Zuora recommends that you set returned empty strings as "null" for consistency with standard callout notifications.

See Configure callout notifications for more information.

Client Credentials grant type for OAuth 2.0 now supports scopes

When you create OAuth 2.0 providers in Zuora, the Scope field allows you to limit Zuora’s access to the accounts of your customers. The scope information will be presented to your customers in the consent screen, and the access token issued to Zuora will be limited to the scopes granted.

Zuora now supports setting scopes for the Client Credentials grant type when you create an OAuth 2.0 provider. Previously, scopes were not supported for this grant type. 

Support for Advanced SMTP Server

Zuora now provides Advanced SMTP Server as a new SMTP server configuration option for sending email notifications. The advanced SMTP server is powered by Amazon's Simple Email Service (SES).

When configuring an advanced SMTP server, you will go through a verification process. After the verification completes, Zuora will use the Amazon SES as your outbound email server and leverage DomainKeys Identified Mail (DKIM) capabilities of Amazon SES to secure your emails. It allows you to comply with Domain-based Message Authentication, Reporting and Conformance (DMARC).

See Configure an SMTP server for email notifications for more information.

Resend notifications API operations now available

For various reasons such as network failures and authentication errors, your customers cannot receive your email or callout notifications sometimes. Zuora now provides the following API operations, which allows you to resend email or callout notifications if your customers could not receive notifications on the first try:

Support for querying email notification histories by account ID through API

Zuora now allows you to query email notification histories by account ID through the “List email notification histories” API operation. You can use the accountId field as a query parameter of this operation, and it will also be returned in the 200 response.

See List email notification histories for more information.

here_black.png Tenant Management

Support for removing unused picklist values for custom fields through the Zuora UI

Zuora now allows you to remove picklist values for custom fields through the Zuora UI if all of the following conditions are met:

  • The picklist values are not used anywhere in your application.
  • The picklist values are not default values of the custom fields.
  • These custom fields are not shared with other entities if you have the Multi-entity feature enabled.

Previously, you could not remove any picklist values for custom fields.

See Manage custom fields for more information.

Support for disabling picklist values for custom fields through Zuora UI

Zuora now allows you to disable picklist values for custom fields through the Zuora UI if the picklist values meet both conditions:

  • They are saved in the system.
  • They are not default values of the custom fields.

If Multiple-entity is enabled for your tenant, you can disable picklist values of shared custom fields in the parent entity, and your update will be synchronized to all child entities.

After picklist values are disabled, you cannot use them to create or update objects through the Zuora UI.

See Manage custom fields for more information.

here_black.png Workflow

Support for Workflow Access Permission

Workflow Access Permission is now available in both Sandbox and Production (UI only). This feature enables you to manage users’ access to Workflow with four different access permissions: Workflow View access, Workflow Run Access, Workflow Manage Access, and Workflow Manage Global Settings Access.

It helps your organization to better meet compliance rules that require restrictions on Workflow access.

See Manage access permissions for Workflow for more information.

Enhancements to the HMAC authentication method in the Callout task

Zuora enhanced support for the HMAC authentication method in the Notifications: Callout task. Now you can both add basic authentication information and enable dynamic secret settings in HMAC authentication.

See Settings for HMAC authentication for more information.

New Merge task available

The Logic: Merge task is in the Early Adopter phase. It is only available for a selected group of customers for now.

Zuora provides a new Logic: Merge task to support merging two or more branches into a single subsequent branch based on the completion of all pre-merge branches. This task simplifies configuring branched processes that complete before a workflow completes.

here_black.png Central Sandbox

Improved tenant data refresh mode

Now, the system automatically determines the more effective method between Production snapshot and Instant refresh by analyzing tenant data. Therefore, you will receive more up-to-date data with a shorter turnaround time for your refresh.

up-arrow.png Back to Table of Contents


See API Changelog for a summary of REST API updates and documentation updates in the Zuora API Reference. 

up-arrow.png Back to Table of Contents


Current WSDL version: 113

See Zuora WSDL for information on how to check your version and download the latest version.

SOAP API change history

See Zuora SOAP API Version History for a summary of updates made to the SOAP API in recent Zuora releases.

up-arrow.png Back to Table of Contents