BEFORE YOU BEGIN

To complete this tutorial, you’ll need the following:

• Access to a non-production Zuora tenant. This tutorial is designed for Test Drive tenants. Test Drive tenants come with seed data, including a sample product catalog, which will be used in the exercises.
  • Go to Zuora Test Drive and sign up for a tenant.
  • Log into your Test Drive tenant, and optionally complete the UI walkthrough tutorial.

• Prepare to execute REST API calls by one of the following:
  • Installing cURL
    The examples in this tutorial use cURL, a command-line tool for making HTTP requests.
    • On MacOS X, cURL is installed by default.
    • On Windows, download and install cURL.
  • Downloading Quick Start Libraries
    The set of exercises below have been prepared in a variety of popular programming languages below. Please pick the one you prefer:
    • Quick Start in Java
    • Quick Start in PHP
    • Quick Start in C#
  • Use your favorite REST tool, such as Postman.

RUNNING EXERCISES

In this tutorial, you will go through a number of exercises to:

1. Retrieve a catalog of available services.
2. Sign up a subscriber.
3. Upgrade the subscription.
4. Cancel the subscription.

In all the exercises, you will send a REST request using the following general procedure.

1. Copy the command to a text editor.
2. Replace $your-zuora-username and $your-zuora-password in the given request with your Zuora Test Drive tenant username and password.
3. Replace any other variables in the request.
4. Open a command line, such as Terminal on Mac or command prompt on Windows.
5. Copy and paste the request at the command line prompt and execute the request.

NOTE: Turn off Smart Quotes in your text editor. cURL will not recognize smart quotes in your commands. For example, if you are using TextEdit in MacOS, navigate to Edit > Substitutions, and deselect Smart Quotes.

EXERCISE 1. QUERY FOR A PRODUCT

Your new customer wants to subscribe to one of your services.

In this exercise, you will first make a REST request to query the product catalog for the service your customer is interested in.

You will use the pre-seeded sample catalog in your Test Drive tenant.

Request

Use the following Get Products request to retrieve a list of products and product rate plans in your product catalog.

curl -X GET \
-H "apiAccessKeyId: $your-zuora-username" \ -H "apiSecretAccessKey: $your-zuora-password" \ "https://rest.apisandbox.zuora.com/v1/catalog/products"

Response

If successful, a JSON response will return the full list of products in your Zuora Test Drive tenant.

Get the product rate plan id, $your-product-rateplan-id, from the response. You will sign up the customer for that product rate plan in the next exercise.

Also select the second product rate plan in the response. Save the second product rate plan id for Exercise 3. We will refer to the second product rate plan id as $your-product-rateplan2-id.

