Skip to main content

Zuora Release 2022.12.R1


Zuora Release 2022.12.R1

Welcome to the release notes for Zuora Release 2022.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.

Release schedule

For release schedule details, see this release notification.

For the planned schedule of upcoming Zuora releases, see Zuora Release Management in Zuora Community.

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

UI enhancements

here_black.png Object ID supported by Global Search

From this release, you can use Global Search to search for the supported object by their ID, which is the unique identifier assigned by Zuora. The ID of the following objects is currently supported:

  • Customer Account 
  • Credit Memo
  • Debit Memo
  • Invoice
  • Order
  • Payment
  • Product
  • Product Rate Plan
  • Product Rate Plan Charge
  • Subscription

here_black.png UI Builder for configurable reinvented list views

As a continuous effort to improve the whole Zuora UI experience, we are pleased to announce the release of a new tool called UI Builder, which enables configurability of pages in our UI, on all reinvented list views. Administrators will now be able to add, remove, and reorder columns that are displayed on each list view to best suit your business needs. This tool is available only when the New Zuora Experience setting is enabled in the user profile.

UI Builder is still in the Beta phase and will not be deployed to Production environments until further notice. We are actively soliciting feedback and keep making improvements before we make it generally available. Please use this form to submit feedback on this tool.

Zuora Billing

here_black.png Orders and Subscriptions

Fulfillment and Return feature generally available

The Fulfillment and Return feature is now generally available to all customers with the Orders or Orders Harmonization feature enabled. You can now manage the entire lifecycle for your non-subscription based business through the Order Line Items feature.

Enhancements to Change Plan subscription amendment and Change Plan order action

You can retrieve information about the Change Plan subscription amendment and Change Plan order action directly from the following objects:

  • The Order Action object in the Order Action Data Source, Reporting, or Data Query, with the Type field specified as ChangePlan
  • The Subscription Version Amendment object in the Subscription Data Source, Reporting, or Data Query, with the Type field specified as ChangePlan

When creating a product rate plan from the UI, you can specify the Grade field for the product rate plan. You can also retrieve information about the Product Rate Plan object with the Grade field specified. For information about the Grade field, see CRUD: Create a product rate plan

Further, you can identify the subscriptions that are updated through the Change Plan subscription amendment or the Change Plan order action from the following places in the UI:

  • The Action column of the subscription row in the expanded order on the Orders page
  • The Action column in the Associated Subscriptions section of the Order Actions tab on the order details page
  • The Action or Amendment Type column in the Subscription Change History section on the subscription details page
  • The Type column of amendments on the Amendments page

The change plan type of order action and subscription amendment is currently not supported for Billing - Revenue Integration. When Billing - Revenue Integration is enabled, the change plan type of order action and subscription amendment will no longer be applicable in Zuora Billing.

For more information, see Create a product rate plan and Rate Plan Data Source.

Support for automatic refunding after subscription cancellations

When using the Create an order API operation to cancel subscriptions, you now have the option to automatically refund the unconsumed part of payments to the customer accounts and write off any outstanding balances on the invoices. Previously, refund and invoice write-offs could only be done manually after the subscriptions were canceled.

With this enhancement, the refundable part will be unapplied from the payments and then refunded to the customer accounts. Meanwhile, credit memos will be created and applied to the corresponding invoices to write off the outstanding balances at the invoice level.

Note the following behaviors and limitations when you use the auto refund enhancement:

  • The API request will not return errors if some of the refunds or invoice write-offs fail. But details of each transaction will be returned in the response body.
  • In scenarios where multiple payments need to be refunded, Zuora will refund the payments one by one, instead of refunding the same amount to each of the payments evenly.
  • Only electronic payments can be refunded automatically. External payments are not supported for now.

For more information, see Cancel a subscription and refund the end customers automatically.

Required permissions to edit subscriptions

Now, you can edit subscriptions from the reinvented UI with both of the following permissions:

  • Platform role: UI Access
  • Billing role: Manage Subscriptions/Amendments

For more information, see Platform roles and Billing Roles.

Rollover fields available in Orders UI

In the Orders UI, you can now select the Rollover field and view the Rollover Period and Rollover Application Option fields for the Prepaid with Drawdown feature.

Enhancements to reinvented subscription details page

The following enhancements are now available to the reinvented subscription details page:

  • Moved the Subscription Change History section right before the Included Products section
  • Supported for displaying a section in the previously expanded and collapsed state
  • Supported for searching removed products in the Included Products section

