Skip to main content

Zuora Release 2023.06.R2


Zuora Release 2023.06.R2

Welcome to the release notes for Zuora Release 2023.06.R2. This article is a consolidated page of release notes for the following Zuora products:

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

Release schedule

To track the progress of this release, see this release notification.

To receive notifications about releases, join Release Notifications in Zuora Community. For the planned release schedule, see Zuora Release Management.

Zuora Billing

here_black.png Product Catalog

Natural key support for product catalog objects

We now support natural keys for products, product rate plans, and product rate plan charges in Zuora APIs. These natural keys, also referred to as unique IDs, are derived from these objects' inherent attributes or properties. They are created based on the values that uniquely identify each record in the product catalog.

The following natural keys are newly added fields for the objects and do not replace any existing ID fields:

  • productNumber for products
  • productRatePlanNumber for product rate plans
  • productRatePlanChargeNumber for product rate plan charges

By default, the natural keys are sequential incremental numbers with an alphabetical prefix. For example, PC-00000001 or PRPC-00000001. You can also customize the naming convention for the natural keys to suit your needs. These natural keys can be used as environment-specific identifiers for products, product rate plans, and product rate plan charges.

For more information, see the "API updates for natural key support of product catalog objects" section in 2023 API Changelog (June 26, 2023) and REST API Reference.

here_black.png Invoicing and Tax

New REST API operations for managing contacts

The following new REST API operations for contacts are now available:

  • Create a contact
  • Retrieve a contact
  • Update a contact
  • Delete a contact

Billing Schedule supports pausing and resuming invoice schedules through Zuora UI

With the Billing Schedule feature, you can now perform the following operations on the invoice schedule details page through the Zuora UI:

  • Pause an invoice schedule
    You can click Pause in the upper right to prevent Zuora Scheduler from automatically picking up an invoice schedule.
  • Resume an invoice schedule
    When you want to execute a paused invoice schedule, you can click Resume to resume the invoice schedule, and Zuora Scheduler will continue picking it up automatically as before.

The corresponding REST API support has been available since the 2023.05.R1 release.

Billing Schedule supports configuring whether to consolidate billing documents through Zuora UI

When creating or updating an invoice schedule through the Zuora UI, you can now control whether to generate a consolidated billing document for unbilled charges under an account. To do this, select an option from the Consolidate Billing Documents list in the Additional Information section. 

The corresponding REST API support has been available since the 2023.05.R1 release.

Billing Schedule supports configuring next run dates for invoice schedule items through Zuora UI

When editing an invoice schedule through the Zuora UI, you can now specify a value for the Next Run Date field in the Additional Information section to determine the next processing date of the invoice schedule. 

With this enhancement, you can control when Zuora Scheduler needs to generate a credit memo or an invoice in the next schedule. For example, you can accelerate the credit memo generation for previous contracts if you want to bill early for the new contract. 

The corresponding REST API support has been available since the 2023.05.R1 release.

Billing Schedule supports specifying blank run dates for invoice schedules through REST API

When creating invoice schedules through the REST API, you can now specify blank dates for the scheduleItems > runDate field in the request. Blank dates are useful if you do not have specific milestones or project dates, especially in the early stages of a project.

When specifying run dates for invoice schedule items, consider that:

  • An invoice schedule item with a blank run date will not be executed.
  • You can only update the run date for an invoice schedule item in Pending status.
  • If the run date of an invoice schedule item is left empty, the dates of all subsequent invoice schedule items must also be blank.
  • You must specify run dates in chronological order for invoice schedule items.

Reinvented bill run details page available in Sandbox environments

You can now visit the reinvented bill run details page in all Sandbox environments.

The redesigned bill run details page has a modern look and feel, along with several enhancements. The key features are:

  • The page is organized into tabs for improved navigation and ease of use.
  • Rebilling failed accounts becomes simpler and more efficient.
  • Summary section: This section provides a clear overview of the results, making it easy to find critical information.
  • Associated Bill Runs section: All instances of executed bill runs for a scheduled bill run are consolidated on a central page. You can easily track processed accounts and billing documents.
  • History section: A comprehensive bill run history is included, which shows the timeline of user operations and bill run status changes.

The existing bill run details page is still enabled by default. To access the reinvented page, click the "Go to the new bill run page" link at the top of the existing bill run details page. If you want to switch back, click the more options icon, and then click Back to the Original Bill Run View.

Annual List Price feature generally available

The Annual List Price feature is now generally available for all customers.

This feature introduces two new list price bases: Year and Specific Months. To enable the list price bases in your product catalog, select the Year and Specific Months check boxes in the Customize List Price Base section through the Zuora UI. For more information about this feature, see Annual List Price.

