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.
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. You do not need to go through full migration in order to leverage Orders related functionality.
What this means is you have the flexibility to transition to Orders at your own pace. If you have an existing web portal integration, you can decide to keep that integration on Subscribe and Amend APIs while you leverage Orders APIs for other channels. One subscription can be managed by both Subscribe and Amend APIs and Orders UI/APIs.
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 of type “Composite” is created. Whether you create an order with one change (order action) or multiple changes, it will still create one amendment of type “Composite”.
Composite Amendment is a subscription level amendment that is used as a placeholder to bridge subscription versions.
See the diagram below that shows how a subscription created before the Orders Harmonization feature is enabled is now modified by both Orders and Subscribe and Amend APIs.
Starting from Step 4, the Orders Harmonization feature is enabled.
- In Step 4, for every Order created using Orders APIs or Orders UI, an amendment is auto-generated for Order O-001 with type “Composite”.
- In Step 5, the Subscribe and Amend API is used to create a renewal amendment. Order O-002 is auto-generated with the order action type “Renewal”.
- In Step 6, Subscribe and Amend API is used to remove a product. Order O-003 is auto-generated with the order action type “RemoveProduct”.
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.
Zuora Billing UI (Orders UI)
Once the Orders feature has been enabled, 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.
In the Zuora Billing UI, the create new subscription button on the account details page is replaced with the create order button.
From the All Subscriptions page and All Amendments page, there are no add new subscription and create new amendment buttons.
In addition, you will see an Orders tab. Going forward, any new subscription or amendment needs to be handled through Create Order flow.
See Orders Tutorials on how you can create and manage subscriptions using Orders.
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.|
For any subscription creation or amendment created through Subscribe and Amend APIs, 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.
- Only order notifications are triggered for order actions that are created through the Create an order operation.
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.
How do I get started?
Before you get started, please go through the Limitations in Orders for any potential impact to your business scenarios. Once you have gone through it, you can create a support ticket to Zuora Global Support to enable Orders.
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