Get started

This page and the "Tutorials" section in the left-hand menu provide code examples in either our REST API or the client libraries version 3.x.

Use this content as a guide to set up your local development environment and send your first API request. This content will guide you through:

  • How to set up your development environment
  • How to install the latest client libraries (SDK)
  • Some basic concepts
  • How to send your first API request using cURL or Zuora client libraries
If you run into any issues or have questions, join our Developers Community to find answers or raise your questions.

Zuora client libraries version 3.x is in the Early Adopter phase. It integrates both the v1 API and Quickstart API into a unified set of libraries. We recommend that you try our client libraries 3.x to start testing or integrating with Zuora.

Tenant setup

This tutorial assumes that you are using either a Zuora-provided test drive, or your own Zuora Central Sandbox environment with billing accounts set up.

OAuth client setup

Accessing the Zuora API requires a user account with the necessary privileges. Zuora recommends using OAuth 2.0 for all API interactions and using a dedicated user account with the API write access for all API or client libraries interactions.

Establishing such a user account requires either being an administrator in the Zuora tenant or having access to your coworkers who are administrators in the tenant.

Follow the steps below to set up an OAuth client:

  1. Create a user role with the API Write access enabled if it doesn’t already exist. Do so even if you will only use one of our client libraries.

    a. Navigate to Settings > Administration > Manage User Roles, and click Add New Role. You can find the Settings option by clicking your initial at the top right.

    b. Specify a name for the new role, for example, API Write Role.

    c. Select the API Write Access checkbox and click Save.

  2. Create a login empowered with that role where you receive the password setting email. Setting the password will enable the user account.

    a. Go back to the Administration Settings page, select Manage Users, and click Add Single User.

    b. Enter your first name, last name, work email, and login name. You won’t be able to use an existing login. A login name that is descriptive and relevant is recommended, for example, APIWriteAccess@yourcompany.com.

    Most of the remaining fields can be left to there defaults, but keep the following points in mind:

    • Ensure that your work email is correctly entered to ensure you receive an email to set your password. Setting the password will activate this new account.
    • Ensure that you set the Zuora Platform Role to the role you created in Step 1.b, we used API Write Role.
  3. Create an OAuth client for the account and capture the client id and secret. You will use these to obtain tokens prior to making API calls or using the libraries. Assuming the correct work email was specified, you will receive an email to set your password.

    a. Once the password has been successfully set, you or your administrator should return to the Manage Users page. Click the created user we created in step 2.b. The user account details page is displayed.

    b. At the bottom of the page, Specify a meaningful name and description for the client in the New OAuth Client section.

    The following animated screenshot demonstrates how to navigate to the New OAuth Client section in the Zuora UI.

    Set up OAuth client

    c. Click Create, and the Client ID and Secret are displayed. You should note down the client ID and secret in a secure location because client secret is only displayed once.

Note that a different Client ID and Secret are needed for each tenant, for example, sandbox or production.

Getting started language selection

Select tool or language you want to use to get started.

cURL
Java
Node.js
Python

cURL is a popular command-line tool for transferring data using network protocols like HTTP and HTTPS. ​​It requires minimal setup but is less capable than fully-featured programming languages like Java or JavaScript. With cURL installed, you can enter the cURL commands in the Terminal or Command Prompt and see the response immediately.

Step 1. Set up cURL

cURL is pre-installed on some operating systems by default, for example, MacOS or Linux. Check whether you have cURL installed by opening your Terminal or command line interface by entering the command:

Copy
Copied
curl https://developer.zuora.com/docs/get-started/introduction/ --compressed

With cURL set up this will send an HTTP request to fetch the contents of "developer.zuora.com/docs/get-started/introduction/".

If you see an error indicating that cURL is not found, you should install it by following the instructions on the Install curl and libcurl.

Step 2: Set up authentication credentials

After you confirm that cURL is installed, you can set up your credentials in your Terminal or Command Prompt.

MacOS/Linux

  1. Open Terminal: You can search for terminal through Spotlight Search or find it in the Applications folder.
  2. Edit bash profile: To open the profile file in a text editor, enter the command nano ~/.bash_profile or nano ~/.zshrc (for newer MacOS versions).
  3. Add your client credentials as environment variables: In the editor, add the following lines to the profile file, replacing your-client-id with your client ID and your-client-secret with your client secret:
    Copy
    Copied
    export ZUORA_CLIENT_ID='your-client-id'
export ZUORA_CLIENT_SECRET='your-client-secret'
  4. Save the changes: To save the changes, press Ctrl + O. At the filename prompt, press Enter, then press Control + X to exit the editor.
  5. Load the updated profile: Use the command source ~/.bash_profile or source ~/.zshrc to load the updated profile.
  6. Setup verification: Verify the setup by entering echo $ZUORA_CLIENT_ID in the Terminal. It should display your client ID. Enter echo $ZUORA_CLIENT_SECRET in the Terminal and it should display your client secret.
  7. Create a bearer token: Send a request to Create an OAuth token to generate an OAuth bearer token.
    Copy
    Copied
    curl --request POST \
  --url https://rest.test.zuora.com/oauth/token \
  --header 'Accept: application/json' \
  --header 'Content-type: application/x-www-form-urlencoded' \
  --data client_id=$ZUORA_CLIENT_ID \
  --data-urlencode client_secret=$ZUORA_CLIENT_SECRET \
  --data grant_type=client_credentials

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

    Each bearer token is valid for an hour. When it expires, repeat this step again.