For more information, see View details of subscriptions through the reinvented UI.

here_black.png Invoicing and Tax

Specific Months available as list price base option for early adopters

With the Annual List Price feature, you can now sell your products and services based on a term price by using the Specific Months list price base, and bill your customers with a variety of billing periods, such as monthly, quarterly, every four months, semi-annually, or annually. 

For example, if a subscription term is seven months, you can configure the charge with the price as $5,000 per seven months, and the billing period as quarterly. You can configure the billing period as quarterly to bill the subscription charge to generate three invoices, and the total billed amount of the charge across the three invoices sums to the price of $5,000.

For a summary of the latest REST API updates specific to this feature, see the "API updates for the Annual List Price feature" section in 2022 API Changelog (2022-12-09) and API Reference

Support for staggered start dates in Billing Schedule

With the Billing Schedule feature, you can now bill charges with staggered start dates according to the following algorithm:

  • Charges are grouped per term. The term start date is determined by the minimum value of start dates, and the term end date is determined by the maximum value of end dates within the charges with the term start date. All charges that fall into the term start date and term end date belong to the same group.
  • Groups are consumed in sequential order. The next group will not be consumed until all charges in the previous group are fully consumed.
  • Charges in the same group are billed proportionally based on the charge total price.

For details about a specific use case, see Group and bill charges with staggered start dates.

Support for mixed use of standard and custom billing schedules through Zuora UI

With the Billing Schedule feature, you can now specify which subscriptions are included in an invoice schedule when creating an invoice schedule from an order in the Zuora UI. Therefore, you do not have to include all subscriptions of an order in the invoice schedule. 

For an order containing multiple subscriptions, you can bill some subscriptions with a custom billing schedule by creating an invoice schedule, and bill the other subscriptions with standard billing periods. 

For details about a specific use case, see Use custom and standard billing schedules for multiyear contracts.

Support for specifying names for invoice schedule items through REST API

With the Billing Schedule feature, you can now specify a name for each invoice schedule item when creating an invoice schedule through the REST API. The name of an invoice schedule item can contain up to 100 characters.

Additionally, you can update the name of an invoice schedule item when the item is in Pending status.

Support for specifying invoice templates and sequence sets at subscription level through Zuora UI

With the Flexible Billing feature, you can now specify such billing attributes as invoice templates and sequence sets at the subscription level when creating subscriptions through the Order UI: 

  • Invoice Template: Specify the invoice template associated with the subscription. 
  • Sequence Set: Specify the sequence set associated with the subscription.

Previously, you can only specify these billing attributes by using the Orders operations through the REST API.

Deprecation of Bill Run Notification: Posted email notification setting

In late December 2022, we will deprecate the non-configurable "Bill Run Notification: Posted" email notification setting from production tenants. This change will take effect in sandbox tenants starting on 6 December 2022. After this change, the notification emails will not be sent to the user accounts that are used to create bill runs. 

The alternative solution to receive "Bill Run Notification: Posted" notifications is to use custom events. For more information about how to configure Bill Run Posted custom events, see the "Bill Run Posted" section in Custom events.

Additionally, you can use the following standard events for Bill Run Completion to trigger email notifications:

  • Completed Status
  • Error Status

Support for creating taxation items for invoices via REST API

You can now create taxation items for invoices through Create taxation items for Invoices. With this REST API, you can create multiple tax items for an invoice with one API call.

For more information, see Create taxation items for invoices through API.

here_black.png Usage and Rating

Rollover available for Prepaid with Drawdown

You can now transfer the accumulative carryover of your customers’ prepaid balance funds to the following billing period when using Prepaid with Drawdown to create prepayment charge.

up-arrow.png Back to Table of Contents

Zuora Collect

here_black.png Payments

Additional error information available in response of Create authorization API

For the Create authorization API operation, you can now submit a request at Zuora Global Support to enable the support for returning additional error information. With this support enabled, when the request fails, the following gateway response information is available in the API response for your further analysis:

  • Gateway type
  • Gateway version
  • HTTP response code
  • Error message returned from the gateway
  • Additional response information from gateways, such as processor name, processor result code, and message

Actionable insights for payment failure events available in Payment Lifecycle

We have improved the Payment Lifecycle section on the reinvented payment detail page to provide actionable recommendations for failed events. Click the failed event in the timeline pane, and then the recommendation is displayed at the top of the right pane.

