What is Orders Harmonization?

Orders Harmonization is Orders in Harmonization mode, a path that allows Subscribe and Amend customers to adopt the Orders feature seamlessly and move to a modern architecture.

With Orders Harmonization enabled, you can access both Orders and existing Subscribe and Amend functionalities. This enables you to do the following:

• Use the Orders UI and API to create and manage subscriptions.

• Access new Zuora Billing features that require Orders.

• Continue using the Subscribe and Amend REST and SOAP API to create and manage subscriptions.

Enable Orders Harmonization

We recommend that all existing Zuora Billing Subscribe and Amend customers enable Orders Harmonization. Enabling Orders Harmonization does not impact your existing Subscribe and Amend API integrations or system functions.

Subscribe and Amend customers can enable Orders Harmonization through the self-service interface. See Feature Management.

For new Zuora Billing customers, Orders is enabled in your tenant by default. You cannot enable Orders Harmonization in this case.

Best practices after enabling Orders Harmonization

Once Orders Harmonization is enabled, your tenant is in Orders Harmonization mode, with access to Orders and all features that require Orders. We recommend the following best practices:

• Start using the Orders UI and API for ongoing transactions, and gradually phase out the transactions and traffic using Subscribe and Amend.

• Keep the tenant in Orders Harmonization mode and do not re-enable Orders. Orders without Harmonization mode not only removes the access to Subscribe and Amend, but also requires you to make necessary integration changes, migrate historical amendment data, and test your use cases.

How to tell whether 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

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. Note that if Orders Harmonization is enabled as of or after Zuora Release 2022.09.R2, the generation of the equivalent order for a subscription creation will be skipped by default. If you want to generate an equivalent order when creating a subscription using the Subscribe and Amend UI or API, configure the Skip amendment generation by subscribe setting to No .

• 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:

  • 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.