This tutorial demonstrates how to get started with the Zuora REST API. During the tutorial, you will learn how to programmatically implement basic subscription use cases.
This tutorial is for those who are new to the Zuora REST API. By the end of the tutorial, you will have created, upgraded, and cancelled a sample subscriber via the Zuora REST API. In the process, you will also become familiar with the Zuora API client development process.
You should complete this tutorial’s exercises in the listed order. Each exercise builds on the work done in the preceding exercises. The entire series should take approximately 20 minutes to complete.
See API Reference for additional details about the Zuora REST API.
To complete this tutorial, you’ll need the following:
In this tutorial, you will go through a number of exercises to:
In all the exercises, you will send a REST request using the following general procedure.
$your-zuora-username and $your-zuora-password in the given request with your Zuora Test Drive tenant username and password.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.
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",
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 }
Now, the customer wants to upgrade to another product rate plan.
In this exercise, you will:
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
}
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
}
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:
© 2019 Zuora Inc.
