Skip to main content

Overview of Orders Harmonization

Zuora

Overview of Orders Harmonization

This article introduces Orders Harmonization.

What is Orders Harmonization?

If you are a Zuora Billing Subscribe and Amend customer, we recommend you enable Orders Harmonization to adopt Orders. The benefit is that you can access both the Orders feature and existing Subscribe and Amend functionalities, which means the following:

  • You can use the Orders APIs or UI to create and manage subscriptions, and also access the new features on Zuora Billing.
  • Meanwhile, you can continue to use the Subscribe and Amend APIs (both SOAP and REST) to create and manage subscriptions.
  • You can continue to use the Subscribe and Amend UI until you want to enable the Orders UI. 

We recommend that all existing Zuora Billing customers enable Orders Harmonization. Enabling Orders Harmonization does not impact your existing Subscribe and Amend API integrations or system functions. For customers who have not got Orders Harmonization yet, you can enable it through the self-service interface. See Feature Management.

How to tell whether Orders Harmonization is enabled?

If Orders Harmonization is enabled, you can see one of the following scenarios on your tenant:

  • When Orders Harmonization is enabled and the Subscribe and Amend UI is still in use, you can see a setting called Enable Order UI? in Billing Settings > Define Default Subscription and Order Settings of the UI. 
  • When Orders Harmonization is enabled and the Orders UI is enabled, in addition to the preceding Enable Order UI? setting, you can also see both Amendments and Orders under the Customers tab in the left navigation menu.
Orders Harmonization Tenants with Subscribe and Amend UI in Use Orders Harmonization Tenants with Orders UI Enabled
Subscribe and Amend tenant.png Orders Harmonization tenant.png

How does it work? 

The following diagrams illustrate the API behavior mappings in the co-existence model of Orders with Subscribe and Amend:

  • For every subscription or amendment that you create using Subscribe and Amend APIs, an equivalent order is automatically generated in the system. This order has the change you make recorded on an order action.2023 Orders Harmonization Coexist Model - S_A part.png
  • For every order that you create using Orders API or Orders UI, an amendment is automatically generated in the system. The type of the amendment is "Composite" or the actual order action type, based on the rule below:2023 Orders Harmonization Coexist Model - Orders part.png
    • If you create an order with multiple order actions, an amendment of type "Composite" is created. The Composite amendment is a subscription-level amendment that is used as a placeholder to bridge subscription versions.

    • If you create an order with only one single order action of the type "Create subscription", an amendment of type "Composite" is created. The Composite amendment is a subscription-level amendment that is used as a placeholder to bridge subscription versions.

    • If you create an order with only one single order action of a type other than "Create subscription", an amendment of the actual order action type is created to provide more useful information for business analysis.

How to adopt Orders after enabling Orders Harmonization?

After enabling Orders Harmonization, you can do the following to adopt Orders:

Enable Orders UI

When Orders Harmonization is enabled, the Orders UI remains turned off by default. You can switch to the Orders UI to create and manage subscriptions, and access the other functionalities empowered by Orders. 

To enable the Orders UI, perform the following steps:

  1. Click your avatar at the top right and navigate to Billing > Define Default Subscription and Order Settings.
  2. Identify to the Default Order Settings section and click Edit.
  3. Switch the Enable Order UI? setting to Yes.

Use Orders API

After enabling Orders Harmonization, you can use the Orders API to create and manage subscriptions.

See the following table for an API mapping between using Subscribe and Amend API and using Orders API for your common use cases:

Subscribe and Amend APIs Orders API

Create a subscription

Previously, you would use one of the following API functions:

Use the Create order operation instead.

See Create a Subscription.

Renew a subscription

Previously, you would use one of the following API functions:

Use the Create order operation instead.

See Renew a Subscription.

Cancel a subscription

Previously, you would use one of the following API functions:

Use the Create order operation instead.

See Cancel a Subscription.

Add, update, or remove products in a subscription

Change the terms and conditions of a subscription

Transfer ownership of a subscription

Previously, you would use one of the following API functions:

