Skip to main content

Scheduled orders


Scheduled orders

The Scheduled Orders feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at Zuora Global Support.

For a subscription, you can schedule one or more orders in a scheduler to be executed on future dates through the Orders REST API. Each order can include one or more order actions. The scheduler is formed by setting the status of all orders (except the first order in the scheduler) as Scheduled  and setting the following two nested fields in the schedulingOptions field for these scheduled orders:

  • Set scheduledDatePolicy to SpecificDate
  • Specify a scheduledDate. The scheduledDate refers to the scheduled date when the order is executed and completed.

For more information, see the following API operations:

You can schedule all order actions through scheduled orders before the scheduled orders are executed.

The following diagram illustrates examples of scheduled orders, including some order actions and subscription version changes for the scheduled orders. 

Example of scheduled orders

Scheduled orders example.png

There are four orders O-00001 to O-00004 scheduled. Order O-00001 is a normal order and the rest of the orders are scheduled orders.

The following table illustrates the order actions in the orders and the history version changes for the orders. 

Order Number Order Action Subscription History

O-00001 includes the Create Subscription order action, and an offer A is added to the subscription.

A subscription history version V1 is generated for O-00001.
O-00002 O-00002 includes the Suspend order action.

Although O-00004 is created on January 16, which is later than the creation date of January 15 for O-00002, O-00004 is scheduled to be completed on February 1, which is earlier than the completion date of February 5 for O-00002.

In this case, a subscription history version V2 is generated for O-00004, and a subscription history version V3 is generated for O-00002. That is, the subscription version is generated following the sequence of the completion dates.

O-00003 O-00003 includes the Resume order action. For the same reason as O-00002, a subscription history version V4 is generated for O-00003.

O-00004 includes the Update Product order action.

A subscription history version V2 is generated for O-00004.


You will understand scheduled orders from the following frequently asked questions:

Q: Do scheduled orders support for Evergreen subscriptions?

A: Scheduled orders support for both Termed and Evergreen subscriptions.

Q: When should I use scheduled orders, and when should I use non-scheduled orders?

A: When you need an order to take effect immediately or within the current term, you are recommended to use non-scheduled orders. The benefits of scheduled orders are: you can update and cancel the scheduled orders before the scheduled dates of the scheduled orders to cope flexibly with end-user change demands. For example, when you scheduled an order for suspending a subscription from April 1st, the status of the subscription will not be changed until April 1st. This allows any change to the subscription between March 1st and April 1st.

Q: What’s the difference between the orderDate, orderscheduledDate, and order action effective date?

A: TheorderDate is the date the user specifies when creating a new order in Zuora, the date normally records when the order is created. The scheduledDate can be any future date. For example, for Termed subscriptions, the scheduledDate can be within the current term or after the term end date of the current term.

The effective date is the date when the order action will become effective. For the following order actions: createSubscription, updateProduct, addproduct, removeProduct, termsAndConditions, renewSubscription, the effective date refers to the ContractEffectiveorServiceActivationdate of the order actions. Forsuspendresume,  and cancelSubscriptionorder actions, the effective date refers to the specified date when creating the order actions respectively, such as suspendSpecificDate, resumeSpecificDate, and cancellationEffectiveDate.

Q: Is there any rule to set the order action effective date when creating a scheduled order?

A: The ContractEffective or ServiceActivation of the order actions within a scheduled order must be earlier than the end date of the future term that the order  scheduledDate falls in. Requirements for suspend and resume order actions are listed as follows: 

  •  suspendPolicy and resumePolicy must be specified as SpecificDate, and

  • suspendSpecificDate and resumeSpecificDate should not be earlier than the order scheduledDate.

Q: When will a scheduled order be executed?

A: A scheduled order will not be executed until the order scheduledDate. Before a scheduled order is executed, the version of the inside subscription is not changed. 

Q: Can I change a scheduled order if my customer changes their mind?

A: Before a scheduled order is executed, the order (including the order scheduledDate) and the inside order actions can be updated. Before a scheduled order is executed, the order can be cancelled. After the scheduled order is completed, the order can also be deleted.

Q: How can I find out the existing scheduled order for a subscription?

A: You can use any of the following API operations to retrieve information about orders:

Scheduled orders can be in any of the following statuses: Scheduled, Executing, Completed, Failed, and Cancelled.

Q: When I create a scheduled order in a future term, will it renew the term immediately?

A: Creating scheduled orders in a future term will not renew the current term immediately. Term renewal uses the existing auto-renew mechanism. The only special case is when a subscription is suspended, and there is a scheduled order for resuming the subscription in the future term. For this case, when thescheduledDate of the order for resuming the subscription arrives, Zuora will renew the term automatically to cover the resume date, then execute the resume order.

Q: How do we make sure a scheduled order will complete successfully if some changes happen to a subscription prior to the scheduledDate?

A: Zuora will validate the changes to the subscription if there is any active scheduled order available for the subscription. Some changes to subscriptions in the scheduled orders might be rejected if the changes invalidate any existing scheduled orders for the subscription. The changes include: creating new orders, creating scheduled orders, deleting orders, cancelling scheduled orders, updating scheduled orders, completing pending orders, activating draft orders, setting subscription activate dates, and deleting subscriptions of specific versions.

Limitations on scheduled orders

The following limitations are listed for scheduled orders:

  • Saving scheduled orders as draft orders or pending orders is not supported
  • Previewing scheduled orders is not supported
  • No more than one scheduled order is created for a subscription per day
  • No more than five scheduled orders in the "Scheduled" status. The limitation does not apply to the scheduled orders that are transitted to the "Completed" status.
  • No more than 80,000 activate scheduled orders created per tenant
  • The changePlan order action is not supported. To replace a product rate plan or offer, you need to use addProduct and removeProduct instead.