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:
If you would like to host your code on the Zuora Central platform, and have not already signed up to become a Zuora Developer, see Building on Zuora Central for how to get started.
Zuora Central is the subscription order-to-cash platform that powers every Zuora tenant. The platform is also open and extensible, enabling Zuora partners and customers to build Apps that extend Zuora for their unique needs.
As a developer, you can create Apps to enhance the capabilities of any Zuora tenant. Once you build Apps with functionality that other organizations might also like to use, you can showcase and sell your Apps on the Connect Marketplace. Your Apps will be viewed and considered by hundreds of Zuora customers and prospects.
To start building on Zuora Central, you must first sign up to become a Zuora Developer and complete a few initial setup steps. If you want to integrate with the Zuora REST API without hosting your code on the Zuora Central platform, jump to REST API; in that case, you do not need to sign up to become a Zuora Developer.
To start building on Zuora Central:
Step 1: Visit https://connect.zuora.com/partner and sign up.
To get the most out of being a Zuora Developer, Zuora recommends that you also join the Developer User Group and the Connect User Group.
After Zuora has successfully registered you as a Zuora Developer, you will receive two emails from Zuora:
As part of the registration process, Zuora will also create a Zuora Connect account for you. Zuora Connect is where you will manage the Apps that you create for the Zuora Central platform.
Steps 2 through 4 explain how to activate your Zuora Developer Sandbox and link your Zuora Developer Sandbox user account with Zuora Connect.
Step 2: In the email with information about accessing your Zuora Developer Sandbox, click the link to apisandbox.zuora.com to activate your Zuora Developer Sandbox user account.
After you have activated your Zuora Developer Sandbox user account, you will be logged into your Zuora Developer Sandbox.
Note: To log into your Zuora Developer Sandbox again in the future, visit https://apisandbox.zuora.com/apps. Your username is the email address that you entered when you signed up to become a Zuora Developer. The email from support@zuora.com was sent to this address.
Step 3: In your Zuora Developer Sandbox, navigate to My Connect > Purchases:
Zuora Connect opens and displays the Edit Profile page:
Step 4: Complete your profile by setting up two factor authentication.
If you are unable to receive two factor authentication tokens from Zuora, contact connect@zuora.com.
After you have set up two factor authentication, your Developer Sandbox user account is linked with Zuora Connect.
Step 5: In your Zuora Developer Sandbox, navigate to My Connect > Developer:
Zuora Connect opens and displays your Zuora Developer dashboard:
To enable you to fully test Apps, you must create a Zuora Connect login for your Zuora Developer Sandbox. The Zuora Connect login will specify the authentication credentials of your Zuora Developer Sandbox.
Step 6: In Zuora Connect, navigate to My Connect > Tenants, then click New Login and select Zuora:
The New Login dialog box opens:
Step 7: Enter the username and password of your Zuora Developer Sandbox user account, then click Save Login.
You are now ready to start creating Apps!
In the next section, you will learn how to:
To learn how to integrate with the Zuora REST API, see REST API.
An App is custom code that runs as a web service on the Zuora Central platform. By hosting your code on the Zuora Central platform, you can take advantage of:
As a developer, you can create Apps that enhance the capabilities of any Zuora tenant. For example, you could create an App that adds custom billing functionality, or you could create an App that synchronizes customer accounts with an external system.
Before you can create Apps on Zuora Central, you must have signed up to become a Zuora Developer. The signup process grants you the permission to run code on Zuora Central and ensures that you have access to a Zuora Developer Sandbox.
If you have not signed up to become a Zuora Developer, start the process at https://connect.zuora.com/partner.
To help you learn how to create Apps for your organization, Zuora has created an open source Starter Package. This App is written in Ruby on Rails.
The Starter Package demonstrates several important aspects of App development, including:
To create an App that is based on the Starter Package:
Step 1: In Zuora Connect, navigate to My Connect > Developer, then click the Applications tab and click New Application:
The New Application dialog box opens.
Step 2: Enter a name for the App, then select Web Service from the Type list.
Step 3: Click the Modes tab, then click the white space to the right of “Universal”.
This expands the “Universal” mode:
Modes enable you to maintain a single codebase that addresses several different use cases. In this case, the App will only have one mode.
Step 4: In the “source” row, click Remove.
The remaining “target” row specifies that the App will require access to a single Zuora tenant. Because of how the Starter Package is coded, it is important that you do not change the “target” row.
Step 5: Click Save Application.
Zuora Connect creates the App:
The App’s code will be stored in a GitLab repository that is hosted by Zuora. You will access this repository in a later step.
Before the App’s code can run on the Zuora Central platform, you must create a “build” via Zuora Connect. The build will enable you to specify and configure the Zuora Central environment that the code will run in.
Step 6: Click the Builds tab, then click New build and select the App:
The New Application Build dialog box opens.
Step 7: Select the Zuora Central data center that you want the App’s code to run in, then select Test from the Environment list:
Step 8: Click Save Build.
Zuora Connect creates a Test build:
Because the Starter Package stores data in a PostgreSQL database, you must create a PostgreSQL database for the Test build.
Step 9: To create a PostgreSQL database for the Test build, first select Show Build from the build menu:
On the Resources tab of the page that opens, click Add Database to the right of “Databases”:
Click Save.
Step 10: To view the GitLab repository for the App, navigate to My Connect > Developer, then click the Applications tab and select GitLab Repo from the App menu:
The GitLab repository is configured so that merges trigger a pipeline that tests and deploys the code to the Zuora Central platform. The testing and deployment pipeline is controlled by the file .gitlab-ci.yaml. The part of this file that contains stage: deploy is not intended to be modified.
The repository has two branches: master and test. These branches are protected, which means that you must create a merge request before merging to either branch.
The test branch was created when the Test build was created. The master branch was created when the App was created. Code in the master branch will not be deployed to the Zuora Central platform until you create a Production build via Zuora Connect.
Step 11: Create an experimental branch in the GitLab repository, then clone the experimental branch in your local development environment.
See How to create a branch in the GitLab documentation for more information.
The remote URL of the GitLab repository is displayed on the Project page in GitLab:
See SSH in the GitLab Documentation for how to configure your SSH keys.
Step 12: Download and set up the Starter Package according to the README file.
As part of the setup process, you must specify the username and password of a Zuora user account. This is required to run the Starter Package in your local development environment. You can specify the username and password of your Zuora Developer Sandbox user account.
Step 13: Commit your modified Starter Package code to your local copy of the experimental branch, then push the experimental branch to the GitLab repository.
Step 14: In the GitLab repository, create a merge request to merge the experimental branch to the test branch.
See How to create a merge request in the GitLab documentation for more information.
After you create the merge request, GitLab starts a pipeline that tests the App’s code. You can monitor the pipeline on the Pipelines page:
Step 15: When the status of the pipeline is “passed”, accept the merge request:
After you accept the merge request, GitLab starts a pipeline that deploys the App’s code to the Zuora Central platform. If the pipeline passes, the Test build of the App is running as a web service on the Zuora Central Platform. The URL of the Test build is https://{app_name}-test.apps.zuora.com.
To fully test the App, you must use Zuora Connect to create an instance of the App. This is because the Starter Package uses the Zuora Central Gem to obtain user configuration data from Zuora Central, rather than relying on hardcoded configuration data. See the next section for more information.
Apps are not required to obtain user configuration data from Zuora Central. However, if you want your Apps to support multiple users or multiple Zuora tenants, your Apps should make use of the Zuora Central Gem – or a reimplementation of the Zuora Central Gem in your preferred language.
If you choose to write your Apps in Ruby, Zuora also recommends that your Apps make use of the Zuora API Gem.
Zuora Central provides a standardized way for users to create instances of Apps. When a user creates an instance of an App, the user specifies which Zuora tenants the App should access, any external systems that the App should access, and which actions the App should perform.
If you have created an App that supports multiple instances, you can test your App by using Zuora Connect to create an instance of your App. The Starter Package demonstrates how to create an App that supports multiple instances.
Before you can create an instance of an App, you must create a private listing of the App. To create a private listing of a App:
Step 1: In Zuora Connect, navigate to My Connect > Developer, then click the Listings tab and click New App:
The New App page opens.
Step 2: Enter a title, short description, type, and category for the listing.
You can enter additional details about the listing, but this is not necessary because you are creating a private listing. The details you enter will not appear publicly on the Connect Marketplace.
Step 3: Select the App from the Application list:
Step 4: Click Next until you reach the Sharing tab.
Step 5: Select Private from the Sharing Status list, then click Submit.
Zuora Connect creates a listing of the App. You can view the listing on the Listings tab of the Developer page:
Step 6: Hover over the listing, then click the name of the listing.
A preview of the listing’s Connect Marketplace page opens:
Step 7: Click Download, then close the dialog box that appears.
This step ensures that you can create instances based on the listing.
To create an instance of an App:
Step 1: In Zuora Connect, navigate to My Connect > Tenants.
Step 2: Hover over the entry for your Zuora Developer Sandbox, then click Apps:
An overview of your Zuora Developer Sandbox opens.
Step 3: Click the Apps tab, then click New and select the App:
The New Configuration dialog box opens:
Step 4: Enter a name for the instance, then click Create.
Zuora Connect displays the instance:
You can then test the App via the user interface of the instance. To view the user interface of the instance, hover over the instance, then click Launch:
After you have developed and fully tested an App, and are ready to offer the App’s functionality to other organizations that use Zuora, you can submit the App to Zuora for certification. Certified Apps are eligible to be listed publicly on the Connect Marketplace.
The App certification process ensures that each App’s code is secure, scalable, and correctly supports multiple instances. The App certification process also ensures that the Apps in the Connect Marketplace have a consistent level of usability, branding, documentation, and support.
If you plan to submit an App to Zuora for certification, use the following checklist to help prepare your App for the certification process:
For additional information about submitting your App for certification, contact isv@zuora.com.
Once your App has been certified by Zuora, and is listed publicly on the Connect Marketplace, you are considered a Zuora partner and can market and sell your App.
© 2018 Zuora Inc.