Use the Create order operation instead.

See Orders Tutorials.

 

Suspend and resume a subscription

Previously, you would use the following API functions:

Use the Create order operation instead.

See Orders Tutorials.

Update custom fields of a subscription

Previously, you would use one of the following API functions:

Use the Update subscription custom fields operation instead.

Preview a subscription

Previously, you would use the Preview subscription operation. 

Use the Preview order operation instead.

Notifications

The notification behaviors vary depending on when you enable Orders Harmonization. In some cases, you might want to adjust the configuration for notifications. If your system integration depends on notification callouts, when you replace Subscribe and Amend notifications with Orders notifications, you might need to change your integration accordingly for the Orders notification. See details below:

General behaviors

If your tenants have Orders Harmonization enabled before Zuora Release 2022.01.R3, the notification behaviors of your tenants are as follows:

  • For any subscription creation or amendment created through the Subscribe and Amend API or UI, the existing Zuora Billing notifications configured on your tenant will continue to work.
  • Both order notifications and amendment notifications are triggered by default for any subscription creation, amendment, or order action. [Action to consider] Zuora recommends you configure only the order notifications and turn off the existing amendment notifications if you do not want duplicate notifications. 

If your tenants have Orders Harmonization enabled as of or after Zuora Release 2022.01.R3, the notification behaviors of your tenants are as follows:

  • Only amendment notifications are triggered for amendments created through the Subscribe and Amend API or UI. 
  • Only Order notifications are triggered for order actions created through the Create an order operation or Orders UI. 
  • The amendment notifications are sent only to the subscription owner of a subscription. The order notifications are sent only to the invoice owner of a subscription.
  • To configure the Orders notifications, click your avatar at the top right and navigate to Billing > Setup Profiles, Notifications and Email Templates.

Notification behaviors for auto-renewals

If your tenants have Orders Harmonization enabled before Zuora Release 2022.09.R2, only order notifications are sent for auto-renewals of subscriptions.

If your tenants have Orders Harmonization enabled as of or after Zuora Release 2022.09.R2, only amendment notifications are sent for auto-renewals of subscriptions.

[Action to consider] If you want to switch the notification behavior for auto-renewals of your tenant, use the Auto-Renew by Order? setting in Billing Settings > Define Default Subscription and Order Settings of the Zuora Billing UI.

Inbound Subscribe and Amend APIs

When Orders Harmonization is enabled, you will see the following expected behaviors: 

  • A subscription suspended by Subscribe and Amend APIs can only be resumed by the Subscribe and Amend UI or APIs.
  • If the last version of a subscription is created through the Subscribe or Amend APIs, when this subscription gets an autorenewal, it is renewed through an amendment of the Renewal type. When the equivalent order is auto-generated, the description for this order is "Created by migration".

Zuora Billing UI (Orders UI)

The following table lists the behavior changes you will see when the Orders UI is enabled:

Before Orders Harmonization Orders Harmonization

Create subscriptions from the Accounts or Subscriptions page in the Zuora Billing UI.

Create subscription amendments from the Amendments page or subscription details page in the Zuora Billing UI.

  • From the All Subscriptions page and All Amendments page, there are no add new subscription and create new amendment buttons. They are replaced with the create new order button, which means you cannot edit subscriptions through amendments. You are encouraged to use Orders to perform the operations.

  • In addition, you will see an Orders tab. See Orders Tutorials on creating and managing subscriptions using Orders UI.

Customers can create orders from the Subscription list view. This option is available for all the Orders and Orders Harmonization customers.

Multiple subscription versions are generated if you create multiple amendments to the same subscription. Zuora generates a new subscription version for each subscription amendment.

You can view the subscription version history in the Version part of the subscription details page. The Amendment numbers are displayed in the version history.

If you create an order with multiple changes to the same subscription, only one subscription version is generated. You will see Orders instead of Amendments in Subscription versions.

On the account details page, you can see all the relevant subscriptions and the corresponding amendments.  In addition to the existing subscription and amendment tabs, an Orders tab is also available on the account details page to display all the transactions that occurred for that account.

