Knowledge Center

Knowledge Center > API > SOAP API > Getting Started with the SOAP API

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:

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.

Open the Zuora UI and use the following menu path to download the latest WSDL file:

Z-Billing > Admin > Download the Zuora WSDL

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.

Get the Latest Zuora WSDL

You need to download the latest Zuora WSDL. The WSDL defines the interface for Zuora.

  1. Log in to Zuora.
  2. Select the following menu option: 
    Settings > Z-Billing Settings > Download the Zuora WSDL

​If your account doesn't have administrative access, contact your Zuora representative.

After you set up your SOAP environment, import this WSDL file into your environment.

Access an Older Version of the Zuora WSDL

To access an older version of the WSDL, use one of the following addresses, replacing XX.X, such as 63.0, with the version you want to download:

Zuora Environment WSDL RL 
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

Omitting the version parameter will retrieve the latest WSDL version.

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 AccountSubscriptionProductRatePlan, 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:

  1. 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.
  2. Download the php-tools pack into your web root directory.
  3. Download the latest version of the Zuora WSDL into the php-tools folder.

To check your installation:

  1. Start your local web server.
  2. 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).

  1. Open your browser and navigate to your php-tools folder.
  2. Log in to your server.
  3. Enter the following ZOQL query in the query text field:
    select id, name from Product
  4. 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.
File:z_Zuora_Internal/Implementation_Guide:_Seed_Edition/K_Use_the_Z-Commerce_APIs/Y_Zuora_API_Utility/API-utility-example-3.gif
  1. Enter the following ZOQL query:
    select id, name from ProductRatePlan where productid = '4028e4852ebd1027012ed8dc5aa36b83'
  2. Uncheck the Refresh? checkbox so that you don't have to re-enter your password.
  3. 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.
File:z_Zuora_Internal/Implementation_Guide:_Seed_Edition/K_Use_the_Z-Commerce_APIs/Y_Zuora_API_Utility/API-utility-example-4.gif

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.

Last modified
20:03, 24 Oct 2016

Tags

Classifications

(not set)