{
  "products": [
    {
      "id": "40802c833cd52a260152390587481482",
      "sku": "SKU-00000016",
      "name": "Enterprise",
      "description": "Endless possibilities with full API access and unlimited customizations",
      "category": "Base Products",
      "effectiveStartDate": "2015-01-01",
      "effectiveEndDate": "2020-01-01",
      "productRatePlans": [
       {
          "id": "$your-product-rateplan-id",            "status": "Active",          "name": "User Plan",          "description": "Complete access to the platform restricted to licensed users only",          "effectiveStartDate": "2015-01-01",          "effectiveEndDate": "2020-01-01",

EXERCISE 2. CREATE A CUSTOMER ACCOUNT AND A SUBSCRIPTION

You used the response from Exercise 1 to present the products, product rate plans, and charges in your product catalog. The customer selected a product rate plan.

In this exercise, you will sign up your first customer for the product rate plan you selected in Exercise 1.

Request

Use the following Create Account request to create a new customer account and a new subscription for the customer. Replace $your-product-rateplan-id in the request below with the first product rate plan id returned in the response in Exercise 1.

curl -X POST \
-H "apiAccessKeyId: $your-zuora-username" \ -H "apiSecretAccessKey: $your-zuora-password" \ -H "Content-Type: application/json" \ -d '{ "name":"ABC Unlimited",  "currency":"USD",  "billToContact":{    "firstName":"Leo", "lastName":"Liu"  },  "soldToContact":{      "firstName":"Leo",      "lastName":"Liu",      "state":"CA",   "country":"USA" },  "creditCard":{    "cardType":"Visa",    "cardNumber":"4111111111111111",    "expirationMonth":10,    "expirationYear":2020,    "securityCode":"111"  }, "subscription":{    "contractEffectiveDate": "2016-10-01",    "termType":"TERMED",    "autoRenew":false,    "initialTerm":12,    "renewalTerm":12,    "subscribeToRatePlans":[      {        "productRatePlanId": "$your-product-rateplan-id"      }    ]  } }' "https://rest.apisandbox.zuora.com/v1/accounts"

Response

When the account and the subscription are successfully created, a JSON response will return the information about the new account and the new subscription. Make a note of the subscription number that you will need in the next two exercises.

{
  "success": true,
  "accountId": "2c92c0fb574ee46801574ef42dea04a0",
  "accountNumber": "A00000062",
  "paymentMethodId": "2c92c0fb574ee46801574ef42e4204a4",
  "subscriptionId": "2c92c0fb574ee46801574ef42ee104aa",
  "subscriptionNumber": "$your-subscription-number",  "contractedMrr": 4,  "totalContractedValue": 48 }

EXERCISE 3. UPGRADE A SUBSCRIPTION

Now, the customer wants to upgrade to another product rate plan.

In this exercise, you will:

1. Query the subscription to get the current subscription rate plan id that will be upgraded.
2. Query the product catalog to get the new product rate plan id your customer wants to upgrade to. To save time, you will use the second product rate plan id you saved in Exercise 1.
3. Amend the subscription to both remove the existing rate plan and add a new product rate plan.

Request 3a

Use the following Get Subscription request to retrieve the existing subscription rate plan id in the subscription. Use $your-subscription-number in the response from Exercise 2.

curl -X GET \
-H "apiAccessKeyId: $your-zuora-username" \ -H "apiSecretAccessKey: $your-zuora-password" \ "https://rest.apisandbox.zuora.com/v1/subscriptions/$your-subscription-number"

Response 3a

In the response, retrieve the current subscription rate plan id, $your-rateplan-id.

"ratePlans": [
  {
    "id": "$your-rateplan-id",

Request 3b

Now you have all the information to use the following Update Subscription request to upgrade the subscription.

curl  -X PUT \
-i -k -H "apiAccessKeyId: $your-zuora-username" \ -H "apiSecretAccessKey: $your-zuora-password" \ -H "Content-Type:application/json" \ -H "Accept:application/json" \ -d '{ "remove": [{   "ratePlanId": "$your-rateplan-id",    "contractEffectiveDate": "2016-12-01" }], "add": [{   "productRatePlanId": "$your-product-rateplan2-id",   "contractEffectiveDate": "2016-12-01" }] }' "https://rest.apisandbox.zuora.com/v1/subscriptions/$your-subscription-number"

Response 3b

The Update Subscription request creates a new subscription, which has the old subscription number but a new subscription ID. The JSON response returns that new subscription ID.

{
  "success": true,
  "subscriptionId": "2c92c0fb574ee46a01574f04ea9a0631",
  "totalDeltaMrr": 15,
  "totalDeltaTcv": 180
}

EXERCISE 4. CANCEL A SUBSCRIPTION

The customer decided to cancel the current subscription.

In this exercise, you will cancel the existing subscription.

The cancellation will be effective as of the first day of the next billing period. By picking this specific date, this cancellation will not result in a credit to the customer.

Request

Use the following Cancel Subscription request to cancel the subscription.

curl -X PUT \
-H "apiAccessKeyId: $your-zuora-username" \ -H "apiSecretAccessKey: $your-zuora-password" \ -H "Content-Type: application/json" \ -d '{  "cancellationPolicy": "SpecificDate",  "invoiceCollect":false,  "cancellationEffectiveDate": "2016-11-30" }' "https://rest.apisandbox.zuora.com/v1/subscriptions/$subscription-number/cancel"

Response

The following response confirms that the subscription was successfully cancelled effective as of November 30, 2016.

{
  "success": true,
  "subscriptionId": "2c92c0fb574ee46a01574f0d2881076c",
  "cancelledDate": "2016-11-30",
  "totalDeltaMrr": 0,
  "totalDeltaTcv": -228
}

NEXT STEPS AND RESOURCES

And you’re done! You were able to take a subscriber through a full lifecycle in four easy steps.

Now that you are acquainted with Zuora REST API, take the next steps to implement your subscription application. Here are a few recommendations:

1. For advanced use cases, take a look at the API Tutorials.
2. For a high-level view of the key Zuora objects, view the Zuora Object Relationship diagram.
3. For a detailed list of all API calls, refer to the Zuora REST API Reference. This reference also includes information about authentication, pagination, and versioning.
4. For more general product information about Zuora features, see the Zuora Knowledge Center.