Scheduled orders
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
toSpecificDate
. - Specify a
scheduledDate
. ThescheduledDate
refers to the scheduled date when the order is executed and completed.
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. To manage and access features from the self-service interface, see Manage Features.
For more information, see the following API operations:
- Create a scheduled order through Create an order.
- Update a scheduled order through Update an order.
- Retrieve scheduled orders through the following operations:
- Cancel a scheduled order through Cancel an order, no need to specify the
status
andschedulingOptions
fields. - Delete a scheduled order through Delete an order, no need to specify the
status
andschedulingOptions
fields.
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
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 |
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 history 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 |
O-00004 includes the Update Product order action. |
A subscription history version V2 is generated for O-00004. |
FAQs
You will understand scheduled orders from the following frequently asked questions:
Q: Do scheduled orders support for Evergreen
subscriptions?
A: Yes, 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
, order scheduledDate
, and order action effective date?
A: TheorderDate
is the date the user specifies when creating a new order in Zuora. The scheduledDate
is a future date (within the current term or after the term end date of the current term) when you want an order to become completed in Zuora. If you’re a Zuora Revenue customer and using orderDate
as the booking date when recognizing revenue, when creating a scheduled order, it’s recommended to ensure the orderDate
and scheduledDate
fall into the same accounting period.
The order action effective date is the date when the order action will become effective in Zuora. An order action within a scheduled order won’t take effect before the scheduledDate
. It’s recommended to set the order action effective date equal to or later than the order scheduledDate
. For the following order actions: createSubscription
, updateProduct
, addproduct
, removeProduct
, termsAndConditions
, renewSubscription
, the effective date refers to the ContractEffective
or ServiceActivation
date of the order actions. Forsuspend
, resume
, and cancelSubscription
order 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
andresumePolicy
must be specified asSpecificDate
. -
suspendSpecificDate
andresumeSpecificDate
should not be earlier than the orderscheduledDate
.
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 canceled. 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 resume the 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, canceling 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:
- The following charge models are not supported:
- Saving scheduled orders as draft orders or pending 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 active scheduled orders are created per tenant per day.
- More than one subscription is not supported within one scheduled order.
- The order line item is not supported in scheduled orders.