Update an order

PUT

/v1/orders/:orderNumber

PUT

/v1/orders/:orderNumber

import requests
url = "https://rest.test.zuora.com/v1/orders/orderNumber"
payload = {
    "orderDate": "2024-11-11",
    "existingAccountNumber": "A00000097",
    "subscriptions": [{ "orderActions": [
                {
                    "type": "CreateSubscription",
                    "createSubscription": {
                        "notes": "Notes about the subscription",
                        "terms": {
                            "initialTerm": {
                                "termType": "TERMED",
                                "period": 12,
                                "periodType": "Month",
                                "startDate": "2024-11-10"
                            },
                            "renewalSetting": "RENEW_WITH_SPECIFIC_TERM",
                            "renewalTerms": [
                                {
                                    "period": 6,
                                    "periodType": "Month"
                                }
                            ]
                        }
                    }
                }
            ] }]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.json())

{
  "success": true,
  "accountNumber": "A00000097",
  "orderNumber": "O-00000758",
  "status": "Draft"
}

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.

Authentication

AuthorizationBearer

Use Bearer {{token}} in the Authorization header for authentication.

Path parameters

orderNumberstringRequiredformat: "string"

Order number of a order in which you are to update.

Headers

Content-EncodingstringOptional

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-Org-IdsstringOptional

Comma separated IDs. If you have Zuora Multi-Org 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.

Request

This endpoint expects an object.

orderDatedateRequired

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.

categoryenumOptionalDefaults to NewSales

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

Allowed values:

commitmentslist of objectsOptional

A list of commitments you want to create or update.

Variant:

customFieldsmap from strings to anyOptional

Container for custom fields of an Order object.

descriptionstringOptional<=500 characters

A description of the order.

existingAccountIdstringOptional

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.

existingAccountNumberstringOptional<=70 characters

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.

orderNumberstringOptional<=100 characters

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.

processingOptionsobjectOptional

The container for billing processing options and payment processing options.

Note:

This field is not supported in draft orders.
When you use the “Create an order” 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. In this case, neither the invoice will be generated, nor the subscription nor the account will be created.
When you use the “Create an order” operation to cancel a subscription with refund and writeOff, if the refund or writeOff fails, cancelSubscription, runBilling, and collectPayment still can succeed.
When you use the “Create an order” operation, the collectPayment and refund fields cannot be set to true simultaneously. Otherwise, the order will not be proceeded.

reasonCodestringOptional<=255 characters

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

schedulingOptionsobjectOptional

Information of scheduled order.

statusenumOptional

The status of the order. The default value is Completed. The following values are supported:

Draft: The order is in draft status.
Pending: The order is in pending status.
Completed: The order is in completed status.
Scheduled: The order is in scheduled status and it is only valid if the Scheduled Orders feature is enabled.
Executing: The scheduled order is executed by a scheduler and it is only valid if the Scheduled Orders feature is enabled.
Failed: The scheduled order has failed.

Note: If you have the Pending Subscription Processing feature turned on and want to update a completed order with an active subscription with pending charges, you must specify Completed in this field because the default order status is Pending for this scenario.

subscriptionslist of objectsOptional

Each item includes a set of order actions, which will be applied to the same base subscription. When you create an order that involves multiple subscriptions, these subscriptions can have different invoice owner accounts or subscription owner accounts.

Response headers

Content-EncodingstringOptional

This header is returned if you specify the Accept-Encoding: gzip request header and the response contains over 1000 bytes of data.

Note that only the following MIME types support gzipped responses:

application/json
application/xml
text/html
text/csv
text/plain

RateLimit-LimitstringOptional

The request limit quota for the time window closest to exhaustion. See rate limits for more information.

RateLimit-Remainingdouble

The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.

RateLimit-Resetdouble

The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.

Zuora-Request-IdstringOptional

The Zuora internal identifier of the API call. You cannot control the value of this header.

Zuora-Track-IdstringOptional

A custom identifier for tracing the API call. If you specified a tracing identifier in the request headers, Zuora returns the same tracing identifier. Otherwise, Zuora does not set this header.

Concurrency-Limit-TypestringOptional

The type of the concurrency limit, which can be Default, High-volume transactions, or Object Query.

For more information, see Concurrent request limits.

Concurrency-Limit-Limitinteger

The total number of the permitted concurrent requests.

For more information, see Concurrent request limits.

Concurrency-Limit-Remaininginteger

The remaining number of the permitted concurrent requests.

For more information, see Concurrent request limits.

Response

processIdstringOptional

The ID of the process that handles the operation.

reasonslist of objectsOptional

The container of the error code and message. This field is available only if the success field is false.

requestIdstringOptionalformat: "uuid"=36 characters

Unique identifier of the request.

successbooleanOptional

Indicates whether the call succeeded.

accountIdstringOptional<=32 characters

The account ID for the order. This field is returned instead of the accountNumber field if the returnIds query parameter is set to true.

accountNumberstringOptional<=50 characters

The account number for the order.

creditMemoIdslist of stringsOptional

An array of the credit memo IDs generated in this order request. The credit memo is only available if you have the Invoice Settlement feature enabled. This field is returned instead of the creditMemoNumbers field if the returnIds query parameter is set to true.

creditMemoNumberslist of stringsOptional

An array of the credit memo numbers generated in this order request. The credit memo is only available if you have the Invoice Settlement feature enabled.

invoiceIdslist of stringsOptional

An array of the invoice IDs generated in this order request. Normally it includes one invoice ID only, but can include multiple items when a subscription was tagged as invoice separately. This field is returned instead of the invoiceNumbers field if the returnIds query parameter is set to true.

invoiceNumberslist of stringsOptional

An array of the invoice numbers generated in this order request. Normally it includes one invoice number only, but can include multiple items when a subscription was tagged as invoice separately.

orderIdstringOptional<=32 characters

The ID of the order created. This field is returned instead of the orderNumber field if the returnIds query parameter is set to true.

orderNumberstringOptional<=100 characters

The order number of the order created.

paidAmountstringOptional9-22 characters

The total amount collected in this order request.

paymentIdstringOptional<=32 characters

The payment Id that is collected in this order request. This field is returned instead of the paymentNumber field if the returnIds query parameter is set to true.

paymentNumberstringOptional<=32 characters

The payment number that is collected in this order request.

rampslist of objectsOptional

Note: This field is only available if you have the Ramps feature enabled. The Orders feature must be enabled before you can access the Ramps feature. The Ramps feature is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see Zuora Editions for pricing information coming October 2020. The ramp definitions created by this order request.

refundslist of objectsOptional

statusenumOptional

Status of the order. Pending is only applicable for an order that contains a CreateSubscription order action.

Allowed values:

subscriptionIdslist of stringsOptional

Container for the subscription IDs of the subscriptions in an order. This field is returned if the returnIds query parameter is set to true.

subscriptionOwnerIdstringOptional

Subscription owner account ID of the subscription.

subscriptionOwnerNumberstringOptional

Subscription owner account number of the subscription.

subscriptionslist of objectsOptional

This field is available only if you are on the latest Zuora API minor version, or you set the Zuora-Version request header to 223.0 or a later available version.

writeOfflist of objectsOptional

commitmentsobjectOptional

The Commitment object in the "Create an order" or "Update an order" response.

Errors

4XX

Client Request Error

500

Internal Server Error