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're 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 S/A 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 use S/A 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 (S/A) APIs, an equivalent order is auto 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. 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 feature has been enabled, The Enable Order UI setting is available on the Subscriptions Settings page, 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 Subscribe and Amend UI and Orders UI.
When you turn on the Enable Order UI setting,you will see the following changes in Zuora Billing UI:
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.
A subscription suspended by amendment can be resumed by amendment only, and the subscription suspended by order can be resumed by order only.
A pending subscription created by an order can only be activated by that order instead of the relevant amendment.
For any subscription creation or amendment created through Subscribe and Amend APIs or UI, the existing Zuora Billing notifications configured in your tenant will continue to work.
However, as of Zuora Release 2022.01.R3, any new customers onboard on Order Harmonization will have the following default notification behavior in their tenants:
- Only amendment notifications are triggered for amendments that are created through the Subscribe and Amend APIs or UI.
- Only order notifications are triggered for order actions that are created through the Create an order operation or Orders UI.
Note that amendment notifications are sent only to the subscription owner of a subscription and order notifications are sent only to the invoice owner of a subscription.
Order relevant notifications will be shown on the Notification Settings page.
Previously in the tenants with the Order Harmonization feature enabled, both order notifications and amendment notifications were triggered by default for any subscription creation, amendment, or order action. Zuora recommended you configure only the orders notifications and turn off the existing amendment notifications if you did not want duplicate notifications.
If you are an existing Orders Harmonization customer, the existing notification behavior in your tenant remains unchanged. If you want to enable the new default notification behavior, submit a request at Zuora Global Support.
Your existing reports on any existing data will not be impacted. If you start creating subscriptions and amendments using Orders APIs or Orders UIs, then two standard reports will be impacted.
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.|
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.
Invoice and Invoice Settlement
No impact. You can continue to run bill runs and generate invoices for subscriptions when the Orders feature is enabled.
No impact if your org is on Zuora CPQ version 8.1 and above. Once the Orders feature has been enabled, Zuora CPQ makes Orders API calls to create Orders.
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.
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.
No impact to any existing integration from Zuora to Netsuite.
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.
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.
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