In the Subscription History Change section of the Subscription details page, you can see the change history of a subscription through amendments.

In the Subscription History Change section of the Subscription details page, you can see the change history of a subscription through both orders and amendments. See Viewing Subscription Change History

Reporting

Your existing reports on any existing data will not be impacted. Two standard reports will be impacted if you create subscriptions and amendments using Orders API or UI. See the following table:

Before Orders Harmonization Orders Harmonization

You can use the CMRR-related standard reports.

 

The ‘CMRR by product’ standard report will be impacted as the amendment type will not consistently be populated for subscriptions created using Orders (UI and API). Zuora recommends you use Zuora Analytics instead, which supports Net MRR.

The ‘Subscription changes’ standard report will be impacted because the amendment type will be "Composite" for any new subscriptions or subscription changes created using Orders. If you rely on this report, then for any subscriptions or amendments managed post Orders, Zuora recommends you use the "Order actions" standard report.

You can rely on the rate plan, rate plan charge, and invoice item to determine, for example, all the new products added this month or all the products that have been upgraded or increased in quantity.

New reports are available for Orders which helps you to get the impact on MRR and TCB for the price or quantity changes. The "Net MRR" and “Order TCB” standard reports can be used. You can get reports on slicing order actions that happened on an account or subscription.

On the Exports page, the Orders Zip item is available. On the Exports page, the Orders Zip item has been removed from the Export Data drop-down list. 

Note that the Amendment type will be "Composite" for any new subscriptions or subscription changes created through Orders. This Composite amendment will not hold any details of the subscription changes.

Also, for a subscription creation through the Subscribe and Amend UI or API, the Amendment type will be "Composite". [Action to consider] If you want to skip generating an amendment of the Composite type for a subscription creation when using the Subscribe and Amend UI or API, configure the Skip amendment generation by subscribe setting to No in Billing Settings > Define Default Subscription and Order Settings on your tenant.

Data Sources and Data Query 

No impact if your data query (or any data source export) is not dependent on the Amendment type.

However, if your data query depends on the Amendment type, Zuora recommends you switch it to the order action available in the Order Action data source.

Zuora CPQ

No impact if your org is on Zuora CPQ version 8.1 and above, and you continue to use continues to make Subscribe and Amend API calls to create and manage subscriptions on the Billing side.

If your org is on Zuora CPQ version 8.1 and above, and you want your CPQ org integrated with the Billing tenant to make Orders API calls to create and manage subscriptions on the Billing side, configure the Enable Order for CPQ setting to Yes in Billing Settings > Define Default Subscription and Order Settings on your tenant.

If your org is on Zuora CPQ version below 8, you need to upgrade to the Zuora CPQ 9 version to enable Orders in your org.

When your Zuora Billing tenants have Orders Harmonization enabled, Zuora CPQ continues to make Subscribe and Amend API calls to create and manage subscriptions on the Billing side.

Zuora 360 Sync

No impact. You can continue to use Zuora 360 Sync to sync the Zuora Billing data from Zuora to Salesforce.

Orders related objects are not supported with Zuora 360 Sync.

Zuora Salesforce Connector

No impact. You can continue to use Zuora Salesforce Connector which is on Subscribe and Amend APIs.

Analytics

No impact. 

Workflow

You can continue to use amendment action to set actions based on certain conditions. However, if a subscription is suspended by Orders API, it cannot be resumed through the Subscribe and Amend APIs. See Limitations in Orders for Zuora Billing.

Netsuite Connector

No impact on any existing integration from Zuora to Netsuite. 

Flexera Connector

If you use the Flexera connector and start using Orders APIs or Orders UI, you need to change the integration to the Order Action object.

Previous Behaviors Orders Harmonization

The Flexera integration relies on the amendment types to manage any change in entitlements.

 

If you use only the Subscribe and Amend APIs to create subscriptions, your Flexera integration will continue to work. However, if your subscriptions or subscription changes are created through Orders APIs or Orders UI, your integration needs to be updated to use the Order Action object instead of the Amendment object.