Sign in
Orders

Create an order asynchronously

Note: This operation is only available if you have the Orders feature enabled. If you are an existing Zuora <a href="ttps://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/subscribe-and-amend" target="_blank">Subscribe and Amend</a> customer, we recommend you enable <a href="https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders-harmonization" target="_blank">Orders Harmonization</a> to access the <a href="https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/orders/orders-introduction/overview-of-orders" target="_blank">Orders</a> 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:

If you have an Order that exceeds any limits of the above, Zuora recommends you use the following asynchronous API operations:

Zuora has the following limits on the Orders asynchronous API operations to prevent performance degradation:

post/v1/async/orders

Query parameters

returnIdsboolean

Specify whether to return IDs for the Get job status and response operation. If you set this query parameter to true, the corresponding IDs, which are associated with the numbers returned in this operation, can be returned in the "Get job status and response" response body.

Headers

Idempotency-Keystring

Specify a unique idempotency key if you want to perform an idempotent POST or PATCH request. Do not use this header in other request types.

With this header specified, the Zuora server can identify subsequent retries of the same request using this value, which prevents the same operation from being performed multiple times by accident.

Accept-Encodingstring

Include the Accept-Encoding: gzip header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response.

If specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a Content-Encoding header with the compression algorithm so that your client can decompress it.

Content-Encodingstring

Include the Content-Encoding: gzip header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload.

Zuora-Track-Idstring

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Zuora-Entity-Idsstring

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you should not set this header.

Zuora-Org-Idsstring

Comma separated IDs. If you have <a href="https://docs.zuora.com/en/zuora-platform/organization-and-entity-management/multi-org/overview-of-multi-org" target="_blank">Zuora Multi-Org</a> enabled, you can use this header to specify which orgs to perform the operation in. If you do not have Zuora Multi-Org enabled, you should not set this header.

The IDs must be a sub-set of the user's accessible orgs. If you specify an org that the user does not have access to, the operation fails. This header is important in Multi-Org (MO) setups because it defines the organization context under which the API should operate—mainly used for read access or data visibility filtering. If the header is not set, the operation is performed in scope of the user's accessible orgs.

Zuora-Versionstring

The minor API version.

For a list of available minor versions, see API upgrades.

Request body

category'NewSales' | 'Return'

Category of the order to indicate a product sale or return. Default value is NewSales.

customFieldsOrderObjectCustomFields

Container for custom fields of an Order object.

descriptionstring

A description of the order.

existingAccountIdstring

The account ID under which this order will be created. This field sets the default invoice owner account and subscription owner account for any new subscriptions in the order. To override these defaults for individual subscriptions, use the subscriptionOwnerAccountNumber and invoiceOwnerAccountNumber nested fields in the subscriptions field.

Note: You can specify either the existingAccountNumber or existingAccountId field, but not both.

existingAccountNumberstring

The account number under which this order will be created. This field sets the default invoice owner account and subscription owner account for any new subscriptions in the order. To override these defaults for individual subscriptions, use the subscriptionOwnerAccountNumber and invoiceOwnerAccountNumber nested fields in the subscriptions field.

externallyManagedBy'Amazon' | 'Apple' | 'Google' | 'Roku'

An enum field on the Subscription object to indicate the name of a third-party store. This field is used to represent subscriptions created through third-party stores.

orderDatestring date required

The date when the order is signed. All the order actions under this order will use this order date as the contract effective date if the contract effective date field is skipped or its value is left as null.

orderNumberstring

The order number of the new order. If not provided, system will auto-generate a number for this order.
Note: The characters #, ?, and / are not allowed in this field. Additionally, to ensure compatibility with the UI when viewing orders, use only the following special characters: _,-, ., ~, *, (, ), and '.

reasonCodestring

Values of reason code configured in Billing Settings > Configure Reason Codes through Zuora UI. Indicates the reason when a return order line item occurs.

Example request

{
  "existingAccountNumber": "A00000097",
  "orderDate": "2024-07-01",
  "subscriptions": [
    {
      "orderActions": [
        {
          "type": "CreateSubscription",
          "createSubscription": {
            "terms": {
              "initialTerm": {
                "period": 12,
                "periodType": "Month",
                "termType": "TERMED"
              },
              "renewalSetting": "RENEW_WITH_SPECIFIC_TERM",
              "renewalTerms": [
                {
                  "period": 12,
                  "periodType": "Month"
                }
              ]
            },
            "subscribeToRatePlans": [
              {
                "productRatePlanId": "8ad081dd9096ef9501909b40bb4e74a4"
              }
            ]
          }
        }
      ]
    }
  ]
}

Response

Accepted

jobIdstring UUID

The ID of an asynchronous job that will be returned for tracking the status and result of the job.

successboolean

Indicates whether the operation call succeeded.

Changes