REST API Guides Overview


Note: This set of guides is based on the REST APIs of Zuora. We also offer a Zuora SDK for Java that allows you to perform common use cases in a programmable way. See Java SDK Quickstart Tutorial to learn more.


Through this set of guides, we attempt to demonstrate common use cases of Zuora Billing REST APIs. The sequence of the guides indicates a typical but loose order that these use cases would occur.

Tell us how we can improve the API guides by clicking the "Feedback" button on the right and completing the anonymous feedback form.

This set of guides assume that you have the following systems and configurations.

  • You have a self-service portal that is used by end subscribers for purchasing and managing products and services.
    This is not a hard requirement. If you do not have a self-service portal, most of the use cases still apply.
  • The Orders feature is enabled on your Zuora tenant. If this feature is enabled on your tenant, you can see Orders under Customers in the left navigation panel in Zuora UI.
    To have access to this feature, submit a request at Zuora Global Support .
  • The Invoice Settlement feature is enabled on your Zuora tenant. If this feature is enabled on your tenant, you can see Credit and Debit Memos under Billing in the left navigation panel in Zuora UI.
    To have access to this feature, submit a request at Zuora Global Support .
  • The Event Framework and Notifications feature is enabled on your Zuora tenant.
  • You have defined your product catalog in Zuora.
  • You have set up a payment gateway instance on your Zuora tenant.

To learn about product catalogs in Zuora and how to define your catalog, refer to these two Knowledge Center articles:

Base URLs

The base URLs for different Zuora environments are different. You can use environment-based variables to manage base URLs and credentials for different Zuora environments.

In code examples, we use the base URL of the US API Sandbox environment. When running your API operations, you need to replace this base URL (https://rest.apisandbox.zuora.com) with the actual base URL.

Tenant Base URL for REST endpoint
US Cloud 1 Production https://rest.na.zuora.com
US Cloud 1 API Sandbox https://rest.sandbox.na.zuora.com
US Cloud 2 Production https://rest.zuora.com
US Cloud 2 API Sandbox https://rest.apisandbox.zuora.com
US Central Sandbox https://rest.test.zuora.com
US Performance Test https://rest.pt1.zuora.com
US Production Copy Submit a request at Zuora Global Support to enable the Zuora REST API in your tenant and obtain the base URL for REST endpoints. See REST endpoint base URL of Production Copy (Service) Environment for existing and new customers for more information.
EU Production https://rest.eu.zuora.com
EU Sandbox https://rest.sandbox.eu.zuora.com
EU Central Sandbox https://rest.test.eu.zuora.com

Authentication

Zuora recommends that you use OAuth to authenticate to the Zuora REST API.

  1. Create a dedicated user for making API calls. See Create an API User for details.
    This step must be performed by a Zuora administrator of your organization and the user should be connected to an internal email address.
  2. Create an OAuth client for the user. This step must be performed by an administrator.
    1. In Zuora, navigate to Settings > Administration > Manage Users , and click the user name (in hypertext) that is created in step 1.
    2. In the New OAuth Client section on the user profile page, enter a client name, and click create . A new window will open showing the client ID and client secret.
    Create a new OAuth client
    Create a new OAuth client
    Client ID and secret are generated
    Client ID and secret are generated
    1. Note down the client ID and client secret. You’ll need them in step 3. This is a one-time process. See Create an Oauth Client for a User for details.
  3. Generate a token. Each token is valid for an hour. If it expires, you need to perform this step again.
    You need to make a call using the Generate an Oauth token operation. The bearer token will be included in the response. For the operation, you need to include these parameters.
    • client_id : This parameter is obtained in step 2.
    • client_secret : This parameter is obtained in step 2.
    • grant_type : It must be set to client _ credentials.

    After you obtain the bearer token, you can start making API calls with it.

The following code example generates an OAuth token.

API operation

Create an OAuth token

Request

Copy
Copied
GET https://rest.apisandbox.zuora.com/oauth/token

Request body (form-encoded)

Copy
Copied
client_id: 6909f6c1-3eeb-4cd2-9778-a3656f077842
client_secret: 196s6a2V8mNHCFZUFhp9mxw=1Nu8laAQuS4/BOa
grant_type: client_credentials

Response

Copy
Copied
{
    "access_token": "6447d349d8854f0d8d5535484b0b862b",
    "token_type": "bearer",
    "expires_in": 3598,
    "scope": "entity.11e643f4-a3ee-8bad-b061-0025904c57d6 platform.write service.genesis.read service.genesis.write service.usage.delete service.usage.update service.usage.write tenant.12270 user.2c92c0f86680fd7777777ad86e455692",
    "jti": "6447d34955555f0d8d5535484b0b862b"
}

For a video demo of the process, see Making Zuora API calls using Postman. The video uses Postman, but the steps apply to other API tools.

Pagination

When retrieving information using GET methods, the optional pageSize query parameter sets the maximum number of rows to return in a response. The default and maximum values for different objects are different. 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.

If more rows are available, the response will include a nextPage element, which contains a URL for requesting the next page.

Below is an example of the nextPage element in the response for the Get product catalog operation.

Copy
Copied
{
  "products": [
  ...
  ],
  "nextPage": "/v1/catalog/products?page=2&pageSize=10",
  "success": true
}

To get the second page of results, you need to make another call using the base URL and the nextPage value.

For example:

Copy
Copied
GET https://rest.apisandbox.zuora.com/v1/catalog/products?page=2&pageSize=10