The Annual List Price feature has been enabled for all customers in Sandbox environments by default. If you want to enable the feature in Production environments, submit a request at Zuora Global Support.

up-arrow.png Back to Table of Contents

here_black.png Orders and Subscriptions

Enhancements to automatic flow of cancelling subscriptions and refunding end customers

We enhanced the automatic flow of cancelling subscriptions and refunding end customers as follows:

  • Previously, the Invoice Item Settlement feature must have been enabled to access refunding settings when cancelling subscriptions and refunding end customers. We have removed this limitation.
  • Previously, we did not support cancelling subscriptions that are not invoiced separately and refunding end customers. You can now cancel such subscriptions and refund end customers by enabling the Invoice Item Settlement feature.

For more information, see Cancel subscriptions and refund end customers automatically.

We will release the enhancements only in Sandbox environments. The enhancements will not be available in Production environments until further notice.

Support for creating reports using Order Line Item data source

Previously, you could export data from the Order Line Item data source or query the Order Line Item object through Data Query.  Now, you can also create reports using the Order Line Item data source. For how to create a report, see Reporting.

UI enhancements to order actions

Previously, you could only edit change reasons for order actions through the Create an order and Create an order asynchronously API operations. We have now added the  Change Reason field for order actions in the UI.

Currently, the following order actions support the Change Reason field. We will gradually roll out support for this field in other order actions.

here_black.png Usage and Rating

Support for setting billing periods to a specific number of days

You can now set the billing period of a product rate plan charge to a specific number of days. This enhancement allows you to set up more flexible product billing periods. To enable this enhancement, go to Billing Settings > Define Billing Periods > Customize Billing Periods, then check Specific Days.

Note the following behaviours or limitations when specifying the Billing Period field to "Specific Days":

  • The Billing Day option will be unavailable. 
  • You can specify how the billing period of the charge will be aligned using the Billing Period Alignment field, for example:
    • When selecting "Align to Charge", the charge will follow its own billing period. 
    • When selecting "Align to Subscription Start", the charge will be aligned to the start day of the specific subscription.
  • The following features are not supported:
    • Prepaid with Drawdown
    • Billing Schedules
    • Rating Information Tool
    • Active Rating

up-arrow.png Back to Table of Contents

Zuora Payments

here_black.png Payments

Enhancements in passing and mapping company name for ACH Business Check on BlueSnap and

We have improved the approach of passing in and mapping the company name information for ACH payment methods of Business Check accounts on the BlueSnap and gateway integrations. We deprecated the Merchant's Company Name field from the gateway configuration page to avoid confusion. You can now pass in the company name through the following approaches:

For BlueSnap, the value passed in will be mapped to the payerInfo > companyName field, in addition to mapping to the firstName and lastName fields as we have already supported.

For, the value passed in will be mapped to the acccount_holder > company_name field, in addition to mapping to the first_name and last_name fields as we have already supported.

For the data on the existing gateway instances, we have migrated the field mappings to the updated design. You do not need to take any action. To make sure the new mappings work as you expect, we suggest that you can check the new mappings in the requests sent to the gateway and check your integrations where you pass in the Account Holder Name. If you have any questions, submit a request to Zuora Global Support.

Support for Payment Method Update object in custom events and custom scheduled events

You can now define custom events and custom scheduled events for the Payment Method Update object. When defining the event, select UpdaterDetail from the Base Object list.

For more information, see the following articles:

Enhancement in NOC messages of Citi Gateway Reconciliation

We have improved the Citi Gateway Reconciliation to present ACH account numbers in NOC messages in a user-friendly way. The last four digits of the ACH account number in NOC messages are now visible, and all previous digits are masked. Previously, the whole ACH account numbers are masked.

up-arrow.png Back to Table of Contents

Zuora Central Platform

here_black.png Feature Management

Self-serve interface for feature enablement is now available

Previously, you could submit Support requests to enable features in Billing, Payments, or Finance. Direct activation of certain EA or GA features is now possible through the Enable Feature option, without needing assistance from Support. You can test and customize all the available features in your Sandbox environment. However, access to features in your Production environment depends on your product entitlements. For more information about product entitlements, see Zuora Editions and Zuora Modules.

here_black.png Appstore Connector v2

Appstore Connector v2 available

Zuora has launched App Store Connectors v2, which delivers a simple and intuitive interface to configure connectors for apps on the Apple and Google stores. With Zuora’s app store connector, you can merge subscription data across platforms, sync in-app data with events, retry failed events, and more. You can use the new functionality to automate repetitive tasks, saving time and increasing productivity. 

We are actively soliciting feedback from a small set of early adopters before releasing it to all customers. To join this early adopter program, submit a request at Zuora Global Support.

here_black.png Reporting and Exports

Support for creating reports from saved data queries

