Skip to main content

SOAP API Calls

Zuora

SOAP API Calls

The calls in the Zuora SOAP API can be thought of as functioning much like verbs do in human languages: They are the actions that you perform. In human languages, verbs act upon objects, so in this case, the API calls are the actions you perform upon the Zuora SOAP API objects.

Zuora's SOAP API offers Create, Read, Update, and Delete (CRUD) capabilities. In this API, we use the term query instead of read.

Using the SOAP API Calls

The Zuora SOAP API calls can be thought of as verbs, because they perform the CRUD actions on the API objects. Using the calls, you can perform various tasks:

  • Logging into the Zuora server  Use login call to allow you receive information for subsequent calls
  • Creating, updating, and deleting various types of information. Use the createupdate, or delete call
  • Querying account information. Use the query call

As an alternative, you can use the subscribe call, which is an all-in-one solution for creating a request to subscribe to a service.

If you have the Invoice Settlement feature enabled, Zuora does not support generating credit memos with the API calls.

The XML of your calls must follow this format:

  1. Header
  2. Body
  3. Operation (for example, create)
  4. Request
  5. Object name
  6. Fields for the object
  7. Additional operations

Except for the login call, use only one header per call.

Properties of the SOAP API Calls

All Zuora API calls are:

  • Service requests and responses: Using the SOAP API, your client application prepares and submits a service request to the Zuora Web service. The Web service processes that request and returns a response, which your client application handles.
  • Synchronous only (asynchronous calls are not supported): Once your client application makes a request, it waits until it receives a response from the service before taking further action.
  • Committed automatically: Every operation that writes to an object is committed automatically. This can be compared to the AUTOCOMMMIT setting in SQL. For createupdate, and delete, if you attempt to write to more than one record in an object, the write operation for each record is treated as a separate transaction. For example, if a client application attempts to create two new accounts, those accounts are created using mutually exclusive insert operations that succeed or fail individually, not as a group.

Your client applications may need to handle failures if a requested operation could not be completed.

Concurrent Request Limits

Zuora employs a number of tenant-level concurrent request limits to maximize the stability of its service.

If the Multi-entity feature is enabled in your tenant, the concurrent request limits are enforced on the entity-level. Each entity is subject to the concurrent request limits individually.

Concurrent request limit types

Zuora applies different request limits to different types of requests. The request limits are:

  • Total Request limit - 40 concurrent requests by default
    Most UI and API requests are counted towards your Total Request limit.
    Some requests require a large amount of processing or data transfer. The following additional concurrent limits apply to such requests:

    • Big Process Request limit - 20 concurrent requests by default. All big process requests are also counted towards your Total Request limit. The requests that require heavy database operations are big process requests. For example, requests for retrieving payments for a specified account. See the Big Process Requests table below for more information.

    • Big Data Request limit - 20 concurrent requests by default. All big data requests are also counted towards your Total Request limit.

  • Custom Request limit - 200 concurrent requests by default. Custom requests are NOT counted towards your Total Request limit.

See the following table for the concurrent request limits that apply to different product areas.

Product Area Operations Total Request Limit Big Data Request Limit Big Process Request Limit Custom Request Limit

Subscriptions

Subscribe and amend REST method calls:

Subscribe and amend SOAP calls, and the corresponding Action calls in the Zuora API Reference:

      checkmarkGreen_xsm.png
Orders

Orders:

  • Preview order
  • Create order
      checkmarkGreen_xsm.png

Orders:

  • All requests except Preview order and Create order
checkmarkGreen_xsm.png      
Login Login Requests:
  • Login API calls (REST and SOAP) 
  • UI login requests

(No applicable concurrent limit for Login requests)

       
HPM

Hosted Payment Method Pages:

      checkmarkGreen_xsm.png
CPQ Zuora 360 Order Builder (includes APEX wrappers for SOAP APIs) checkmarkGreen_xsm.png      
Zuora for Salesforce
  • 360 Sync
  • Zuora Quotes

(No applicable concurrent limit)

       
AQuA AQuA API requests
  • Post query
  • Get job results
  • Get results files
checkmarkGreen_xsm.png      
AQuA results files download checkmarkGreen_xsm.png checkmarkGreen_xsm.png    
Usage

Usage request

  • Post usage
checkmarkGreen_xsm.png checkmarkGreen_xsm.png    

Usage request

  • Check import status
checkmarkGreen_xsm.png      
Data Source Export Data source file download checkmarkGreen_xsm.png checkmarkGreen_xsm.png    
Invoicing

Transactions

  • Get payments
checkmarkGreen_xsm.png   checkmarkGreen_xsm.png  

Big process requests

SOAP API calls on some objects are handled as Big Process Requests. See the following table for details. The corresponding REST API Actions are also handled as big process requests.

SOAP API Calls Objects
Create invoice
Generate invoice
QueryMore

Account

InvoiceItem

PaymentTransactionLog

RatePlan

RatePlanCharge

RatePlanChargeTier

Subscription

Query

Account

Invoice

InvoicePayment

Payment

PaymentTransactionLog

RatePlan

RatePlanCharge

Subscription

Usage

Errors when reaching concurrent request limits

You will encounter the following error codes, error messages, or HTTP status codes:

Request Type Error Code Error Message HTTP Status Code - Response Header
User Interface N/A "The total number of concurrent requests has exceeded the limit allowed by the system. Please resubmit your request later."

N/A

REST API 50000070 "The total number of concurrent requests has exceeded the limit allowed by the system. Please resubmit your request later."

HTTP Status:429

Response Header:  “Retry-After:120"

SOAP API, version 51.0 and later

<fns:FaultCode>
REQUEST_EXCEEDED_LIMIT
</fns:FaultCode>

<fns:FaultMessage>
The total number of concurrent requests has exceeded the limit allowed by the system. Please resubmit your request later.
</fns:FaultMessage>

HTTP Status:429

Response Header:  “Retry-After:120"

SOAP API, versions prior to 51.0

<fns:FaultCode>
UNKNOWN_ERROR </fns:FaultCode>

<fns:FaultMessage>
The total number of concurrent requests has exceeded the limit allowed by the system. Please resubmit your request later.
</fns:FaultMessage>

HTTP Status:429

Response Header:  “Retry-After:120"

File Download API N/A "The total number of concurrent requests has exceeded the limit allowed by the system. Please resubmit your request later."

HTTP Status:429

Response Header:  “Retry-After:120"

Zuora recommends that you retry sending the request after 120 seconds.

We recommend that you test your integration in Zuora Sandbox and make sure you do not hit the concurrent request limits. Contact Zuora Global Support if you require additional assistance.