For more information, see Review and edit payments.

up-arrow.png Back to Table of Contents

Zuora Central Platform

here_black.png SDK

Official Zuora Node client library now available

The official Zuora Node client library (also known as SDK) is now available. The Node SDK is built on the Quickstart API. To use the Node SDK, you must have the following features enabled on your tenant:

  • Orders or Order Harmonization
  • Invoice Settlement

You can find the Node SDK distribution on npm. To learn how to install and use the Node SDK, see the following developer docs:

here_black.png Workflow

Liquid Auto Complete

You can now use Liquid Auto-Complete. You can use the type-ahead functionality during your task development experience as well as while using the Liquid Tester. The autocomplete feature allows you to type in Liquid tags as you normally would, and the system will automatically use the drop-down menu of options to either scroll through and click the tag of your choice or highlight and press the tab key. Furthermore, if you are using Liquid functions, you can type the vertical bar | and see a menu of functions, with hints and outputs visible when hovering.

For more information, see Use Liquid expressions in Workflow.

Global constants bulk import

You can now bulk import and export Global Constants via CSV from the Workflow General Settings tab. You can now select one, many, or all global constants and then export them as a CSV file downloaded to their local workstation.
You can import Global Constants by uploading a CSV file with the headers [key, value] and providing a mass entry. You will also be guided to improve any existing keys with Skip, Skip All, Replace, and Replace All options. These options are only displayed when a new upload contains previously uploaded keys with different values.
In-line edits to global constants are now auto-saved.

Collapsable task library

The task library can now be collapsed with a collapse icon (clipboard_e11c3173d52382c34fb5fc11d605cc352.png) or a keyboard short [.

here_black.png Data Query

Resolved: Failures in exporting data from the OrderAction table through Data Query

Previously, queries failed when you exported data from the OrderAction table through Data Query. 

This issue is now resolved. For example, you can export the order action data of a specific Order object with the following query:

SELECT * FROM OrderAction WHERE OrderId = '8ad098ea80042b630180165e0d193d31'

here_black.png Events and Notifications

Support for displaying request payloads of callout notification histories in the Zuora UI

You can now view request payloads of callout notification histories in the Zuora UI.

To view request payloads, perform the following steps:

  1. Open the Settings page by clicking your avatar and then one of the following options:
    • Administration
    • Billing
    • Finance
    • Payments
  2. Click Setup Profiles, Notifications and Email Templates.
  3. Click the Callout History tab.
  4. To the right of a request URL, click the Info icon info.png. The Request Payload window opens.

Support for exporting notification definitions and email templates through Data Query

From this release, the following tables are available in Data Query:

  • notificationdefinition: the notification definitions in your Zuora tenant
  • notificationemailtemplate: the email templates in your Zuora tenant

You can export notification definitions and email templates through Data Query with these tables.

For example, you can use the following query to export all notification definitions in your default communication profile:

SELECT * FROM notificationdefinition WHERE ProfileName = 'Default'

Email and callout notifications available for the HPM Threat Detection System Health dashboard

HPM Card Attack and HPM Page Attack standard events are now available for the HPM Threat Detection System Health dashboard.

You can customize the evaluation frequency of the event by configuring the Interval event parameter.

For example, you can define notifications as follows:

  • If a card attack happened in the last five minutes, an email notification is sent.
  • If an attack on hosted payment pages happened in the last ten minutes, a callout notification is sent.

Note that this feature is available only if you have Zuora System Health enabled.

up-arrow.png Back to Table of Contents


Zuora REST API provides comprehensive support for common business use cases. 

API for Billing, Collect, and Platform

For the detailed API documentation, see API Reference.

For a summary of REST API updates and documentation updates in the Zuora API Reference, see 2022 API Changelog

Quickstart API

From 2022.09.R1, the Quickstart API is available to you if you have the Orders (or Order Harmonization) and Invoice Settlement features enabled in your tenant. The QuickstartAPI allows new integrators to swiftly integrate with Zuora, and it supports essential business use cases.

For the detailed Quickstart API documentation, see Quickstart API Reference.

For a summary of REST API updates and documentation updates in the Quickstart API Reference, see Quickstart API Changelog


Current WSDL version: 128

For information about how to check your version and download the latest version. see Zuora WSDL.

SOAP API change history

For a summary of updates made to the SOAP API in recent Zuora releases, see Zuora SOAP API Version History.