Windows

  1. Open Command Prompt: You can find it by searching cmd in the Start menu.
  2. Configure environment variable, in the current session or permanently.
    • Set environment variables in the current session: To set the ZUORA_CLIENT_ID environment variable in the current session, use the following command and replace your-client-id with your client ID:
      Copy
      Copied
      setx ZUORA_CLIENT_ID "your-client-id"
      To set the ZUORA_CLIENT_SECRET environment variable in the current session, use the following command and replace your-client-secret with your client secret:
      Copy
      Copied
      setx ZUORA_CLIENT_SECRET "your-client-secret"
    • Permanent setup: Alternative to setting variables for the session, you can make the setup permanent by adding your client credentials as system properties:
      1. Right-click the This PC or My Computer option, and select Properties.
      2. Click Advanced system settings.
      3. Click the Environment Variables button.
      4. In the System variables section, click New..., and enter ZUORA_CLIENT_ID as the variable name and your client ID as the variable value.
      5. In the System variables section, click New..., and enter ZUORA_CLIENT_SECRET as the variable name and your client secret as the variable value.
  3. Setup verification: Reopen the Command Prompt and enter the following command. It should display your client ID and secret:
    Copy
    Copied
    echo %ZUORA_CLIENT_ID%
echo %ZUORA_CLIENT_SECRET%
  4. Create a bearer token: Send a request to Create an OAuth token to generate an OAuth bearer token.
    Copy
    Copied
    curl --request POST \
  --url https://rest.test.zuora.com/oauth/token \
  --header 'Accept: application/json' \
  --header 'Content-type: application/x-www-form-urlencoded' \
  --data client_id=$ZUORA_CLIENT_ID \
  --data-urlencode client_secret=$ZUORA_CLIENT_SECRET \
  --data grant_type=client_credentials

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

    Each bearer token is valid for an hour. When it expires, you just repeat this step again.

Step 3. Send your first request

Now, you can send your first API request. A sample cURL request to query all customer accounts in your tenant is provided below. The page size is set to 1 for easier validation.

Customer accounts capture your customers' billing and payment details. Regardless of whether your customers are individuals or companies, the customer account is where Zuora captures their name, their addresses for billing and tax purposes, their payment methods, the orders they’ve placed for your products and services, and many other details. This is a topic you can explore in more depth in Manage customer accounts in our Knowledge Center. Note that you should replace your-bearer-token with the bearer token you generated in Step 2.
Copy
Copied
curl -L -X GET 'https://rest.test.zuora.com/object-query/accounts?pageSize=1' \
-H 'Authorization: b40653aaab554b60b7169041c02c0647'

You will receive an Account object with account details if the request succeeds.

Copy
Copied
{
    "nextPage": "W3sidmFsdWUiOiIyMDI0LTA3LTI1VDAyOjQ2OjIwWiIsIm9yZGVyQnkiOnsiZmllbGQiOiJVcGRhdGVkRGF0ZSIsIm9yZGVyIjoiREVTQyJ9fSx7InZhbHVlIjoiOGE4YWEzYmM5MGM0ZjE2OTAxOTBlN2MyNTQ1ZjNjODYiLCJvcmRlckJ5Ijp7ImZpZWxkIjoiSWQiLCJvcmRlciI6IkRFU0MifX1d",
    "data": [
        {
            "accountNumber": "A00000019",
            "allowInvoiceEdit": false,
            "autoPay": true,
            "balance": 0.0,
            "batch": "Batch1",
            "bcdSettingOption": "AutoSet",
            "billCycleDay": 25,
            "billToId": "8a8aa3bc90c4f1690190e7c254eb3c8d",
            "createdById": "c4c98efdaf78374783d85c22e0338e53",
            "createdDate": "2024-07-25T02:39:50Z",
            "creditBalance": 0.0,
            "currency": "USD",
            "defaultPaymentMethodId": "8a8aa3bc90c4f1690190e7c2566e3cb8",
            "id": "8a8aa3bc90c4f1690190e7c2545f3c86",
            "invoiceDeliveryPrefsEmail": true,
            "invoiceDeliveryPrefsPrint": false,
            "invoiceTemplateId": "8a368bbf87b6d5910187b80ab8f40d0b",
            "lastInvoiceDate": "2024-07-25",
            "mrr": 299.9,
            "name": "Test Customer 3",
            "partnerAccount": false,
            "paymentMethodCascadingConsent": false,
            "paymentTerm": "Due Upon Receipt",
            "soldToId": "8a8aa3bc90c4f1690190e7c2555f3ca4",
            "status": "Active",
            "taxExemptStatus": "No",
            "totalDebitMemoBalance": 0.0,
            "totalInvoiceBalance": 0.0,
            "unappliedBalance": 0.0,
            "unappliedCreditMemoAmount": 0.0,
            "updatedById": "c4c98efdaf78374783d85c22e0338e53",
            "updatedDate": "2024-07-25T02:46:20Z"
        }
    ]
}

Congratulations! You’ve made your first request to Zuora throught the REST API!

Next steps

We provide step-by-step tutorials for using the Zuora API and client libraries to complete typical business-to-consumer(B2C) business flows. Check our Tutorials to learn more.