Zuora Release 2022.11.R3
Welcome to the release notes for Zuora Release 2022.11.R3. 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 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.
Orders and Subscriptions
Behavior change in notifications for auto-renewals on Orders Harmonization tenants and new setting to select notifications for auto-renewals
If your Zuora Billing tenant has Orders Harmonization enabled, a setting called Auto-Renew by Order is now available in Billing Settings > Define Default Subscription and Order Settings on your tenant. You can use this setting to select whether to send Orders notifications for auto-renewals of subscriptions. The options for the setting are as follows:
- Yes: Send order notifications for auto-renewals of subscriptions. Yes is the default value on the tenants with Orders Harmonization enabled before Zuora Release 2022.09.R2.
- No: Send amendment notifications for auto-renewals of subscriptions. No is the default value on the tenants with Orders Harmonization enabled through the rolling release starting from Zuora Release 2022.09.R2.
If your tenant has Orders Harmonization enabled before Zuora Release 2022.09.R2, the Auto-Renew by Order setting may introduce a behavior change to your notifications for auto-renewals. No matter which type of notifications you used previously, Zuora Billing now sends only order notifications for auto-renewals by default. If you want to send amendments notifications for auto-renewals, configure the Auto-Renew by Order setting to No.
New setting to skip generating amendment for subscription creation when using Subscribe and Amend UI or API on Orders Harmonization tenants
If your Zuora Billing tenant has Orders Harmonization enabled, a setting called Skip amendment generation by subscribe is now available in Billing Settings > Define Default Subscription and Order Settings on your tenant. You can use this setting to choose whether to skip generating an amendment of the Composite type for a subscription creation when using the Subscribe and Amend UI or API. The options for the setting are as follows:
- Yes: Skip generating an amendment of the Composite type for a subscription creation through the Subscribe and Amend UI or API on your Orders Harmonization tenant. Yes is the default value on the tenants with Orders Harmonization enabled through the rolling release starting from Zuora Release 2022.09.R2.
- No: Generate an amendment of the Composite type for a subscription creation through the Subscribe and Amend UI or API on your Orders Harmonization tenant. No is the default value on the tenants with Orders Harmonization enabled before Zuora Release 2022.09.R2.
New setting for CPQ customers to enable Orders on Orders Harmonization tenants
If your Zuora Billing tenant has Orders Harmonization enabled, a setting called Enable Order for CPQ is now available in Billing Settings > Define Default Subscription and Order Settings on your tenant. If you are a Zuora CPQ customer, you can use this setting to choose whether your CPQ org integrated with the Billing tenant makes Orders API calls to create and manage subscriptions on the Billing side. The options for the setting are as follows:
- Yes: Your CPQ org integrated with the Billing tenant makes Orders API calls to create and manage subscriptions on the Billing side.
- No: the default value. Your CPQ org integrated with the Billing tenant makes Subscribe and Amend API calls to create and manage subscriptions on the Billing side.
Additional fields on Booking Transaction object available for Data Source Export and Data Query
The following fields are now available on the Booking Transactions object:
- Amendment Create Date
- Original Charge Create Date
- Original Charge Segment Create Date
- Original Term Start Date
- Subscription Last Booking Date
For more information, see Booking Transaction data source and Booking Transaction object fields and Data Query.
New Order Line Item related fields on Booking Transaction object available for Data Source Export and Data Query
Previously, the Booking Transaction object captured changes on the rate plan charges, and now the Booking Transaction object also captures the order line items information through the following new fields:
- Billing Rule
- Customer ID
- Customer Name
- Customer Number
- Charge/OLI Create Date
- Charge/OLI Update Date
- Inline Discount Amount
- Item Name
- Order Line Item Category
- Original Sales Order Line Item ID
- Sales Order Number
For more information, see Booking Transaction data source and Booking Transaction object fields and Data Query.
Invoicing and Tax
Billing Schedule available for early adopters
You can now bill your customers based on contract negotiations or project milestones. With the Billing Schedule feature, you can generate invoices based on predefined invoicing dates and amounts.
- You can specify customized invoicing dates that do not follow standard billing frequencies such as monthly, quarterly, annually, and so on. You can set invoicing dates to any date to meet business requirements.
- You can also specify invoicing amounts that vary based on certain criteria for each invoice.
For example, for a subscription with a term of 12 months and a total amount of $12,000, you can bill $3,000 in the first invoice on February 1, $7,000 in the second invoice on July 12, and the remaining $2,000 in the third invoice on November 15.
For more information about this feature, see Billing Schedule.
For a summary of the latest REST API updates specific to this feature, see “API Updates for Billing Schedule” section in 2022 API Changelog (2022-11-14) and API Reference.
The Billing Schedule feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at Zuora Global Support.
Annual List Price available for early adopters
You can now sell your products and services based on an annual list price, and bill your customers with non-annual billing periods.
The Annual List Price feature provides you the capability to set up a recurring charge with an annual list price in the product catalog, and then sell the charge with various billing periods, for example, monthly, quarterly, every four months, semi-annually, annually, and so on. You can bill subscriptions to generate expected invoices for your end customers.
For more information, see Annual List Price.
For a summary of the latest REST API updates specific to this feature, see “API Updates for Annual List Price” section in 2022 API Changelog (2022-11-14) and API Reference.
The Annual List Price feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at Zuora Global Support.
New field creditMemoAmount available on Invoice object
Previously, when multiple credit memos were applied to an invoice, you had to calculate the sum of credit amounts from the credit memos for the invoice if needed.
creditMemoAmount field on the Invoice object is now available for API, Data Source Export, Data Query, and Object Query. The field indicates the sum of credit amounts of all credit memos for an invoice. With the field, you can display credit amounts for each invoice on your customer tenant.
Usage and Rating
Resolved: Auto truncation of decimal numbers passed by custom fields during usage import
Previously, when you import usage data in the Microsoft Excel (.xls) format, if the columns of text-type custom fields are set to the numeric format, decimal numbers in the columns will be automatically truncated to integers.
The auto-truncation issue has been resolved. Decimal numbers specified in the text-type custom fields will be imported to Zuora without being truncated now. Note that the fix is not enabled by default. If you want to enable this fix for your tenant, submit a request at Zuora Global Support.
See Import Usage Data for more information.
Deprecation of AVS and CVV validation features on CyberSource v1.28 and PayPal Payflow Pro
On 15 November 2022 PDT, the Address Verification Service (AVS) and Card Verification Value (CVV) validation features on the following gateway integrations are deprecated:
- CyberSource Enterprise Gateway, API v1.28
- PayPal Payflow Pro
For customers who use the preceding gateway integrations, the deprecation does not impact your payment process, and you do not need to take any actions.
After the AVS and CVV validation features on the preceding gateway integrations are deprecated, we do not validate the AVS and CVV responses from the corresponding gateways. We use the responses from the gateways in transaction processing to ensure a consistent result on the related payments between Zuora and gateways.
If you have any questions about the upcoming deprecation, contact Zuora Global Support.
Support for processing Level 2 card data on Mastercard gateway integrations
To support processing payments successfully through the Mastercard gateway integration, we have improved this gateway integration to support processing the following Level 2 card data:
To avoid payment failures in some regions such as Ecuador, you must enable this feature by selecting Enable L2 on the gateway configuration page, and then the tax amount and item amount for the order will be sent to the gateway.
For more information, see Mastercard payment gateway.
Automation of linking payments to payment schedules through Fuzzy Logic
The Fuzzy Logic setting allows automation of linking incoming payments to payment schedules. With the setting, you can also specify a time range within which a payment and a payment schedule item are allowed to be linked.
After the Fuzzy Logic setting is turned on, we will automatically link any newly created or imported payment to a payment schedule item. A successful linking must meet all the following validation rules:
- The following formula is satisfied: Collection Date of the payment schedule item - Threshold Value < Payment Date of the payment < Collection Date of the payment schedule item + Threshold Value. For example, suppose the Collection Date of a payment schedule item is 2022/10/1 and the Threshold Value is set to 5, a payment with a Payment Date between 2022/09/26 to 2022/10/6 would be linked to the payment schedule item if all the other validations are passed.
- The invoice on the payment schedule item and the payment is the same.
- The amount of the payment schedule item and payment is the same.
- The status of the payment schedule item to be linked must be
Pendingand the payment schedule item has not been linked to any other payment.
- The payment schedule status must be
- The payment and the payment schedule item must belong to the same account.
Support for skipping payment schedule items on payment schedule details page
You can now skip a payment schedule item on the payment schedule details page. This operation allows you to skip one
Pending payment schedule item at a time. The skipped payment schedule item will turn to the
Cancelled status, and a new payment schedule item will be scheduled on the next recurring date after the last existing scheduled date.
We also introduce a new Cancellation Reason field on the Payment Schedule Item object to indicate the reason why the payment schedule item is canceled. Note that for now, the only available value of the Cancellation Reason field is
Skip Payment. In addition, you can retrieve the cancellation reason data through Data Query or Data Source Export.
Support for Adyen Checkout API v66
We have upgraded Adyen Integration v2.0 to support Adyen’s Checkout API version 66. The previous version was version 49. For more information, see Adyen Integration v2.0.
Token usage analysis for payment pages available
You can now check the usage analysis of tokens used for rendering payment pages in the past 30 days in Zuora UI. On the Hosted Pages page, click the token usage analysis link above the Page List section, and the following information for the past 30 days is available in a pop-up window:
- The number of tokens used for rendering payment pages.
- The number of page rendering failures due to the reuse of the same token.
- If the rate of failures due to the reuse of the same token is significant, a suggestion and related article are provided for your further analysis.
For more information, see Generate and manage the Digital Signature and Token for Payment Pages 2.0.
Support for passing IPv6 addresses to gateways when creating or updating payment methods
You can now use the
IPAddress field in any of the following API operations to pass IPv6 information to gateways. Gateways normally use IP information for payment fraud prevention.
Payment Pages 2.0 also support passing the IP address through the
ipAddress parameter when creating or updating a payment method. This parameter now supports IPv6. For more information, see Payment Pages 2.0 form fields.
Support for Delayed Capture on Stripe v2
Stripe v2 gateway integrations now support the Delayed Capture feature for credit card payment methods. You can use this feature to authorize a payment amount before capturing the payment. Subsequently, you can fully or partially capture the authorized amount or cancel the authorization.
See Stripe payment gateway for more information.
Support for card blacklist for hosted payment pages
A new tenant-level setting called Blacklisted Card BINs is now available for Credit Card payment pages. You can define and block cards to be added through payment pages. The cards defined in the blacklist will not be added in Zuora nor submitted to gateways.
To enable this feature, submit a request at Zuora Global Support.
For more information, see Create and configure Payment Pages 2.0.
Support for passing email addresses to Adyen for Apple Pay and Google Pay payment transactions
When creating Apple Pay or Google Pay payment methods or creating payments of these payment methods on Adyen Integration v2.0 through the REST API operations, you can now use the
gatewayOptions field in any of the following operations to pass the shopperEmail information to the Adyen gateway:
For more information, see the following articles:
- Gateway Options fields supported by Adyen Integration v2.0
- Set up Adyen Apple Pay
- Set up Adyen Google Pay
Zuora Central Platform
Events and Notifications
Support for disabling communication profiles
You can now disable individual communication profiles, or disable all communication profiles by clicking Mute All. After a communication profile is disabled, we will no longer trigger email or callout notifications in this profile.
This feature provides simplicity and flexibility in implementing notifications, without sending unexpected notifications to your customers during configurations.
Enhancement to email notifications for order action events
You can now include a subscription details table in an email notification that is triggered and sent by the Create Subscription order action. To realize the function, you need to include the merge field tag <Subscription.SubscriptionDetailTable> in the email body of an email template and select the email template in a notification that is configured with the Order Action Processed related event and the CreateSubscription type.
A subscription details table includes the following information about subscriptions created within an order:
Effective Start Date
Unit Price (not displayed for the Tiered Charge model)
You can set the merge field tag by navigating to Billing > Setup Profiles, Notifications and Email Templates > Email Templates. After specifying Event as Order Action Processed in the Basic Information section in the Email Templates tab, you need to include the merge field tag "<Subscription.SubscriptionDetailTable>" in the Email Body field.
After selecting Subscription from the Select Field Type list and selecting Subscription Details from the Select Field list in the Available Merge Fields section, you can copy the merge field tag from the Merge Field Tag field and then paste the merge field tag into the email body text to include the tag.
For information about the merge field, see Email Template Legacy Merge Fields.
For notification and email template configurations, see Create and Edit Notifications and Manage Email Templates.
Support for exporting attempt numbers of callout notifications in Data Sources, AQuA, and Data Query
AttemptLimit fields are now available in the Notification History - Callout data source. You can export these values in Data Sources, AQuA, and Data Query.
AttemptNumber: the number of attempts of a callout notification.
AttemptLimit: the maximum number of attempts of a callout notification. For more information about how to configure the maximum number of attempts, see Configure callout settings.
When a callout notification fails, Zuora resends this callout notification until the notification is successful or the number of attempts reaches the limitation. If the value of the
AttemptNumber field is greater than one, it indicates this callout notification has been resent.
Note that these fields apply only to callout notifications created since January 2022.
Email and callout notifications available for APIs System Health dashboard
Three new standard events, API Failures, API Performance, and API Concurrency, are now available for the APIs System Health dashboard.
You can send callout or email notifications based on evaluation parameters of the APIs System Health dashboard events. These parameters include evaluation frequency, triggering threshold, threshold type, time range, and API endpoint.
For example, you can define notifications as follows:
- If the number of failed API requests over the last 24 hours is greater than or equal to 10, an email notification is sent.
- If the average response time of all API requests over the last 30 minutes is greater than or equal to 5000 milliseconds, a callout notification is sent.
Note that this feature is available only if you have Zuora System Health enabled.
For more information, see Standard events for Zuora Central Platform.
Redesigned building workflow experience
The following enhancements have been made to the building workflow:
- You can now search for a task in the task library. Search feature has been introduced in the task library which enables you to search for a task.
- You can now drag and drop the tasks into the canvas. This feature is in addition to the existing method of adding a task. The dropped task is placed in the line between linked tasks, and at the end of a flow.
Redesigned swimlane workflow experience
Swimlane workflow has been enhanced with the following features:
- The Swimlane landing page now displays the API logs and Data Payload in a tab. You can download and save the API responses in the Response tab.
- A new toolbar is introduced on the right side of the page to access the liquid tester ( ) feature. Liquid tester allows the user to view outputs along with the inputs. The toolbar has the option to view and copy the task properties ().
- The workflow Task Config button is now replaced with a new Promote () option, which allows users to make changes in the Task Config () and then publish changes to the swimlane run-time version.
- The color of the Edit Workflow icon () on the execution summary is now changed for better visibility and easy discovery. The Edit Workflow button enables users to go back to the canvas without having to exit the workflow.
- When you Rerun () a task on the Swimlane page, the task status now changes to Queued and presents the user with a refresh icon to reload the task results without having to leave the page.
New System Health dashboard available
We have now released the following dashboard:
|System Health dashboard||Data contained in the dashboard|
|Gateway Reconciliation||Describes how to use Zuora System Health dashboard for Gateway Reconciliation that collects and displays data about gateway reconciliation usage, and failure in near real time.|
For the initial few days, only seven days of data is available.
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.
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: 127
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.