Getting Started Tutorial

This guide walks you through how to make your first API call to Zuora from scratch.

In this guide, you will learn:

How to create an API user and generate credentials
How to authenticate to the Zuora REST API
How to send your first request

Estimated completion time

10 minutes

Choose the development environment

Zuora Quickstart API is recommended for new integrators. The Quickstart API supports essential business use cases, and it allows new integrators to integrate with Zuora in just a few minutes.

Zuora also offers the SDK that is built on the Quickstart API.

cURL : See the sections below.
SDK : See Quickstart for SDK for example

Step 1. Get a Zuora test environment

You must have at least one of the Zuora test environments to make API requests.

If you do not yet have a Zuora environment, sign up for a Zuora Test Drive to get a test environment.

If you already have a Zuora tenant, you can use either of the following environments to make API calls:

API Sandbox
Zuora Central Sandbox

Step 2. Generate authentication credentials

To use the Zuora REST API, the role of the user you use to make API calls must have API write access. Zuora recommends that you create a dedicated user for making API calls.

Take the following steps to create an API user, then generate an OAuth client:

Log in to the Zuora UI as the tenant administrator.
Click the user name at the top right and click Administration .
Create an API user role.
1. On the Administration Settings page, click Manage User Roles .
2. On the Manage Roles page, click Add New Role .
3. In the Basic Info section on the New Role page, enter a name in the Role Name field that clearly identifies this role, such as API user .
4. In the Platform Permissions section, select the API Write Access check box and leave the UI Access box unchecked. This step gives the role the capability to create, update, and delete data using REST APIs, but not to log into the UI.
5. Click Save . The Manage Roles page displays the API user role.
Click back to Administration Settings to go back to the Administration Settings page.
Assign the API user role to a user.
1. On the Administration Settings page, click Manage Users .
2. On the All Users page, click Add Single User to create a new user.
3. For the Zuora Platform Role setting, select the API user role you created in Step 3 from the list.
4. Complete all other fields, then click Save . An activation email is then sent to the email address specified in the Work Email field.
Find the activation email sent from Zuora in your mailbox, then click the link contained in the email and set a password, then this user is activated.
Generate client credentials.
1. On the All Users page, locate the API user you configured in step 5 and 6 in the table, then check that the user's status is Active .
2. Click the user's First Name , Last Name , or User Name .
3. In the New OAuth Clients section, enter a name for the OAuth client.
4. Click Create . Then the Client ID and Client Secret for the OAuth client are displayed. This is the only time you can see the Client Secret.
5. Note down the client ID and client secret. You will need the Client ID and Client Secret to generate OAuth tokens. Then click OK .

Step 3. Generate an OAuth token

Use OAuth 2.0 bearer token for authentication when calling the Zuora API.

You need to make a call through the Create an OAuth token operation to generate a bearer token. The token will be included in the response. For this operation, include the following fields:

client_id : It is the Client ID obtained in step 2.
client_secret : It is the Client Secret obtained in step 2.
grant_type : It must be set to client_credentials .

The following code example generates an OAuth token.

cURL request (form-encoded)

Copy

Copied

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
     -d "client_id=b64e42ba-7e1a-4bc6-9146-5e1b420306b5" \
     --data-urlencode "client_secret=dOFENLWU193EEoEsWjPZrcjLKVr5OrN1HC9Kqg" \
     -d "grant_type=client_credentials" \
     "https://rest.apisandbox.zuora.com/oauth/token"

Response body

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"
}

The value for access_token will be used in later steps. Each token is valid for an hour. If it expires, you need to perform this step again.

Step 4. Submit your first API request

Now you are all set to submit your first API request!

In most scenarios, customers start building with Zuora by creating products or creating customer accounts.

In Zuora, a customer account (account for short) is a container of all critical information about your customers (end-subscribers) who subscribe to the products or services you offer in your product catalog.

This section demonstrates a detailed example of creating a customer account using the Create an account operation.

To create a customer account using the Quickstart API, you need to specify the following required fields:

name : Name of the account
bill_to : Bill-to contact information.
currency : Currency of the account

The following example creates an account named Amy Lawrence’s account where the currency is USD and the bill-to contact is Amy Lawrence who is based in CA, USA:

cURL request

Copy

Copied

curl --request POST \
     --url 'https://rest.apisandbox.zuora.com/v2/accounts' \
     --header 'Authorization: Bearer 6447d349d8854f0d8d5535484b0b862b' \
     --header 'Content-Type: application/json' \
     --data '{ 
        "name": "Amy Lawrence’s account",
        "bill_to": {
            "first_name": "Amy",
            "last_name": "Lawrence",
            "address": {
                "country": "USA",
                "state": "CA"
            }
        },
        "currency": "USD"
      }
'

Response body

Copy

Copied

{
	"id": "8ad0823f83ac566d0183b551d0d324c8",
	"updated_by_id": "8ad09bce80507dab0180688bdabc20cb",
	"updated_time": "2022-10-07T18:59:41-07:00",
	"created_by_id": "8ad09bce80507dab0180688bdabc20cb",
	"created_time": "2022-10-07T18:59:41-07:00",
	"account_number": "RC-00020756",
	"billing_document_settings": {
		"credit_memo_template_id": "",
		"debit_memo_template_id": "",
		"email_documents": false,
		"print_documents": false,
		"invoice_template_id": "8f64d4d754739d85d0346e00ef77e50d",
		"additional_email": []
	},
	"batch": "Batch1",
	"bill_cycle_day": 0,
	"communication_profile_id": "",
	"crm_id": "",
	"default_payment_method_id": "",
	"name": "Amy Lawrence GZIP test",
	"description": "",
	"payment_gateway": "",
	"payment_terms": "Due Upon Receipt",
	"sequence_set_id": "",
	"auto_pay": false,
	"currency": "USD",
	"enabled": true,
	"remaining_debit_memo_balance": 0,
	"remaining_invoice_balance": 0,
	"remaining_credit_memo_balance": 0,
	"remaining_payment_balance": 0,
	"bill_to_id": "8ad0823f83ac566d0183b551d11424cf",
	"sold_to_id": "8ad0823f83ac566d0183b551d11424cf"
}

Step 5. Verify the result

After the account is created, you can verify the result in the Zuora UI or through the GET API operations for the Account object.

To verify the result through the Zuora UI, you can find the created account displayed at the top of the All Customer Accounts page by navigating to Customers > Customer Accounts in the Zuora UI.

To verify the result through the Quickstart API, you can use one of the following operations:

What to do next

You can then proceed to complete the following tasks:

Create a product: Create a product
Create a subscription: Create a subscription

For detailed examples for different use cases, check our API Guides:

For the API documentation, check Zuora’s API References: