Welcome to the Zuora REST API. To use the API, you'll need to be familiar with REST, as well as the following information. Take a moment to review this page before diving into the REST calls.
Few setup steps are required to use the Zuora REST API. No special software libraries or development tools are needed. Take a moment to set up an API user account. See Creating an API user.
Note that a user role does not have write access to Zuora REST services unless it has the API Write Access permission as described in those instructions.
Use the API user account only for API calls, and avoid using it to log into the Zuora UI. Logging into the UI enables a security feature that periodically expires the account's password, which may eventually cause authentication failures with the API.
There are three ways to authenticate:
connectionsresource with the following API user information:
The cookie authorizes the user to make calls to the REST API for the duration specified in Administration > Security Policies > Session timeout. The cookie expiration time is reset with this duration after every call to the REST API.
In the API reference material, we demonstrate the use of the apiAccessKeyId and apiSecretAccessKey in the CURL examples. Otherwise we generally assume that you are using the cookie.
The entityId and entityName parameters are only used for Zuora Multi-entity.
The entityId parameter specifies the Id of the entity that you want to access. The entityName parameter specifies the name of the entity that you want to access. Note that you must have permission to access the entity. You can get the entity Id and entity name through the REST GET Entities call.
You can specify either the entityId or entityName parameter in the authentication to access and view an entity.
See API User Authentication for more information.
The CORS mechanism enables REST API calls to Zuora to be made directly from your customer's browser, with all credit card and security information transmitted directly to Zuora. This minimizes your PCI compliance burden, allows you to implement advanced validation on your payment forms, and makes your payment forms look just like any other part of your website.
For security reasons, instead of using cookies, an API request via CORS uses tokens for authentication.
The token method of authentication is only designed for use with requests that must originate from your customer's browser; it should not be considered a replacement to the existing cookie authentication mechanism.
See Zuora CORS REST for details on how CORS works and how you can begin to implement customer calls to the Zuora REST APIs. See HMAC Signatures for details on the HMAC method that returns the authentication token.
The Zuora REST API is in version control. 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.
The major version number of the REST API appears in the REST URL. Currently, Zuora only supports the v1 major version. For example,
Zuora uses minor versions for 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.
The supported minor versions are not serial, see Zuora REST API Minor Version History for the fields and their supported minor versions. 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.
The following REST services are provided in Zuora.
|Service||Base URL for REST Endpoints|
|Production REST service||https://api.zuora.com/rest/v1|
|Sandbox REST service|| |
|Services REST service|| |
*xxx indicates the services environment number, e.g. the URL for services 445 is https://services445.zuora.com/apps/v1/
|Performance Test REST service||https://pt1-api.zuora.com/rest/v1/|
The production service provides access to your live user data. The sandbox environment is a good place to test your code without affecting real-world data. To use it, you must be provisioned with a sandbox tenant - your Zuora representative can help with this if needed.
The reference documentation for each API call shows the REST resource, method, and parameters that must be appended to the base URL to form a request.
The following is an example of a well-formed REST URL:
that includes a base URL and the following:
Requests and Responses
Most of the parameters and data accompanying your requests will be contained in the body of the HTTP request.
The Zuora REST API accepts JSON in the HTTP request body. No other data format (e.g., XML) is supported.
Use a third party client, such as Postman or Advanced REST Client to test the Zuora REST API.
You can test the Zuora REST API from the Zuora sandbox or production service. If connecting to the production service, bear in mind that you are working with your live production data, not sample data or test data.
Sooner or later it will probably be necessary to test some transactions that involve credit cards. For suggestions on how to handle this, see Going Live With Your Payment Gateway.
The HTTP response includes:
Responses and error codes are detailed on the Responses and errors page.
For variables in the body of a request or response, and for URL query parameters, we use camel case.
For parameters in the URL path of an API method, we use hyphenated lower case. If a data value (such as an account ID) is included in the path, its capitalization is not changed.
The following is an example of a well-formed request:
As a general rule, when asked to supply a "key" for an account or subscription (accountKey, account-key, subscriptionKey, subscription-key), you can provide either the actual ID or the number of the entity.
When retrieving information (using GET methods), the optional pageSize query parameter sets the maximum number of rows to return in a response. The maximum is 40; larger values are treated as 40. If this value is empty or invalid, pageSize typically defaults to 10.
The default value for the maximum number of rows retrieved can be overridden at the method level. Refer to the specific REST API reference article to get the pageSize value for the specific method.
If more rows are available, the response will include a nextPage element, which contains a URL for requesting the next page. If this value is not provided, no more rows are available. No "previous page" element is explicitly provided; to support backward paging, use the previous call(s).
For data items that are not paginated, the REST API supports arrays of up to 300 rows. Thus, for instance, repeated pagination can retrieve thousands of customer accounts, but within any account an array of no more than 300 rate plans is returned.
Each Zuora tenant has the following default concurrent request limits:
|Type||Description||Default Limit for Concurrent, Uncompleted Requests||Retry After|
|Total Request||Refers to UI, REST, and SOAP API requests processed under a tenant. |
Excluded from this policy
|Big Process Request|| |
Refers to database operation-heavy requests. The following lists the SOAP API calls that are handled as Big Process Requests and the objects they support.
|Big Data Request||Data transfers to or from Zuora, such as a usage upload or data source file download.||20|
Includes all of the following:
Subscribe and amend REST method calls:
Subscribe and amend SOAP calls:
Hosted Payment Method Pages:
Custom requests are not counted against the total number of requests allowed at any given time.
See Concurrent Request Limits for the information about the error codes and handling the error condition.
Responses and error codes are detailed on the Responses and errors page.