Zuora

Introduction

Welcome to the REST API reference for the Zuora Billing, Payments, and Central Platform!

To learn about the common use cases of Zuora REST APIs, check out the REST API Tutorials.

The Zuora REST API provides a broad set of operations and resources that:

• Enable Web Storefront integration from your website.
• Support self-service subscriber sign-ups and account management.
• Process revenue schedules through custom revenue rule models.
• Enable manipulation of most objects in the Zuora Billing Object Model.

Want to share your opinion on how our API works for you? Tell us how you feel about using our API and what we can do to make it better.

Some of our older APIs are no longer recommended but still available, not affecting any existing integration. To find related API documentation, see Older API Reference.

Base URL

All API requests occur in a test or production environment. For details on Zuora’s environments, see Zuora Environments in the Knowledge Center. Each environment uses a different base URL. Select the appropriate base URL below that you need to use:

If you do not have a Zuora tenant, go to https://www.zuora.com/resource/zuora-test-drive and sign up for a Test Drive.

Error Handling

If a request to Zuora Billing REST API with an endpoint starting with /v1 (except Actions and CRUD operations) fails, the response will contain an eight-digit error code with a corresponding error message to indicate the details of the error.

The following code snippet is a sample error response that contains an error code and message pair:

 {
"success": false,
"processId": "CBCFED6580B4E076",
"reasons": [
{
"code": 53100320,
"message": "'termType' value should be one of: TERMED, EVERGREEN"
}
]
}

The success field indicates whether the API request has succeeded. The processId field is a Zuora internal ID that you can provide to Zuora Global Support for troubleshooting purposes.

The reasons field contains the actual error code and message pair. The error code begins with 5 or 6 means that you encountered a certain issue that is specific to a REST API resource in Zuora Billing, Payments, and Central Platform. For example, 53100320 indicates that an invalid value is specified for the termType field of the subscription object.

The error code beginning with 9 usually indicates that an authentication-related issue occurred, and it can also indicate other unexpected errors depending on different cases. For example, 90000011 indicates that an invalid credential is provided in the request header.

When troubleshooting the error, you can divide the error code into two components: REST API resource code and error category code. See the following Zuora error code sample:

Note: Zuora determines resource codes based on the request payload. Therefore, if GET and DELETE requests that do not contain payloads fail, you will get 500000 as the resource code, which indicates an unknown object and an unknown field. The error category code of these requests is valid and follows the rules described in the Error Category Codes section. In such case, you can refer to the returned error message to troubleshoot.

REST API Resource Codes

The 6-digit resource code indicates the REST API resource, typically a field of a Zuora object, on which the issue occurs. In the preceding example, 531003 refers to the termType field of the subscription object.

The value range for all REST API resource codes is from 500000 to 679999. See Resource Codes in the Knowledge Center for a full list of resource codes.

Error Category Codes

The 2-digit error category code identifies the type of error, for example, resource not found or missing required field.

The following table describes all error categories and the corresponding resolution:

API Versions

The Zuora REST API are version controlled. Versioning ensures that Zuora REST API changes are backward compatible. Zuora uses a major and minor version nomenclature to manage changes. By specifying a version in a REST request, you can get expected responses regardless of future changes to the API.

Major Version

The major version number of the REST API appears in the REST URL. In this API reference, only the v1 major version is available. For example, POST https://rest.zuora.com/v1/subscriptions.

Minor Version

Zuora uses minor versions for the REST API to control small changes. For example, a field in a REST method is deprecated and a new field is used to replace it.

Some fields in the REST methods are supported as of minor versions. If a field is not noted with a minor version, this field is available for all minor versions. If a field is noted with a minor version, this field is in version control. You must specify the supported minor version in the request header to process without an error.

If a field is in version control, it is either with a minimum minor version or a maximum minor version, or both of them. You can only use this field with the minor version between the minimum and the maximum minor versions. For example, the invoiceCollect field in the POST Subscription method is in version control and its maximum minor version is 189.0. You can only use this field with the minor version 189.0 or earlier.

If you specify a version number in the request header that is not supported, Zuora will use the minimum minor version of the REST API. In our REST API documentation, if a field or feature requires a minor version number, we note that in the field description.

You only need to specify the version number when you use the fields require a minor version. To specify the minor version, set the zuora-version parameter to the minor version number in the request header for the request call. For example, the collect field is in 196.0 minor version. If you want to use this field for the POST Subscription method, set the zuora-version parameter to 196.0 in the request header. The zuora-version parameter is case sensitive.

For all the REST API fields, by default, if the minor version is not specified in the request header, Zuora will use the minimum minor version of the REST API to avoid breaking your integration.

Minor Version History

The supported minor versions are not consecutive. You can use the following versions to override the default version (186.0):

• 187.0
• 188.0
• 189.0
• 196.0
• 206.0
• 207.0
• 211.0
• 214.0
• 215.0
• 216.0
• 223.0
• 224.0
• 230.0
• 239.0
• 256.0
• 257.0
• 309.0
• 314.0
• 315.0
• 329.0
• 330.0
• 336.0
• 337.0
• 338.0
• 341.0

If you set the zuora-version header to a version excluded from the preceding list, the corresponding API request is processed as you use the default version, 186.0.

The following table lists the supported versions and the fields that have a Zuora REST API minor version.

Version 207.0 and Later

The response structure of the Preview Subscription and Update Subscription methods are changed. The following invoice related response fields are moved to the invoice container:

• amount
• amountWithoutTax
• taxAmount
• invoiceItems
• targetDate
• chargeMetrics

API Names for Zuora Objects

For information about the Zuora business object model, see Zuora Business Object Model.

You can use the Describe operation to list the fields of each Zuora object that is available in your tenant. When you call the operation, you must specify the API name of the Zuora object.

The following table provides the API name of each Zuora object:

Operations