Overview of Orders Harmonization
This article introduces Orders Harmonization.
What is Orders Harmonization?
If you are an existing Subscribe and Amend customer, and want to leverage Orders, Orders Harmonization helps you to transition to Orders easily. Previously, to adopt Orders, you had to migrate all your existing integrations on Subscribe and Amend APIs to the new Orders REST APIs.
Zuora is in the process of proactively reaching out to customers to enable the Orders feature. If you are interested in migrating to Orders, please contact support or your CSM. The migrated customers can benefit from the new functionalities like Order Delta Metrics, Order Line Items, and improved reporting features previously available on Orders only. Migration causes no behavior change for the Subscribe and Amend customers.
With Orders Harmonization, you can continue to use Subscribe and Amend APIs and also use Orders APIs and Orders UI to create and manage your subscriptions. Also, customers can continue to manage subscriptions and amendments from UI until they want to adopt the Orders UI. You do not need to go through full migration in order to leverage Orders related functionality.
However, if you still want to refactor all of your existing Subscribe and Amend APIs to Orders APIs and also migrate historical data created to Orders, you can still do that. See Orders Migration Guidance for details.
How does it work?
With the Orders Harmonization feature, for every subscription or amendment created in the system using Subscribe and Amend APIs, an equivalent order is automatically generated. This order will have the details on order action - based on the amendment type you create. See the diagram below on Post Orders Harmonization.
For every order created using Orders API or Orders UI, an amendment is automatically created. The type of the amendment can be either type ‘Composite’ or the actual order action type.
-
When you create an order with multiple order actions or 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.
-
When you create an order with only one single order action of any type other than 'Create subscription', an amendment of the actual order action type is created for providing more useful information for business analysis.
What impact does it have on my existing processes and integration to Zuora?
With Orders Harmonization, the impact is minimal. See below for a summary of the key changes. Note these scenarios are for your reference only. You can also join the Orders Harmonization Community group for more information about your end-to-end scenarios. If you have any questions, please reach out to your Account or CSM representative.
Inbound Subscribe and Amend APIs
No impact on any existing inbound integrations with Subscribe and Amend APIs. You can continue to use both SOAP and REST Subscribe and Amend APIs to create subscriptions and subscription amendments. A subscription suspended by Subscribe and Amend APIs can be resumed either from the Zuora Billing UI or through Subscribe and Amend APIs.
No impact on Subscribe and Amend APIs. You can continue to use the Subscribe and Amend APIs (both SOAP and REST) to create subscriptions and subscription amendments.
If the last version of a subscription is created through the Subscribe or Amend APIs, when this subscription gets an autorenewal, it will be renewed through an amendment of the Renewal type. When the equivalent order is auto-generated, the description of the order is "Created by migration".
Zuora Billing UI (Orders UI)
Once the Orders Harmonization feature has been enabled, the Enable Order UI setting is available in Billing Settings > Define Default Subscription and Order Settings on your tenant, which acts as a switch between Amendment and Orders. The Orders UI remains turned off by default.
If you are an existing Orders Harmonization customer, you can also see the Enable Order UI setting and switch between the Subscription and Amendment UI, and Orders UI. You can turn off the Enable Order UI setting to switch back to the Subscription and Amendment UI.
When you turn on the Enable Order UI setting, you will see the following changes in Zuora Billing UI:
| Before Orders | Orders |
|---|---|
|
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. |
Customers can create orders from the Subscription list view. This option is available for all the Orders and Orders Harmonization customers. |
|
If you create multiple amendments to the same subscription, multiple subscription versions are generated. 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. |
Subscriptions suspended by order can be resumed by order only.
Notifications
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 the order notifications and amendment notifications are triggered by default for any subscription creation, amendment, or order action. 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 that are created through the Subscribe and Amend API or UI.
- Only order notifications are triggered for order actions that are 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.
- The order notifications are shown on the Notification Settings page.
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.
If you want to switch the notification behavior for auto-renewals on your tenant, use the Auto-Renew by Order setting in Billing Settings > Define Default Subscription and Order Settings on your tenant.
Reporting
Your existing reports on any existing data will not be impacted. If you start creating subscriptions and amendments using Orders API or UI, then two standard reports will be impacted. See the following table for more information.
| Before Orders | Orders |
|---|---|
|
You can use the CMRR related standard reports related.
|
The ‘CMRR by product’ standard report will be impacted as the amendment type will not be consistently populated for subscriptions created using Orders (both UI and API). Zuora recommends you use Zuora Analytics instead, which support 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 by 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 rate plan, rate plan charge, invoice item to determine, for example, all the new products added in 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. You can use the "Net MRR" and “Order TCB” standard reports. You can get the reports on slicing order actions that happened on an account or subscription. However, all the historical data created before the Orders feature is enabled will not be available in the Orders related reports unless you go through the migration. You may need to use two reports to get a holistic view of the data. In such a case, to make the data consistent for the Order related reports, Zuora recommends you go through migration for all of your historical data. See Orders Migration Guidance. |
| 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". 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
Once the Orders feature has been enabled, certain functions in the Data Query will be impacted:
No impact if your data query (or any data source export) is built on the Rate Plan data source and is not dependent on the amendment type.
However, if your data query is dependent on the Amendment type, Zuora recommends you to switch it to the order action available in the Order Action data source. You can join the Orders Harmonization Community group for sample queries.
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".
Invoice and Invoice Settlement
No impact. You can continue to run bill runs and generate invoices for subscriptions when the Orders feature is enabled.
Zuora CPQ
No impact if your org is on Zuora CPQ version 8.1 and above. 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. If 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.
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, then you need to change the integration to the Order Action object.
| Previous Behaviors | Orders |
|---|---|
|
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. |
Resources
See the following resources for more information about the Orders feature:
- Overview of Orders
- Orders Migration Guidance
- REST API Reference
- Modify Custom Fields in Orders
- Default Subscription and Order Settings:
- Ramps Settings for Orders UI:
- Notifications for Orders