Knowledge Center

Knowledge Center > API > REST API > REST API Basics

REST API Basics

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.

Set up an API User Account 

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.

Authentication

There are three ways to authenticate:

  • Obtain an authorization cookie by calling the REST connections resource with the following API user information:
    • ID
    • password
    • entity Id or entity name (Only for Zuora Multi-entity. See "Entity Id and Entity Name" below for more 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.

  • Include the following parameters in the request header, which re-authenticates the user with each request:
    • apiAccessKeyId
    • apiSecretAccessKey
    • entityId or entityName (Only for Zuora Multi-entity. See "Entity Id and Entity Name" below for more information.)
  • For CORS-enabled APIs only: Include a 'single-use' token in the request header, which re-authenticates the user with each request. See below for more details.

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.

Entity Id and Entity Name

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.

  • If both entityId and entityName are specified in the authentication, an error occurs. 
  • If neither entityId nor entityName is specified in the authentication, you will log in to the entity in which your user account is created. 

See API User Authentication for more information.

Token Authentication for CORS-Enabled APIs

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.

Zuora REST API Versions

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.

Major Version

The major version number of the REST API appears in the REST URL. Currently, Zuora only supports the v1 major version. For example, POST https://api.zuora.com/rest/v1/subscriptions.

Minor Version

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. 

URLS and Endpoints

BASE URL for REST Endpoints

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

https://apisandbox-api.zuora.com/rest/v1

Services REST service

https://servicesxxx*.zuora.com/apps/v1/ 

*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.

REST URLs

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:

https://api.zuora.com/rest/v1/transactions/payments/accounts/A00000001?pageSize=40

 that includes a base URL and the following:

  • Resource and associated method: rest/v1/transactions/payments/accounts
  • Path parameter, the account key: A00000001
  • Query parameter: pageSize

Requests and Responses

HTTP Request Body

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.

Testing a Request

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.

Testing with Credit Cards

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.

HTTP Responses

The HTTP response includes:

  • an HTTP status in the 200 range for successful HTTP transactions, or else an HTTP error status
  • a response body that contains data in JSON format:
    • your requested data if successful
    • an error code and message if there is an application error

Responses and error codes are detailed on the Responses and errors page.

Variable Names

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:

https://api.zuora.com/rest/v1/payment-methods/credit-cards/accounts/AbCd1234?pageSize=40

Account and Subscription IDs

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.

Pagination

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).

Array Size

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.

Concurrent Request Limits

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.
  • API calls (REST and SOAP)
    • Create
    • Update
    • Delete 
    • Generate
    • Query
  • UI requests (all - including Big Data Requests, and Big Process Requests)
  • Zuora for Salesforce
    • Zuora 360 Order Builder (includes APEX wrappers for SOAP APIs)

Excluded from this policy

  • Login API calls (REST and SOAP) 
  • UI login requests
  • Zuora for Salesforce
    • 360 Sync
    • Zuora Quotes
  • Custom requests
40 120 seconds
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.

create()

invoice

generate()

invoice

queryMore()

Account

InvoiceItem

PaymentTransactionLog

RatePlan

RatePlanCharge

RatePlanChargeTier

Subscription

query()

Account

Invoice

InvoicePayment

Payment

PaymentTransactionLog

RatePlan

RatePlanCharge

Subscription

Usage

20
Big Data Request Data transfers to or from Zuora, such as a usage upload or data source file download. 20

Custom

Includes all of the following:

Subscribe and amend REST method calls:

Subscribe and amend SOAP calls:

  • Amend
  • Subscribe
  • Subscribe with existing account

Hosted Payment Method Pages:

Custom requests are not counted against the total number of requests allowed at any given time. 

200

 

See Concurrent Request Limits for the information about the error codes and handling the error condition.

Error Handling

Responses and error codes are detailed on the Responses and errors page.

Last modified
18:00, 6 Dec 2016

Tags

Classifications

(not set)