Getting Started with the SOAP API
Before you can begin coding, there are things you'll need to assemble and configure, and a few terms and concepts you'll need to know along the way.
If you're familiar the SOAP API, use the following checklist to make sure you have everything.
If you're newer to APIs or SOAP, start with this article to get yourself set up properly.
What do I Need?
To start, you need the following:
- Zuora account with the API user role
- SOAP development environment (WSDL-capable)
- Zuora WSDL
- Zuora API utility (optional)
- Zuora Sandbox (optional)
Set up Checklist for the Zuora API Environment
Item | Required? | Description | Where to Get It |
---|---|---|---|
Zuora account | required | A Zuora account lets you look at materials available only to registered users, and to contact Support for administration access credentials. | http://info.zuora.com/subscribe.html |
Zuora API user role | required | A Zuora API user role allows you to use the API functions. | Set up a Zuora account with the API user role |
SOAP development environment (WSDL capable) | required | Install and set up a SOAP development environment that can use a WSDL. You use this environment to code with the Zuora API. | Zuora does not endorse any particular SOAP development environment, but you might like some of the offerings at Sourceforge. |
Zuora WSDL | required | The WSDL defines the interface for Zuora's web services, and is essential for using the API. | See Download the Zuora WSDL, below. Import the WSDL file into your development environment. |
Zuora API utility | optional | Use this utility's tools to open XML templates for making API calls and testing inputs. You can troubleshoot error messages and discover potential implementation issues. | Ensure that you have a local web server with PHP installed. Go to the Zuora GitHub repository. Download the php-tools pack into your web root director. Download the latest Zuora WSDL into the php-tool folders. |
Zuora Sandbox | optional | Use the Zuora Sandbox to develop and test your applications without affecting your production environment or data. | Contact your Zuora representative. |
Set up a Zuora Account with the API User Role
To use the API, you need a Zuora account with API access. See Creating an API User for more information.
Get a SOAP Development Environment
You need a SOAP development environment that's WSDL-capable. While Zuora can't recommend a particular environment, you might find SOAP environments that you like at Sourceforge. If you are new to working with APIs, then look for one that is friendly to novice users - for instance, an environment that provides a wizard for importing WSDL files.
Download the environment, then install and configure it according to its instructions.
Download the Zuora WSDL
In WSDL 68 and earlier, there are 56 date fields in the Zuora SOAP API that Zuora treats as dateTime fields. From WSDL 69 and later, Zuora treats these fields as date fields and they will no longer accept dateTime values. Before downloading and using WSDL 69 or later, check to see if your SOAP integration passes or receives dateTime values to or from any of these fields.
See Date Fields Changes in the SOAP API for more information.
As of Zuora WSDL v61.0, downloading the WSDL supports custom fields. Re-adding custom fields after downloading the WSDL is no longer required.
To download the Zuora WSDL, use one of the following addresses. Replace XX.X by the version you want to download, for example 63.0. Omit the version
parameter to retrieve the latest WSDL version.
Zuora Environment | WSDL URL |
---|---|
Production | https://www.zuora.com/apps/servlet/GenerateWsdl?version=XX.X |
API Sandbox | https://apisandbox.zuora.com/apps/servlet/GenerateWsdl?version=XX.X |
Services |
https://servicesNNN.zuora.com/apps/servlet/GenerateWsdl?version=XX.X NNN denotes the services environment number. |
Performance Test | https://pt1.zuora.com/apps/servlet/GenerateWsdl?version=XX.X |
EU Production | https://eu.zuora.com/apps/servlet/GenerateWsdl?version=XX.X |
EU Sandbox | https://sandbox.eu.zuora.com/apps/servlet/GenerateWsdl?version=XX.X |
Central Sandbox | https://test.zuora.com/apps/servlet/GenerateWsdl?version=XX.X |
Zuora API utility
The Zuora API utility can help you with your API implementation. You can use this utility to open XML templates for making API calls and test various inputs. This is useful for a variety of purposes:
- Familiarizing yourself with Zuora objects and calls
- Looking up information from
Account
,Subscription
,ProductRatePlan
, and other objects for testing purposes - Testing SOAP XML generated by your code base in order to troubleshoot error messages or other implementation issues
While this utility isn't essential nor supported for using the Zuora API, some users find it useful to testing, troubleshooting, and generating sample code.
Disclaimer for the API utility:
Install the Zuora API Utility
To download and install the Zuora API utility:
- Ensure that you have a local web server with PHP installed.
If you need to get one, you might like XAMPP for Windows or MAMP for Mac. - Download the php-tools pack into your web root directory.
- Download the latest version of the Zuora WSDL into the php-tools folder.
To check your installation:
- Start your local web server.
- Using your web browser, open the
php-tools
folder.
The Zuora API utility loads automatically when you navigate into the php-tools
folder from your browser.
How do I use the Zuora API utility?
Before you start, make sure that you have the latest WSDL file in your php-tools folder.
Open your browser and open your php-tools
directory. The API utility automatically loads.
You can use the dropdowns on the right side of the utility to load the templates for XML calls, or you can enter ZOQL statements directly at the prompt.
Select the appropriate WSDL from the dropdown at the top of the page. Secure a session ID (SessionId
) using your username and password, then remove the check from the Refresh? check box. If you leave the Refresh? check box selected, then you must re-enter your password until your Session ID expires.
Example: Look up ProductRatePlan Information
This example looks up the product ID (Product Id
) values for all of the ProductRatePlan
objects for a particular product (Product
).
- Open your browser and navigate to your php-tools folder.
- Log in to your server.
- Enter the following ZOQL query in the query text field:
select id, name from Product
- This query returns the ID for the product. You can use the value in the
Id
field to look up theProductRatePlan
objects associated with the product.
- Enter the following ZOQL query:
select id, name from ProductRatePlan where productid = '4028e4852ebd1027012ed8dc5aa36b83'
- Uncheck the Refresh? checkbox so that you don't have to re-enter your password.
- Click the Submit button.
This query returns the values for the Name andId
fields for all of theProductRatePlan
objects associated with the product.
Zuora Sandbox
You need to contact your Zuora representative for access to the Zuora Sandbox.
The Zuora Sandbox is a non-production environment that provides full access to the Zuora API. You can use it to develop and test your client applications without worrying about how your work might affect your production environment or production data.
When using the Sandbox, you must change the URL of the WSDL before using it in your toolkit. Contact your Zuora sales representative to obtain the correct URL.