When creating a report in Reporting, you can now use a saved data query to create the report. This provides you with more customization options and available objects when creating reports.

Previously, only a fixed set of data sources was supported.

For more information about how to save data queries in your tenant, see Save data queries.

For more information about this feature, see Create a report from saved data queries.

here_black.png Deployment Manager

Product Catalog deployments available in Deployment Manager

Product Catalog deployment is now generally available. Deployment Manager now supports deployment of your product catalog. This enables you to create products in the target tenant or deploy delta changes from the source to the target tenant.

For more information, see Product Catalog deployments.

here_black.png Events and Notifications

Support for tracking bounced emails sent from the default email server or Advanced SMTP server

When sending notification emails from the default email server or Advanced SMTP server, Zuora now captures and records the status of bounced emails. Bounced emails will present as Failed, with the following error message: Bounced email address(es): <email address(es)>.

You can report on bounced emails in the following ways:

  • The Email History tab on the Setup Profiles, Notifications and Email Templates page.
  • The Failures tab on the Notifications System Health dashboard. For more information, see Notifications dashboard.
  • Exported data through Data Query upon the NotificationHistoryEmail or NotificationHistoryEmailEvent table.
  • Exported data through Data Source Exports upon the Notification History - Email data source.
  • The List email notification histories API operation.

Note that you can enable alerts on failed email notifications, including bounced emails, using Notification System Health dashboard notifications. For more information, see Notifications dashboard.

For more information about Zuora SMTP server, see Configure an SMTP server for email notifications.

Increased maximum character limit for the base URL of callout notifications

The maximum character limit for the base URL of callout notifications is now 1000 characters.

This limitation applies to callout notifications based on standard, custom, or custom scheduled events.

Previously, the limit was 255 characters.

here_black.png Custom Objects

New custom field type available for custom objects

A new custom field type called "Multiselect" is now available for custom objects. You can specify multiple options for custom field definitions of this type.

When creating custom object records, you can select one or more options from the pre-defined list for multiselect-type fields. As a comparison, you can select only one option for picklist-type fields.

Multiselect fields have the following limitations:

  • The Multiselect field type does not apply to Zuora Standard Objects for this release.
  • The option values of a particular field must be unique.
  • The multiselect-type fields are not filterable at this time.

For more information, see Create a new custom object definition.

Enhancement to text-type fields of Custom Objects

A new data format called "URL" is available for text-type fields of Custom Objects. The values for fields with the URL format must be valid URL strings, such as

For example, you can utilize URL-formatted fields to record weblinks from external systems, such as Salesforce.

URL-formatted fields are not filterable at this time.

For more information, see Create a new custom object definition.

Support for display names for Custom Objects

You can now create display names for Custom Objects. The display name can be used as a user-friendly name for a custom object record linked to other custom objects.

For example, suppose that you have created two custom object definitions named "Vehicle" and "Tire Manufacturer" in your tenant. The Vehicle object contains a relationship-type field Tire linking to the Tire Manufacturer object. You can now enable the display name for the Tire Manufacturer object by creating a text-type field Manufacturer Name. When creating custom object records for the Vehicle object, real manufacturer names can be recorded as values for the Tire field. Previously, you could only use 36-character record IDs for the Tire field.

custom object relationship example.png

Display names have the following limitations:

  • Each custom object definition can have at most one field as the display name.
  • Only text-type fields with no format (such as UUID or URL) can be used as display names.

For more information, see Create a new custom object definition.

here_black.png Workflow 

Version comparison available in Workflow

A new feature called Difference Checker is now available in Workflow, which allows you to compare two versions. An icon clipboard_e81ccb8aa8f04531893f175e1fec23231.png is added on the top right corner in the Versions tab. You can choose to see the comparison results of the JSON definitions in a side-by-side Diff View or a Merged View.

Workflow Run Schedule Management

In the Settings tab of the Workflow application, you can now find a section to view all scheduled Workflows with the next run date and time. Additionally, you can also modify the schedule of the Workflow definition.

Note that you must have Workflow Manage permissions to view and change the schedules.

Record Finder in Workflow

In the Overview tab of the Workflow application, you can now provide a search text string to locate records where a Workflow execution happened. The Record Finder lets you provide a search string and then submit an asynchronous search job that runs in the background to find any tasks that may have included the search string. The search window is active for up to 12 hours.

For example, If you want to search for an invoice ID created or updated by a Workflow, provide the Invoice ID in the search box and click the Search button to submit a search job. In the search results, you can view the tasks containing the Invoice ID in the execution history.

up-arrow.png Back to Table of Contents


For the detailed API documentation, see API Reference.

For a summary of REST API updates and documentation updates in the Zuora API Reference, see 2023 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: 134

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.