# Orders Orders are contractual agreements between merchants and customers. You can create multiple subscriptions and subscription amendments at once in a single order. All the operations on subscriptions in orders are done by order actions. You can also create order line items to support your non-subscription based business models. Zuora calculates order delta metrics when orders take place. You can retrieve order delta metrics and measure billed and unbilled amounts by order. For more information about Orders, see Overview Of Orders. To learn how orders interacts with billing accounts, subscriptions, and product catalog, see [Zuora object model](https://developer.zuora.com/v1-api-reference/object-model/). ## Preview an order - [POST /v1/orders/preview](https://developer.zuora.com/v1-api-reference/api/orders/post_previeworder.md): Notes: - This operation is only available if you have the Orders feature enabled. If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing functions for subscription and billing management and the new features on Zuora Billing. - The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. - You cannot preview enhanced discounts and usage charges. - You can skip the accounting period validation to avoid backdated subscription cancellation caused order preview failure. To skip the accounting period validation, submit a request at Zuora Global Support. Retrieves the preview of the charge metrics and invoice items of a specified order. Preview for subscriptions and order line items are both supported. This operation is only an order preview and no order is created. You can also use this operation to preview billing for a standalone order. For more information, see Preview billing for a standalone order. #### Billing preview behavior regarding draft invoices By default, the billing preview behavior regarding draft invoices is as below: - When you preview billing for your order and the order contains subscriptions only, the draft invoices are excluded. - When you preview billing for your order and the order contains order line items only, the draft invoices are included. - When you preview billing for an order that contains both subscriptions order line items, the draft invoices are included for both subscriptions and order line items. However, if you want to always exclude the draft invoices in billing preview, submit a request at Zuora Global Support. #### Limits on Orders API The limit of orders allowed on a subscription is 1000. The limit of order line items allowed in an order is 100. Zuora has the following limits on the Orders synchronous API to prevent performance degradation: - Up to 50 subscriptions are allowed in a single Create an order or Preview an order operation call. - Up to 50 order actions are allowed in a single Create an order or Preview an order operation call. - Up to 50 order actions are allowed on a single subscription in a Create an order or Preview an order operation call. If you have an Order that exceeds any limits of the above, Zuora recommends you use the following asynchronous API operations: - Create an order asynchronously - Preview an order asynchronously - Retrieve the status and response of a job for checking the status of the asynchronous API operations Zuora has the following limits on the Orders asynchronous API operations to prevent performance degradation: - Up to 300 subscriptions are allowed in a single Create an order asynchronously or Preview an order asynchronously operation call. - Up to 300 order actions are allowed in a single Create an order asynchronously or Preview an order asynchronously operation call. - Up to 300 order actions are allowed on a single subscription\ in a Create an order asynchronously or Preview an order asynchronously operation call. ## Preview an order asynchronously - [POST /v1/async/orders/preview](https://developer.zuora.com/v1-api-reference/api/orders/post_previeworderasynchronously.md): Notes: - This operation is only available if you have the Orders feature enabled. Orders is now generally available as of Zuora Billing Release 284 (August 2020). If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing functions for subscription and billing management and the new features on Zuora Billing. - The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. - You cannot preview enhanced discounts and usage charges. In the case where a normal "Preview an order" operation call will time out, use this operation instead to preview an order asynchronously. A job will be previewing the order in the back end; the job ID will be returned for tracking the job status and result. #### Billing preview behavior regarding draft invoices By default, the billing preview behavior regarding draft invoices is as below: * When you preview billing for your order and the order contains subscriptions only, the draft invoices are excluded. * When you preview billing for your order and the order contains order line items only, the draft invoices are included. * When you preview billing for an order that contains both subscriptions order line items, the draft invoices are included for both subscriptions and order line items. However, if you want to always exclude the draft invoices in billing preview, submit a request at Zuora Global Support. #### Limits on Orders API The limit of orders allowed on a subscription is 1000. The limit of order line items allowed in an order is 100. Zuora has the following limits on the Orders synchronous API to prevent performance degradation: * Up to 50 subscriptions are allowed in a single Create an order or Preview an order operation call. * Up to 50 order actions are allowed in a single Create an order or Preview an order operation call. * Up to 50 order actions are allowed on a single subscription in a Create an order or Preview an order operation call. If you have an Order that exceeds any limits of the above, Zuora recommends you use the following asynchronous API operations: * Create an order asynchronously * Preview an order asynchronously * Retrieve the status and response of a job for checking the status of the asynchronous API operations Zuora has the following limits on the Orders asynchronous API operations to prevent performance degradation: * Up to 300 subscriptions are allowed in a single Create an order asynchronously or Preview an order asynchronously operation call. * Up to 300 order actions are allowed in a single Create an order asynchronously or Preview an order asynchronously operation call. * Up to 300 order actions are allowed on a single subscription in a Create an order asynchronously or Preview an order asynchronously operation call. ## List orders - [GET /v1/orders](https://developer.zuora.com/v1-api-reference/api/orders/get_allorders.md): Note: This feature is only available if you have the Order Metrics feature enabled. As of Zuora Billing Release 284, Orders is generally available and the Order Metrics feature is no longer available as a standalone feature. If you are an existing Subscribe and Amend customer and want Order Metrics only, you must turn on Orders Harmonization. You can still keep the existing Subscribe and Amend API integrations to create and manage subscriptions. Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. Retrieves information about all orders in your tenant. You can set the status query parameter to an order status to retrieve orders in that order status. If you do not set a value for this query parameter, the query parameter has a default value all, and orders of all statuses are returned. By default, it returns the first page of the orders. ## Create an order - [POST /v1/orders](https://developer.zuora.com/v1-api-reference/api/orders/post_order.md): Note: This operation is only available if you have the Orders feature enabled. If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing functions for subscription and billing management and the new features on Zuora Billing. Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. You can use this operation to create subscriptions and make changes to subscriptions by creating orders. You can also use this operation to create order line items by creating orders. The following tutorials demonstrate how to use this operation: * Create a Subscription * Add a Product to a Subscription * Create a Ramp Deal * Add a Product Mid-Interval Update on a Ramp Deal * Add a Product in a Ramp Deal * Change the Terms and Conditions of a Ramp Deal * Change the Owner of a Subscription * Change the Terms and Conditions of a Subscription * Renew a Subscription * Renew a Subscription and Upgrade a Product * Replace a Product in a Subscription * Update a Product in a Subscription * Cancel a Subscription * Remove a Product from a Subscription * Create sales order line items * Associate order line items with new subscriptions * Return order line items You can also use this operation to create orders and save the orders as Scheduled Orders. In addition, you can use this operation to place a standalone order to subscribe without pre-defining a product catalog in Zuora Billing. For more information, see Create a subscription using a standalone order. Note: If you received a timeout error message when creating an order, the call is still running in the backend and the order will be created. The limit of orders allowed on a subscription is 1000. The limit of order line items allowed in an order is 100. Zuora has the following limits on the Orders synchronous API to prevent performance degradation: * Up to 50 subscriptions are allowed in a single Create an order or Preview an order operation call. * Up to 50 order actions are allowed in a single Create an order or Preview an order operation call. * Up to 50 order actions are allowed on a single subscription in a Create an order or Preview an order operation call. If you have an Order that exceeds any limits of the above, Zuora recommends you use the following asynchronous API operations: * Create an order asynchronously * Preview an order asynchronously * Retrieve the status and response of a job for checking the status of the asynchronous API operations Zuora has the following limits on the Orders asynchronous API operations to prevent performance degradation: * Up to 300 subscriptions are allowed in a single Create an order asynchronously or Preview an order asynchronously operation call. * Up to 300 order actions are allowed in a single Create an order asynchronously or Preview an order asynchronously operation call. * Up to 300 order actions are allowed on a single subscription in a Create an order asynchronously or Preview an order asynchronously operation call. Note: When you are to suspend a subcription (via the suspend order action), if in the same "Create an order" call you are to perform other subsequent order actions on the supscription to suspend, you must first resume the subscription (via a resume order action). Note: When using this operation to create an account, create a subscription, run billing, and collect payment in a single call, if any error occurs during the call, such as a payment processing failure and a tax engine failure, then all the other steps will be rolled back. This means that the invoice will not be generated, the subscription will not be created, and the account will not be created. Note: The characters #, ?, and / are not allowed in the Orders operations. ## Create an order asynchronously - [POST /v1/async/orders](https://developer.zuora.com/v1-api-reference/api/orders/post_createorderasynchronously.md): Note: This operation is only available if you have the Orders feature enabled. If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing functions for subscription and billing management and the new features on Zuora Billing. Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. In the case where a normal "Create an order" operation call will time out, use this operation instead to create an order asynchronously. A job will be creating the order in the back end; the job ID will be returned for tracking the job status and result. Note that this operation doesn't support auto-refund and invoice write-off during subscription cancellation. Use the "Create an order" operation instead. The limit of orders allowed on a subscription is 1000. The limit of order line items allowed in an order is 100. Zuora has the following limits on the Orders synchronous API to prevent performance degradation: * Up to 50 subscriptions are allowed in a single Create an order or Preview an order operation call. * Up to 50 order actions are allowed in a single Create an order or Preview an order operation call. * Up to 50 order actions are allowed on a single subscription in a Create an order or Preview an order operation call. If you have an Order that exceeds any limits of the above, Zuora recommends you use the following asynchronous API operations: * Create an order asynchronously * Preview an order asynchronously * Retrieve the status and response of a job for checking the status of the asynchronous API operations Zuora has the following limits on the Orders asynchronous API operations to prevent performance degradation: * Up to 300 subscriptions are allowed in a single Create an order asynchronously or Preview an order asynchronously operation call. * Up to 300 order actions are allowed in a single Create an order asynchronously or Preview an order asynchronously operation call. * Up to 300 order actions are allowed on a single subscription in a Create an order asynchronously or Preview an order asynchronously operation call. ## Delete an order - [DELETE /v1/orders/{orderNumber}](https://developer.zuora.com/v1-api-reference/api/orders/delete_order.md): Note: This operation is only available if you have the Orders feature enabled. If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing functions for subscription and billing management and the new features on Zuora Billing. Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. Deletes a specified order. * All the subscriptions changed by this order are deleted. After the deletion, the subscriptions are rolled back to the previous version. * All the order line items created in this order are deleted. You are not allowed to delete an order in the following situations: - The charges that are affected by this order are invoiced. - The order is reverted and in the Reverted status. ## Retrieve an order - [GET /v1/orders/{orderNumber}](https://developer.zuora.com/v1-api-reference/api/orders/get_order.md): Note: This feature is only available if you have the Order Metrics feature enabled. As of Zuora Billing Release 284, Orders is generally available and the Order Metrics feature is no longer available as a standalone feature. If you are an existing Subscribe and Amend customer and want Order Metrics only, you must turn on Orders Harmonization. You can still keep the existing Subscribe and Amend API integrations to create and manage subscriptions. Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. Retrieves the detailed information about a specified order. ## Update an order - [PUT /v1/orders/{orderNumber}](https://developer.zuora.com/v1-api-reference/api/orders/put_order.md): Notes: - This operation is only available if you have the Orders feature enabled. If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing functions for subscription and billing management and the new features on Zuora Billing. - Update an order is only valid for draft or scheduled orders. - This operation doesn't support auto-refund and invoice write-off during subscription cancellation. Use the "Create an order" operation instead. - You must provide full payload when using the "Update an order" operation. That is, if you want to edit one order action, you need to provide all other order actions in the payload. Otherwise, the other order actions will be removed. ## Delete an order asynchronously - [DELETE /v1/async/orders/{orderNumber}](https://developer.zuora.com/v1-api-reference/api/orders/deleteorderasynchronously.md): Note: This operation is only available if you have the Orders feature enabled. If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing\ functions for subscription and billing management and the new features on Zuora Billing. Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who\ onboard on Orders will have the Order Line Items feature enabled by default. Deletes a specified order. All the subscriptions changed by this order are deleted. After the deletion, the subscriptions are rolled back to the previous version. All the order line items created in this order are deleted. You are not allowed to delete an order in the following situations: - The charges that are affected by this order are invoiced. - The order is reverted and in the Reverted status. ## Retrieve the status and response of a job - [GET /v1/async-jobs/{jobId}](https://developer.zuora.com/v1-api-reference/api/orders/get_jobstatusandresponse.md): Note: This operation is only available if you have the Orders feature enabled. If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing functions for subscription and billing management and the new features on Zuora Billing. Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. Get the status and response of an asynchronous job. Currently, an asynchronous job created by "Create an order asynchronously" or "Preview an order asynchronously" is supported. ## List orders of a subscription owner - [GET /v1/orders/subscriptionOwner/{accountNumber}](https://developer.zuora.com/v1-api-reference/api/orders/get_ordersbysubscriptionowner.md): Note: This feature is only available if you have the Order Metrics feature enabled. As of Zuora Billing Release 284, Orders is generally available and the Order Metrics feature is no longer available as a standalone feature. If you are an existing Subscribe and Amend customer and want Order Metrics only, you must turn on Orders Harmonization. You can still keep the existing Subscribe and Amend API integrations to create and manage subscriptions. Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. Retrieves the detailed information about all orders for a specified subscription owner. Any orders containing the changes on the subscriptions owned by this account are returned. Note: You cannot retrieve detailed information about draft orders or scheduled orders through this operation. ## List orders by subscription number - [GET /v1/orders/subscription/{subscriptionNumber}](https://developer.zuora.com/v1-api-reference/api/orders/get_ordersbysubscriptionnumber.md): Note: This feature is only available if you have the Order Metrics feature enabled. As of Zuora Billing Release 284, Orders is generally available and the Order Metrics feature is no longer available as a standalone feature. If you are an existing Subscribe and Amend customer and want Order Metrics only, you must turn on Orders Harmonization. You can still keep the existing Subscribe and Amend API integrations to create and manage subscriptions. Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. Retrieves the detailed information about all orders for a specified subscription. You can set the status query parameter to an order status to retrieve orders in that order status. If you do not set a value for this query parameter, the query parameter has a default value all, and orders of all statuses are returned. ## List orders of an invoice owner - [GET /v1/orders/invoiceOwner/{accountNumber}](https://developer.zuora.com/v1-api-reference/api/orders/get_ordersbyinvoiceowner.md): Note: This feature is only available if you have the Order Metrics feature enabled. As of Zuora Billing Release 284, Orders is generally available and the Order Metrics feature is no longer available as a standalone feature. If you are an existing Subscribe and Amend customer and want Order Metrics only, you must turn on Orders Harmonization. You can still keep the existing Subscribe and Amend API integrations to create and manage subscriptions. Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. Retrieves the detailed information about all orders for a specified invoice owner. You can set the status query parameter to an order status to retrieve orders in that order status. If you do not set a value for this query parameter, the query parameter has a default value all, and orders of all statuses are returned. ## Update order custom fields - [PUT /v1/orders/{orderNumber}/customFields](https://developer.zuora.com/v1-api-reference/api/orders/put_updateordercustomfields.md): Note: This feature is only available if you have the Order Metrics feature enabled. As of Zuora Billing Release 284, Orders is generally available and the Order Metrics feature is no longer available as a standalone feature. If you are an existing Subscribe and Amend customer and want Order Metrics only, you must turn on Orders Harmonization. You can still keep the existing Subscribe and Amend API integrations to create and manage subscriptions. Note: To update the custom fields of an order line item, you must use the "Update an order line item" or "Update order line items" operation. Updates the custom fields of a specified order. ## Update subscription custom fields - [PUT /v1/subscriptions/{subscriptionNumber}/customFields](https://developer.zuora.com/v1-api-reference/api/orders/put_updatesubscriptioncustomfields.md): Note: This operation is only available if you have the Orders feature enabled. If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing functions for subscription and billing management and the new features on Zuora Billing. Updates the custom fields of a specified subscription. ## Update order action trigger dates - [PUT /v1/orders/{orderNumber}/triggerDates](https://developer.zuora.com/v1-api-reference/api/orders/put_ordertriggerdates.md): Note: This operation is only available if you have the Orders feature enabled. If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing functions for subscription and billing management and the new features on Zuora Billing. Updates the triggering dates for either of the following order actions: * CreateSubscription * AddProduct * UpdateProduct * RemoveProduct * RenewSubscription * TermsAndConditions ## Activate an order - [PUT /v1/orders/{orderNumber}/activate](https://developer.zuora.com/v1-api-reference/api/orders/put_orderactivate.md): Note: This operation is only available if you have the Orders feature enabled. If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing functions for subscription and billing management and the new features on Zuora Billing. Activate order is only available for draft orders. ## Cancel an order - [PUT /v1/orders/{orderNumber}/cancel](https://developer.zuora.com/v1-api-reference/api/orders/put_ordercancel.md): Note: This operation is only available if you have the Orders feature enabled. If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing functions for subscription and billing management and the new features on Zuora Billing. Note: Cancellation is only valid for draft or scheduled orders. If the order is not in draft or scheduled status, the API returns an error. ## Revert an order - [POST /v1/orders/{orderNumber}/revert](https://developer.zuora.com/v1-api-reference/api/orders/revertorder.md): Reverts an order though this operation. Note: This operation is only available if you have the following features turned on: - Orders - Single Version Subscription For information on what orders can be reverted, see Revert orders. ## List pending orders by subscription number - [GET /v1/orders/subscription/{subscription-key}/pending](https://developer.zuora.com/v1-api-reference/api/orders/get_pendingordersbysubscriptionnumber.md): Note: This feature is only available if you have the Order Metrics feature enabled. As of Zuora Billing Release 284, Orders is generally available and the Order Metrics feature is no longer available as a standalone feature. If you are an existing Subscribe and Amend customer and want Order Metrics only, you must turn on Orders Harmonization. You can still keep the existing Subscribe and Amend API integrations to create and manage subscriptions. Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. Retrieves the detailed information about all pending orders for a specified subscription.