Sign in
Orders

Update an order

Notes:

  • This operation is only available if you have the Orders feature enabled. If you are an existing Zuora <a href="https://docs.zuora.com?resourceId=billing-subscribe-and-amend" target="_blank">Subscribe and Amend</a> customer, we recommend you enable <a href="https://docs.zuora.com?resourceId=billing-overview-orders" target="_blank">Orders Harmonization</a> to access the <a href="https://docs.zuora.com?resourceId=billing-overview-orders" target="_blank">Orders</a> feature. With Orders, you can access both existing functions for subscription and billing management and the <a href="https://docs.zuora.com?resourceId=billing-orders-harmonization" target="_blank">new features</a> 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.
put/v1/orders/{orderNumber}

Path parameters

orderNumberstring string required

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

Headers

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.

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.

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.

status'Draft' | 'Pending' | 'Completed' | 'Scheduled' | 'Executing' | 'Failed'

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.

Example request

{
  "existingAccountNumber": "A00000097",
  "orderDate": "2024-11-11",
  "subscriptions": [
    {
      "orderActions": [
        {
          "createSubscription": {
            "notes": "Notes about the subscription",
            "terms": {
              "renewalSetting": "RENEW_WITH_SPECIFIC_TERM",
              "initialTerm": {
                "startDate": "2024-11-10",
                "period": 12,
                "periodType": "Month",
                "termType": "TERMED"
              },
              "renewalTerms": [
                {
                  "period": 6,
                  "periodType": "Month"
                }
              ]
            }
          },
          "type": "CreateSubscription"
        }
      ]
    }
  ]
}

Response

OK

processIdstring

The ID of the process that handles the operation.

requestIdstring uuid

Unique identifier of the request.

successboolean

Indicates whether the call succeeded.

accountIdstring

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

accountNumberstring

The account number for the order.

creditMemoIdsstring[]

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.

creditMemoNumbersstring[]

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.

invoiceIdsstring[]

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.

invoiceNumbersstring[]

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.

orderIdstring

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

orderNumberstring

The order number of the order created.

paidAmountstring

The total amount collected in this order request.

paymentIdstring

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.

paymentNumberstring

The payment number that is collected in this order request.

status'Draft' | 'Pending' | 'Completed' | 'Scheduled'

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

subscriptionIdsstring[]

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

subscriptionOwnerIdstring

Subscription owner account ID of the subscription.

subscriptionOwnerNumberstring

Subscription owner account number of the subscription.

Example response

{
  "commitments": {
    "prepaymentType": "FullyPrepaid"
  }
}

Changes