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 create, update, 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:
- Header
- Body
- Operation (for example, create)
- Request
- Object name
- Fields for the object
- 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
create
,update
, anddelete
, 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
See Concurrent Request Limits.
Limitation on Memo PDF
Up to 20,000 line items are allowed in a single memo PDF.
Limitation on Invoice PDF
Zuora limits the sum total of certain line items up to a maximum number in a single invoice. For example, the sum total of line items for invoice items, taxation items, and usage items in a single invoice cannot exceed 20,000.
Maximum sum total of 20,000 is allowed for the following line items:
- invoice item
- taxation item
- usage item
Maximum sum total of 2,000 is allowed for the following line items:
- credit balance adjustment
- invoice adjustment
- invoice item adjustment
- payment
- refund
Maximum sum total of 2,000 is allowed for the following line items:
- subscription
- rate plan
When generating an invoice PDF, if the maximum number is exceeded, an error message is generated.
Amendments per Subscription
Zuora recommends that you create no more than 100 amendments on a subscription to ensure high performance of the subscriptions. The limit of amendments allowed on a subscription is 1000. However, if you create more than 100 amendments, the performance may be severely degraded, depending on the products and charges set up in your subscription.
If the renewal term period of the latest version of the subscription is Day or Week, the limit of amendments allowed on a subscription is 100.
The 100 amendment limit does not apply to Orders. See Orders Performance Guidance for more information.
Limitations on Orders
Zuora has the following limits on the Orders synchronous API to prevent performance degradation:
- Up to 50 subscriptions are allowed in a single Create order or Preview order operation call.
- Up to 50 order actions are allowed in a single Create order or Preview order operation call.
- Up to 50 order actions are allowed on a single subscription in a Create order or Preview order operation call.
If you have an Order that exceeds any limits of the above, Zuora recommends you use the following asynchronous API operations:
Zuora has the following limits on the Orders asynchronous API operations to prevent performance degradation:
- Up to 300 subscriptions are allowed in a single Create order asynchronously or Preview order asynchronously operation call.
- Up to 300 order actions are allowed in a single Create order asynchronously or Preview order asynchronously operation call.
- Up to 300 order actions are allowed on a single subscription in a Create order asynchronously or Preview order asynchronously operation call.
If you have a need for a large order that exceeds any limits of the above, you can request a limit increase for the Orders asynchronous API by submitting a request at Zuora Global Support.