Getting Started with the SOAP API

Last updated
Save as PDF

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:/* Copyright (c) 2011 Zuora, Inc.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of
* this software and associated documentation files (the "Software"), to use copy,
* modify, merge, publish the Software and to distribute, and sublicense copies of
* the Software, provided no fee is charged for the Software. In addition the
* rights specified above are conditioned upon the following:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* Zuora, Inc. or any other trademarks of Zuora, Inc. may not be used to endorse
* or promote products derived from this Software without specific prior written
* permission from Zuora, Inc.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
* ZUORA, INC. BE LIABLE FOR ANY DIRECT, INDIRECT OR CONSEQUENTIAL DAMAGES
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
* ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/

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 the ProductRatePlan 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 and Id fields for all of the ProductRatePlan 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.