Mock sample for your project: Branch Locator API
Integrate with "Branch Locator API" from hsbc.com in no time with Mockoon's ready to use mock sample
Branch Locator API
hsbc.com
Version: 2.2.1
Speed up your application development by using "Branch Locator API" ready-to-use mock sample. Mocking this API will allow you to start working in no time. No more accounts to create, API keys to provision, accesses to configure, unplanned downtime, just work.
It also improves your integration tests' quality and reliability by accounting for random failures, slow response time, etc.
Description
Other APIs by hsbc.com
Other APIs in the same category
Fire Financial Services Business API
The fire.com API allows you to deeply integrate Business Account features into your application or back-office systems.
The API provides read access to your profile, accounts and transactions, event-driven notifications of activity on the account and payment initiation via batches. Each feature has its own HTTP endpoint and every endpoint has its own permission.
The API exposes 3 main areas of functionality: financial functions, service information and service configuration.
Financial Functions
These functions provide access to your account details, transactions, payee accounts, payment initiation etc.
Service Functions
These provide information about the fees and limits applied to your account.
Service configuration
These provide information about your service configs - applications, webhooks, API tokens, etc.
The API provides read access to your profile, accounts and transactions, event-driven notifications of activity on the account and payment initiation via batches. Each feature has its own HTTP endpoint and every endpoint has its own permission.
The API exposes 3 main areas of functionality: financial functions, service information and service configuration.
Financial Functions
These functions provide access to your account details, transactions, payee accounts, payment initiation etc.
Service Functions
These provide information about the fees and limits applied to your account.
Service configuration
These provide information about your service configs - applications, webhooks, API tokens, etc.
Event Notification API Specification - TPP Endpoints
openbanking.org.uk
Swagger for Event Notification API Specification - TPP Endpoints
Paylocity API
paylocity.com
For general questions and support of the API, contact: [email protected]
Overview
Paylocity Web Services API is an externally facing RESTful Internet protocol. The Paylocity API uses HTTP verbs and a RESTful endpoint structure. OAuth 2.0 is used as the API Authorization framework. Request and response payloads are formatted as JSON.
Paylocity supports v1 and v2 versions of its API endpoints. v1, while supported, won't be enhanced with additional functionality. For direct link to v1 documentation, please click here. For additional resources regarding v1/v2 differences and conversion path, please contact [email protected].
Setup
Paylocity will provide the secure client credentials and set up the scope (type of requests and allowed company numbers). You will receive the unique client id, secret, and Paylocity public key for the data encryption. The secret will expire in 365 days.
Paylocity will send you an e-mail 10 days prior to the expiration date for the current secret. If not renewed, the second e-mail notification will be sent 5 days prior to secret's expiration. Each email will contain the code necessary to renew the client secret.
You can obtain the new secret by calling API endpoint using your current not yet expired credentials and the code that was sent with the notification email. For details on API endpoint, please see Client Credentials section.
Both the current secret value and the new secret value will be recognized during the transition period. After the current secret expires, you must use the new secret.
If you were unable to renew the secret via API endpoint, you can still contact Service and they will email you new secret via secure email.
When validating the request, Paylocity API will honor the defaults and required fields set up for the company default New Hire Template as defined in Web Pay.
Authorization
Paylocity Web Services API uses OAuth2.0 Authentication with JSON Message Format.
All requests of the Paylocity Web Services API require a bearer token which can be obtained by authenticating the client with the Paylocity Web Services API via OAuth 2.0.
The client must request a bearer token from the authorization endpoint:
auth-server for production: https://api.paylocity.com/IdentityServer/connect/token
auth-server for testing: https://apisandbox.paylocity.com/IdentityServer/connect/token
Paylocity reserves the right to impose rate limits on the number of calls made to our APIs. Changes to API features/functionality may be made at anytime with or without prior notice.
Authorization Header
The request is expected to be in the form of a basic authentication request, with the "Authorization" header containing the client-id and client-secret. This means the standard base-64 encoded user:password, prefixed with "Basic" as the value for the Authorization header, where user is the client-id and password is the client-secret.
Content-Type Header
The "Content-Type" header is required to be "application/x-www-form-urlencoded".
Additional Values
The request must post the following form encoded values within the request body:
granttype = clientcredentials
scope = WebLinkAPI
Responses
Success will return HTTP 200 OK with JSON content:
{
"access_token": "xxx",
"expires_in": 3600,
"token_type": "Bearer"
}
Encryption
Paylocity uses a combination of RSA and AES cryptography. As part of the setup, each client is issued a public RSA key.
Paylocity recommends the encryption of the incoming requests as additional protection of the sensitive data. Clients can opt-out of the encryption during the initial setup process. Opt-out will allow Paylocity to process unencrypted requests.
The Paylocity Public Key has the following properties:
2048 bit key size
PKCS1 key format
PEM encoding
Properties
key (base 64 encoded): The AES symmetric key encrypted with the Paylocity Public Key. It is the key used to encrypt the content. Paylocity will decrypt the AES key using RSA decryption and use it to decrypt the content.
iv (base 64 encoded): The AES IV (Initialization Vector) used when encrypting the content.
content (base 64 encoded): The AES encrypted request. The key and iv provided in the secureContent request are used by Paylocity for decryption of the content.
We suggest using the following for the AES:
CBC cipher mode
PKCS7 padding
128 bit block size
256 bit key size
Encryption Flow
Generate the unencrypted JSON payload to POST/PUT
Encrypt this JSON payload using your own key and IV (NOT with the Paylocity public key)
RSA encrypt the key you used in step 2 with the Paylocity Public Key, then, base64 encode the result
Base64 encode the IV used to encrypt the JSON payload in step 2
Put together a "securecontent" JSON object:
{
'secureContent' : {
'key' : -- RSA-encrypted & base64 encoded key from step 3,
'iv' : -- base64 encoded iv from step 4
'content' -- content encrypted with your own key from step 2, base64 encoded
}
}
Sample Example
{
"secureContent": {
"key": "eS3aw6H/qzHMJ00gSi6gQ3xa08DPMazk8BFY96Pd99ODA==",
"iv": "NLyXMGq9svw0XO5aI9BzWw==",
"content": "gAEOiQltO1w+LzGUoIK8FiYbU42hug94EasSl7N+Q1w="
}
}
Sample C# Code
using Newtonsoft.Json;
using System;
using System.IO;
using System.Security.Cryptography;
using System.Text;
public class SecuredContent
{
[JsonProperty("key")]
public string Key { get; set; }
[JsonProperty("iv")]
public string Iv { get; set; }
[JsonProperty("content")]
public string Content { get; set; }
}
public class EndUserSecureRequestExample
{
public string CreateSecuredRequest(FileInfo paylocityPublicKey, string unsecuredJsonRequest)
{
string publicKeyXml = File.ReadAllText(paylocityPublicKey.FullName, Encoding.UTF8);
SecuredContent secureContent = this.CreateSecuredContent(publicKeyXml, unsecuredJsonRequest);
string secureRequest = JsonConvert.SerializeObject(new { secureContent });
return secureRequest;
}
private SecuredContent CreateSecuredContent(string publicKeyXml, string request)
{
using (AesCryptoServiceProvider aesCsp = new AesCryptoServiceProvider())
{
aesCsp.Mode = CipherMode.CBC;
aesCsp.Padding = PaddingMode.PKCS7;
aesCsp.BlockSize = 128;
aesCsp.KeySize = 256;
using (ICryptoTransform crt = aesCsp.CreateEncryptor(aesCsp.Key, aesCsp.IV))
{
using (MemoryStream outputStream = new MemoryStream())
{
using (CryptoStream encryptStream = new CryptoStream(outputStream, crt, CryptoStreamMode.Write))
{
byte[] encodedRequest = Encoding.UTF8.GetBytes(request);
encryptStream.Write(encodedRequest, 0, encodedRequest.Length);
encryptStream.FlushFinalBlock();
byte[] encryptedRequest = outputStream.ToArray();
using (RSACryptoServiceProvider crp = new RSACryptoServiceProvider())
{
crp.FromXmlstring(publicKeyXml);
byte[] encryptedKey = crp.Encrypt(aesCsp.Key, false);
return new SecuredContent()
{
Key = Convert.ToBase64string(encryptedKey),
Iv = Convert.ToBase64string(aesCsp.IV),
Content = Convert.ToBase64string(encryptedRequest)
};
}
}
}
}
}
}
}
Support
Questions about using the Paylocity API? Please contact [email protected].
Deductions (v1)
Deductions API provides endpoints to retrieve, add, update and delete deductions for a company's employees. For schema details, click here.
OnBoarding (v1)
Onboarding API sends employee data into Paylocity Onboarding to help ensure an easy and accurate hiring process for subsequent completion into Web Pay. For schema details, click here.
Overview
Paylocity Web Services API is an externally facing RESTful Internet protocol. The Paylocity API uses HTTP verbs and a RESTful endpoint structure. OAuth 2.0 is used as the API Authorization framework. Request and response payloads are formatted as JSON.
Paylocity supports v1 and v2 versions of its API endpoints. v1, while supported, won't be enhanced with additional functionality. For direct link to v1 documentation, please click here. For additional resources regarding v1/v2 differences and conversion path, please contact [email protected].
Setup
Paylocity will provide the secure client credentials and set up the scope (type of requests and allowed company numbers). You will receive the unique client id, secret, and Paylocity public key for the data encryption. The secret will expire in 365 days.
Paylocity will send you an e-mail 10 days prior to the expiration date for the current secret. If not renewed, the second e-mail notification will be sent 5 days prior to secret's expiration. Each email will contain the code necessary to renew the client secret.
You can obtain the new secret by calling API endpoint using your current not yet expired credentials and the code that was sent with the notification email. For details on API endpoint, please see Client Credentials section.
Both the current secret value and the new secret value will be recognized during the transition period. After the current secret expires, you must use the new secret.
If you were unable to renew the secret via API endpoint, you can still contact Service and they will email you new secret via secure email.
When validating the request, Paylocity API will honor the defaults and required fields set up for the company default New Hire Template as defined in Web Pay.
Authorization
Paylocity Web Services API uses OAuth2.0 Authentication with JSON Message Format.
All requests of the Paylocity Web Services API require a bearer token which can be obtained by authenticating the client with the Paylocity Web Services API via OAuth 2.0.
The client must request a bearer token from the authorization endpoint:
auth-server for production: https://api.paylocity.com/IdentityServer/connect/token
auth-server for testing: https://apisandbox.paylocity.com/IdentityServer/connect/token
Paylocity reserves the right to impose rate limits on the number of calls made to our APIs. Changes to API features/functionality may be made at anytime with or without prior notice.
Authorization Header
The request is expected to be in the form of a basic authentication request, with the "Authorization" header containing the client-id and client-secret. This means the standard base-64 encoded user:password, prefixed with "Basic" as the value for the Authorization header, where user is the client-id and password is the client-secret.
Content-Type Header
The "Content-Type" header is required to be "application/x-www-form-urlencoded".
Additional Values
The request must post the following form encoded values within the request body:
granttype = clientcredentials
scope = WebLinkAPI
Responses
Success will return HTTP 200 OK with JSON content:
{
"access_token": "xxx",
"expires_in": 3600,
"token_type": "Bearer"
}
Encryption
Paylocity uses a combination of RSA and AES cryptography. As part of the setup, each client is issued a public RSA key.
Paylocity recommends the encryption of the incoming requests as additional protection of the sensitive data. Clients can opt-out of the encryption during the initial setup process. Opt-out will allow Paylocity to process unencrypted requests.
The Paylocity Public Key has the following properties:
2048 bit key size
PKCS1 key format
PEM encoding
Properties
key (base 64 encoded): The AES symmetric key encrypted with the Paylocity Public Key. It is the key used to encrypt the content. Paylocity will decrypt the AES key using RSA decryption and use it to decrypt the content.
iv (base 64 encoded): The AES IV (Initialization Vector) used when encrypting the content.
content (base 64 encoded): The AES encrypted request. The key and iv provided in the secureContent request are used by Paylocity for decryption of the content.
We suggest using the following for the AES:
CBC cipher mode
PKCS7 padding
128 bit block size
256 bit key size
Encryption Flow
Generate the unencrypted JSON payload to POST/PUT
Encrypt this JSON payload using your own key and IV (NOT with the Paylocity public key)
RSA encrypt the key you used in step 2 with the Paylocity Public Key, then, base64 encode the result
Base64 encode the IV used to encrypt the JSON payload in step 2
Put together a "securecontent" JSON object:
{
'secureContent' : {
'key' : -- RSA-encrypted & base64 encoded key from step 3,
'iv' : -- base64 encoded iv from step 4
'content' -- content encrypted with your own key from step 2, base64 encoded
}
}
Sample Example
{
"secureContent": {
"key": "eS3aw6H/qzHMJ00gSi6gQ3xa08DPMazk8BFY96Pd99ODA==",
"iv": "NLyXMGq9svw0XO5aI9BzWw==",
"content": "gAEOiQltO1w+LzGUoIK8FiYbU42hug94EasSl7N+Q1w="
}
}
Sample C# Code
using Newtonsoft.Json;
using System;
using System.IO;
using System.Security.Cryptography;
using System.Text;
public class SecuredContent
{
[JsonProperty("key")]
public string Key { get; set; }
[JsonProperty("iv")]
public string Iv { get; set; }
[JsonProperty("content")]
public string Content { get; set; }
}
public class EndUserSecureRequestExample
{
public string CreateSecuredRequest(FileInfo paylocityPublicKey, string unsecuredJsonRequest)
{
string publicKeyXml = File.ReadAllText(paylocityPublicKey.FullName, Encoding.UTF8);
SecuredContent secureContent = this.CreateSecuredContent(publicKeyXml, unsecuredJsonRequest);
string secureRequest = JsonConvert.SerializeObject(new { secureContent });
return secureRequest;
}
private SecuredContent CreateSecuredContent(string publicKeyXml, string request)
{
using (AesCryptoServiceProvider aesCsp = new AesCryptoServiceProvider())
{
aesCsp.Mode = CipherMode.CBC;
aesCsp.Padding = PaddingMode.PKCS7;
aesCsp.BlockSize = 128;
aesCsp.KeySize = 256;
using (ICryptoTransform crt = aesCsp.CreateEncryptor(aesCsp.Key, aesCsp.IV))
{
using (MemoryStream outputStream = new MemoryStream())
{
using (CryptoStream encryptStream = new CryptoStream(outputStream, crt, CryptoStreamMode.Write))
{
byte[] encodedRequest = Encoding.UTF8.GetBytes(request);
encryptStream.Write(encodedRequest, 0, encodedRequest.Length);
encryptStream.FlushFinalBlock();
byte[] encryptedRequest = outputStream.ToArray();
using (RSACryptoServiceProvider crp = new RSACryptoServiceProvider())
{
crp.FromXmlstring(publicKeyXml);
byte[] encryptedKey = crp.Encrypt(aesCsp.Key, false);
return new SecuredContent()
{
Key = Convert.ToBase64string(encryptedKey),
Iv = Convert.ToBase64string(aesCsp.IV),
Content = Convert.ToBase64string(encryptedRequest)
};
}
}
}
}
}
}
}
Support
Questions about using the Paylocity API? Please contact [email protected].
Deductions (v1)
Deductions API provides endpoints to retrieve, add, update and delete deductions for a company's employees. For schema details, click here.
OnBoarding (v1)
Onboarding API sends employee data into Paylocity Onboarding to help ensure an easy and accurate hiring process for subsequent completion into Web Pay. For schema details, click here.
Chaingateway.io
chaingateway.io
Chaingateway.io
REST API to build the bridge between Ethereum and the real world
Please check out our website for detailed information about this API.
To use our API, you need an API Key (Described as Authorization header in the examples below).
To get one, please create an account on our website.
For our internal documentation, please check out our Docs Site.
If you need help with integrating our API in your application, you can reach us via email or join our official Telegram group.
REST API to build the bridge between Ethereum and the real world
Please check out our website for detailed information about this API.
To use our API, you need an API Key (Described as Authorization header in the examples below).
To get one, please create an account on our website.
For our internal documentation, please check out our Docs Site.
If you need help with integrating our API in your application, you can reach us via email or join our official Telegram group.
The Consumer Financial Protection Bureau
Learn more about home mortgage data, download the data yourself, or build new tools using our API.
Big Red Cloud API
bigredcloud.com
Welcome to the Big Red Cloud API
This API enables programmatic access to Big Red Cloud data.
We have used Swagger to auto generate the API documentation on this page, and it also enables direct interaction with the API in this page.
To get started, you will require an API Key - check out our guide at https://www.bigredcloud.com/support/generating-api-key-guide/ for information on how to get one.
Use the 'Enter API Key' button below to enter your API key and start interacting with your Big Red Cloud data right on this page.
The API key will be stored in your browsers local storage for convenience, but you will be able to delete it at any time if you wish.
For additional information on the API, check out our support article at https://www.bigredcloud.com/support/api/
This API enables programmatic access to Big Red Cloud data.
We have used Swagger to auto generate the API documentation on this page, and it also enables direct interaction with the API in this page.
To get started, you will require an API Key - check out our guide at https://www.bigredcloud.com/support/generating-api-key-guide/ for information on how to get one.
Use the 'Enter API Key' button below to enter your API key and start interacting with your Big Red Cloud data right on this page.
The API key will be stored in your browsers local storage for convenience, but you will be able to delete it at any time if you wish.
For additional information on the API, check out our support article at https://www.bigredcloud.com/support/api/
API Reference: Billing
zuora.com
Introduction
Welcome to the reference for the Zuora Billing REST API!
To learn about the common use cases of Zuora Billing REST APIs, check out the API Guides.
In addition to Zuora API Reference; Billing, we also provide API references for other Zuora products:
API Reference: Collect
API Reference: Revenue
The Zuora REST API provides a broad set of operations and resources that:
Enable Web Storefront integration from your website.
Support self-service subscriber sign-ups and account management.
Process revenue schedules through custom revenue rule models.
Enable manipulation of most objects in the Zuora Billing Object Model.
Want to share your opinion on how our API works for you? Tell us how you feel about using our API and what we can do to make it better.
Access to the API
If you have a Zuora tenant, you can access the Zuora REST API via one of the following endpoints:
| Tenant | Base URL for REST Endpoints |
|-------------------------|-------------------------|
|US Production | https://rest.zuora.com |
|US API Sandbox | https://rest.apisandbox.zuora.com|
|US Performance Test | https://rest.pt1.zuora.com |
|US Production Copy | Submit a request at Zuora Global Support to enable the Zuora REST API in your tenant and obtain the base URL for REST endpoints. See REST endpoint base URL of Production Copy (Service) Environment for existing and new customers for more information. |
|US Cloud Production | https://rest.na.zuora.com |
|US Cloud API Sandbox | https://rest.sandbox.na.zuora.com |
|US Central Sandbox | https://rest.test.zuora.com |
|EU Production | https://rest.eu.zuora.com |
|EU API Sandbox | https://rest.sandbox.eu.zuora.com |
|EU Central Sandbox | https://rest.test.eu.zuora.com |
The Production endpoint provides access to your live user data. Sandbox tenants are a good place to test code without affecting real-world data. If you would like Zuora to provision a Sandbox tenant for you, contact your Zuora representative for assistance.
If you do not have a Zuora tenant, go to https://www.zuora.com/resource/zuora-test-drive and sign up for a Production Test Drive tenant. The tenant comes with seed data, including a sample product catalog.
API Changelog
You can find the Changelog of the API Reference: Billing in the Zuora Community.
Authentication
OAuth v2.0
Zuora recommends that you use OAuth v2.0 to authenticate to the Zuora REST API. Currently, OAuth is not available in every environment. See Zuora Testing Environments for more information.
Zuora recommends you to create a dedicated API user with API write access on a tenant when authenticating via OAuth, and then create an OAuth client for this user. See Create an API User for how to do this. By creating a dedicated API user, you can control permissions of the API user without affecting other non-API users.
If a user is deactivated, all of the user's OAuth clients will be automatically deactivated.
Authenticating via OAuth requires the following steps:
Create a Client
Generate a Token
Make Authenticated Requests
Create a Client
You must first create an OAuth client in the Zuora UI. To do this, you must be an administrator of your Zuora tenant. This is a one-time operation. You will be provided with a Client ID and a Client Secret. Please note this information down, as it will be required for the next step.
Note: The OAuth client will be owned by a Zuora user account. If you want to perform PUT, POST, or DELETE operations using the OAuth client, the owner of the OAuth client must have a Platform role that includes the "API Write Access" permission.
Generate a Token
After creating a client, you must make a call to obtain a bearer token using the Generate an OAuth token operation. This operation requires the following parameters:
client_id - the Client ID displayed when you created the OAuth client in the previous step
client_secret - the Client Secret displayed when you created the OAuth client in the previous step
granttype - must be set to clientcredentials
Note: The Client ID and Client Secret mentioned above were displayed when you created the OAuth Client in the prior step. The Generate an OAuth token response specifies how long the bearer token is valid for. You should reuse the bearer token until it is expired. When the token is expired, call Generate an OAuth token again to generate a new one.
Make Authenticated Requests
To authenticate subsequent API requests, you must provide a valid bearer token in an HTTP header:
Authorization: Bearer {bearer_token}
If you have Zuora Multi-entity enabled, you need to set an additional header to specify the ID of the entity that you want to access. You can use the scope field in the Generate an OAuth token response to determine whether you need to specify an entity ID.
If the scope field contains more than one entity ID, you must specify the ID of the entity that you want to access. For example, if the scope field contains entity.1a2b7a37-3e7d-4cb3-b0e2-883de9e766cc and entity.c92ed977-510c-4c48-9b51-8d5e848671e9, specify one of the following headers:
Zuora-Entity-Ids: 1a2b7a37-3e7d-4cb3-b0e2-883de9e766cc
Zuora-Entity-Ids: c92ed977-510c-4c48-9b51-8d5e848671e9
Note: For a limited period of time, Zuora will accept the entityId header as an alternative to the Zuora-Entity-Ids header. If you choose to set the entityId header, you must remove all "-" characters from the entity ID in the scope field.
If the scope field contains a single entity ID, you do not need to specify an entity ID.
Other Supported Authentication Schemes
Zuora continues to support the following additional legacy means of authentication:
Use username and password. Include authentication with each request in the header:
apiAccessKeyId
apiSecretAccessKey
Zuora recommends that you create an API user specifically for making API calls. See Create an API User for more information.
Use an authorization cookie. The cookie authorizes the user to make calls to the REST API for the duration specified in Administration > Security Policies > Session timeout. The cookie expiration time is reset with this duration after every call to the REST API. To obtain a cookie, call the Connections resource with the following API user information:
ID
Password
For CORS-enabled APIs only: Include a 'single-use' token in the request header, which re-authenticates the user with each request. See below for more details.
Entity Id and Entity Name
The entityId and entityName parameters are only used for Zuora Multi-entity. These are the legacy parameters that Zuora will only continue to support for a period of time. Zuora recommends you to use the Zuora-Entity-Ids parameter instead.
The entityId and entityName parameters specify the Id and the name of the entity that you want to access, respectively. Note that you must have permission to access the entity.
You can specify either the entityId or entityName parameter in the authentication to access and view an entity.
If both entityId and entityName are specified in the authentication, an error occurs.
If neither entityId nor entityName is specified in the authentication, you will log in to the entity in which your user account is created.
To get the entity Id and entity name, you can use the GET Entities REST call. For more information, see API User Authentication.
Token Authentication for CORS-Enabled APIs
The CORS mechanism enables REST API calls to Zuora to be made directly from your customer's browser, with all credit card and security information transmitted directly to Zuora. This minimizes your PCI compliance burden, allows you to implement advanced validation on your payment forms, and makes your payment forms look just like any other part of your website.
For security reasons, instead of using cookies, an API request via CORS uses tokens for authentication.
The token method of authentication is only designed for use with requests that must originate from your customer's browser; it should not be considered a replacement to the existing cookie authentication mechanism.
See Zuora CORS REST for details on how CORS works and how you can begin to implement customer calls to the Zuora REST APIs. See HMAC Signatures for details on the HMAC method that returns the authentication token.
Requests and Responses
Request IDs
As a general rule, when asked to supply a "key" for an account or subscription (accountKey, account-key, subscriptionKey, subscription-key), you can provide either the actual ID or the number of the entity.
HTTP Request Body
Most of the parameters and data accompanying your requests will be contained in the body of the HTTP request.
The Zuora REST API accepts JSON in the HTTP request body. No other data format (e.g., XML) is supported.
Data Type
(Actions and CRUD operations only) We recommend that you do not specify the decimal values with quotation marks, commas, and spaces. Use characters of +-0-9.eE, for example, 5, 1.9, -8.469, and 7.7e2. Also, Zuora does not convert currencies for decimal values.
Testing a Request
Use a third party client, such as curl, Postman, or Advanced REST Client, to test the Zuora REST API.
You can test the Zuora REST API from the Zuora API Sandbox or Production tenants. If connecting to Production, bear in mind that you are working with your live production data, not sample data or test data.
Testing with Credit Cards
Sooner or later it will probably be necessary to test some transactions that involve credit cards. For suggestions on how to handle this, see [Going Live With Your Payment Gateway](https://knowledgecenter.zuora.com/CBBilling/MPaymentGateways/CManagingPaymentGateways/BGoingLivePaymentGateways#TestingwithCreditCards "CZuoraUserGuides/ABillingandPayments/MPaymentGateways/CManagingPaymentGateways/BGoingLivePaymentGateways#TestingwithCredit_Cards"
).
Concurrent Request Limits
Zuora enforces tenant-level concurrent request limits. See Concurrent Request Limits for more information.
Timeout Limit
If a request does not complete within 120 seconds, the request times out and Zuora returns a Gateway Timeout error.
Error Handling
If a request to Zuora Billing REST API with an endpoint starting with /v1 (except Actions and CRUD operations) fails, the response will contain an eight-digit error code with a corresponding error message to indicate the details of the error.
The following code snippet is a sample error response that contains an error code and message pair:
The success field indicates whether the API request has succeeded. The processId field is a Zuora internal ID that you can provide to Zuora Global Support for troubleshooting purposes.
The reasons field contains the actual error code and message pair. The error code begins with 5 or 6 means that you encountered a certain issue that is specific to a REST API resource in Zuora Billing. For example, 53100320 indicates that an invalid value is specified for the termType field of the subscription object.
The error code beginning with 9 usually indicates that an authentication-related issue occurred, and it can also indicate other unexpected errors depending on different cases. For example, 90000011 indicates that an invalid credential is provided in the request header.
When troubleshooting the error, you can divide the error code into two components: REST API resource code and error category code. See the following Zuora error code sample:
Note: Zuora determines resource codes based on the request payload. Therefore, if GET and DELETE requests that do not contain payloads fail, you will get 500000 as the resource code, which indicates an unknown object and an unknown field.
The error category code of these requests is valid and follows the rules described in the Error Category Code section.
In such case, you can refer to the returned error message to troubleshoot.
REST API Resource Code
The 6-digit resource code indicates the REST API resource, typically a field of a Zuora object, on which the issue occurs. In the preceding example, 531003 refers to the termType field of the subscription object.
The value range for all REST API resource codes is from 500000 to 679999. See Resource Codes in the Knowledge Center for a full list of resource codes.
Error Category Code
The 2-digit error category code identifies the type of error, for example, resource not found or missing required field.
The following table describes all error categories and the corresponding resolution:
| Code | Error category | Description | Resolution |
|:--------|:--------|:--------|:--------|
| 10 | Permission or access denied | The request cannot be processed because a certain tenant or user permission is missing. | Check the missing tenant or user permission in the response message and contact Zuora Global Support for enablement. |
| 11 | Authentication failed | Authentication fails due to invalid API authentication credentials. | Ensure that a valid API credential is specified. |
| 20 | Invalid format or value | The request cannot be processed due to an invalid field format or value. | Check the invalid field in the error message, and ensure that the format and value of all fields you passed in are valid. |
| 21 | Unknown field in request | The request cannot be processed because an unknown field exists in the request body. | Check the unknown field name in the response message, and ensure that you do not include any unknown field in the request body. |
| 22 | Missing required field | The request cannot be processed because a required field in the request body is missing. | Check the missing field name in the response message, and ensure that you include all required fields in the request body. |
| 30 | Rule restriction | The request cannot be processed due to the violation of a Zuora business rule. | Check the response message and ensure that the API request meets the specified business rules. |
| 40 | Not found | The specified resource cannot be found. | Check the response message and ensure that the specified resource exists in your Zuora tenant. |
| 45 | Unsupported request | The requested endpoint does not support the specified HTTP method. | Check your request and ensure that the endpoint and method matches. |
| 50 | Locking contention | This request cannot be processed because the objects this request is trying to modify are being modified by another API request, UI operation, or batch job process. | Resubmit the request first to have another try. If this error still occurs, contact Zuora Global Support with the returned Zuora-Request-Id value in the response header for assistance. |
| 60 | Internal error | The server encounters an internal error. | Contact Zuora Global Support with the returned Zuora-Request-Id value in the response header for assistance. |
| 70 | Request exceeded limit | The total number of concurrent requests exceeds the limit allowed by the system. | Resubmit the request after the number of seconds specified by the Retry-After value in the response header. Check Concurrent request limits for details about Zuora’s concurrent request limit policy. |
| 90 | Malformed request | The request cannot be processed due to JSON syntax errors. | Check the syntax error in the JSON request body and ensure that the request is in the correct JSON format. |
| 99 | Integration error | The server encounters an error when communicating with an external system, for example, payment gateway, tax engine provider. | Check the response message and take action accordingly. |
Pagination
When retrieving information (using GET methods), the optional pageSize query parameter sets the maximum number of rows to return in a response. The maximum is 40; larger values are treated as 40. If this value is empty or invalid, pageSize typically defaults to 10.
The default value for the maximum number of rows retrieved can be overridden at the method level.
If more rows are available, the response will include a nextPage element, which contains a URL for requesting the next page. If this value is not provided, no more rows are available. No "previous page" element is explicitly provided; to support backward paging, use the previous call.
Array Size
For data items that are not paginated, the REST API supports arrays of up to 300 rows. Thus, for instance, repeated pagination can retrieve thousands of customer accounts, but within any account an array of no more than 300 rate plans is returned.
API Versions
The Zuora REST API are version controlled. Versioning ensures that Zuora REST API changes are backward compatible. Zuora uses a major and minor version nomenclature to manage changes. By specifying a version in a REST request, you can get expected responses regardless of future changes to the API.
Major Version
The major version number of the REST API appears in the REST URL. Currently, Zuora only supports the v1 major version. For example, POST https://rest.zuora.com/v1/subscriptions.
Minor Version
Zuora uses minor versions for the REST API to control small changes. For example, a field in a REST method is deprecated and a new field is used to replace it.
Some fields in the REST methods are supported as of minor versions. If a field is not noted with a minor version, this field is available for all minor versions. If a field is noted with a minor version, this field is in version control. You must specify the supported minor version in the request header to process without an error.
If a field is in version control, it is either with a minimum minor version or a maximum minor version, or both of them. You can only use this field with the minor version between the minimum and the maximum minor versions. For example, the invoiceCollect field in the POST Subscription method is in version control and its maximum minor version is 189.0. You can only use this field with the minor version 189.0 or earlier.
If you specify a version number in the request header that is not supported, Zuora will use the minimum minor version of the REST API. In our REST API documentation, if a field or feature requires a minor version number, we note that in the field description.
You only need to specify the version number when you use the fields require a minor version. To specify the minor version, set the zuora-version parameter to the minor version number in the request header for the request call. For example, the collect field is in 196.0 minor version. If you want to use this field for the POST Subscription method, set the zuora-version parameter to 196.0 in the request header. The zuora-version parameter is case sensitive.
For all the REST API fields, by default, if the minor version is not specified in the request header, Zuora will use the minimum minor version of the REST API to avoid breaking your integration.
Minor Version History
The supported minor versions are not serial. This section documents the changes made to each Zuora REST API minor version.
The following table lists the supported versions and the fields that have a Zuora REST API minor version.
| Fields | Minor Version | REST Methods | Description |
|:--------|:--------|:--------|:--------|
| invoiceCollect | 189.0 and earlier | Create Subscription; Update Subscription; Renew Subscription; Cancel Subscription; Suspend Subscription; Resume Subscription; Create Account|Generates an invoice and collects a payment for a subscription. |
| collect | 196.0 and later | Create Subscription; Update Subscription; Renew Subscription; Cancel Subscription; Suspend Subscription; Resume Subscription; Create Account|Collects an automatic payment for a subscription. |
| invoice | 196.0 and 207.0| Create Subscription; Update Subscription; Renew Subscription; Cancel Subscription; Suspend Subscription; Resume Subscription; Create Account|Generates an invoice for a subscription. |
| invoiceTargetDate | 196.0 and earlier | Preview Subscription |Date through which charges are calculated on the invoice, as yyyy-mm-dd. |
| invoiceTargetDate | 207.0 and earlier | Create Subscription; Update Subscription; Renew Subscription; Cancel Subscription; Suspend Subscription; Resume Subscription; Create Account|Date through which charges are calculated on the invoice, as yyyy-mm-dd. |
| targetDate | 207.0 and later | Preview Subscription |Date through which charges are calculated on the invoice, as yyyy-mm-dd. |
| targetDate | 211.0 and later | Create Subscription; Update Subscription; Renew Subscription; Cancel Subscription; Suspend Subscription; Resume Subscription; Create Account|Date through which charges are calculated on the invoice, as yyyy-mm-dd. |
| includeExisting DraftInvoiceItems | 196.0 and earlier| Preview Subscription; Update Subscription | Specifies whether to include draft invoice items in subscription previews. Specify it to be true (default) to include draft invoice items in the preview result. Specify it to be false to excludes draft invoice items in the preview result. |
| includeExisting DraftDocItems | 207.0 and later | Preview Subscription; Update Subscription | Specifies whether to include draft invoice items in subscription previews. Specify it to be true (default) to include draft invoice items in the preview result. Specify it to be false to excludes draft invoice items in the preview result. |
| previewType | 196.0 and earlier| Preview Subscription; Update Subscription | The type of preview you will receive. The possible values are InvoiceItem(default), ChargeMetrics, and InvoiceItemChargeMetrics. |
| previewType | 207.0 and later | Preview Subscription; Update Subscription | The type of preview you will receive. The possible values are LegalDoc(default), ChargeMetrics, and LegalDocChargeMetrics. |
| runBilling | 211.0 and later | Create Subscription; Update Subscription; Renew Subscription; Cancel Subscription; Suspend Subscription; Resume Subscription; Create Account|Generates an invoice or credit memo for a subscription. Note: Credit memos are only available if you have the Invoice Settlement feature enabled. |
| invoiceDate | 214.0 and earlier | Invoice and Collect |Date that should appear on the invoice being generated, as yyyy-mm-dd. |
| invoiceTargetDate | 214.0 and earlier | Invoice and Collect |Date through which to calculate charges on this account if an invoice is generated, as yyyy-mm-dd. |
| documentDate | 215.0 and later | Invoice and Collect |Date that should appear on the invoice and credit memo being generated, as yyyy-mm-dd. |
| targetDate | 215.0 and later | Invoice and Collect |Date through which to calculate charges on this account if an invoice or a credit memo is generated, as yyyy-mm-dd. |
| memoItemAmount | 223.0 and earlier | Create credit memo from charge; Create debit memo from charge | Amount of the memo item. |
| amount | 224.0 and later | Create credit memo from charge; Create debit memo from charge | Amount of the memo item. |
| subscriptionNumbers | 222.4 and earlier | Create order | Container for the subscription numbers of the subscriptions in an order. |
| subscriptions | 223.0 and later | Create order | Container for the subscription numbers and statuses in an order. |
| creditTaxItems | 238.0 and earlier | Get credit memo items; Get credit memo item | Container for the taxation items of the credit memo item. |
| taxItems | 238.0 and earlier | Get debit memo items; Get debit memo item | Container for the taxation items of the debit memo item. |
| taxationItems | 239.0 and later | Get credit memo items; Get credit memo item; Get debit memo items; Get debit memo item | Container for the taxation items of the memo item. |
| chargeId | 256.0 and earlier | Create credit memo from charge; Create debit memo from charge | ID of the product rate plan charge that the memo is created from. |
| productRatePlanChargeId | 257.0 and later | Create credit memo from charge; Create debit memo from charge | ID of the product rate plan charge that the memo is created from. |
| comment | 256.0 and earlier | Create credit memo from charge; Create debit memo from charge; Create credit memo from invoice; Create debit memo from invoice; Get credit memo items; Get credit memo item; Get debit memo items; Get debit memo item | Comments about the product rate plan charge, invoice item, or memo item. |
| description | 257.0 and later | Create credit memo from charge; Create debit memo from charge; Create credit memo from invoice; Create debit memo from invoice; Get credit memo items; Get credit memo item; Get debit memo items; Get debit memo item | Description of the the product rate plan charge, invoice item, or memo item. |
Version 207.0 and Later
The response structure of the Preview Subscription and Update Subscription methods are changed. The following invoice related response fields are moved to the invoice container:
amount
amountWithoutTax
taxAmount
invoiceItems
targetDate
chargeMetrics
Zuora Billing Object Model
The following diagram is a high-level view of how key business objects are related to one another within Zuora Billing.
Click the diagram to open it in a new tab and zoom in.
For more information about the different sections of the diagram, see
Zuora Billing business object model.
This diagram is intended to provide a conceptual understanding; it does not illustrate a specific way to integrate with Zuora.
The diagram includes the Orders feature and the Invoice Settlement feature.
If your organization does not use either of these features, see
Zuora Billing business object model prior to Orders and Invoice Settlement
for an alternative diagram.
API Names
You can use the Describe object operation to list the fields of each Zuora object that is available in your tenant. When you call the operation, you must specify the API name of the Zuora object.
The following table provides the API name of each Zuora object:
| Object | API Name |
|-----------------------------------------------|--------------------------------------------|
| Account | Account |
| Accounting Code | AccountingCode |
| Accounting Period | AccountingPeriod |
| Amendment | Amendment |
| Application Group | ApplicationGroup |
| Billing Run | BillingRun - API name used in the Describe object operation, Export ZOQL queries, and Data Query. BillRun - API name used in the Actions. See the CRUD oprations of Bill Run for more information about the BillRun object. BillingRun and BillRun have different fields. |
| Contact | Contact |
| Contact Snapshot | ContactSnapshot |
| Credit Balance Adjustment | CreditBalanceAdjustment |
| Credit Memo | CreditMemo |
| Credit Memo Application | CreditMemoApplication |
| Credit Memo Application Item | CreditMemoApplicationItem |
| Credit Memo Item | CreditMemoItem |
| Credit Memo Part | CreditMemoPart |
| Credit Memo Part Item | CreditMemoPartItem |
| Credit Taxation Item | CreditTaxationItem |
| Custom Exchange Rate | FXCustomRate |
| Debit Memo | DebitMemo |
| Debit Memo Item | DebitMemoItem |
| Debit Taxation Item | DebitTaxationItem |
| Discount Applied Metrics | DiscountAppliedMetrics |
| Entity | Tenant |
| Feature | Feature |
| Gateway Reconciliation Event | PaymentGatewayReconciliationEventLog |
| Gateway Reconciliation Job | PaymentReconciliationJob |
| Gateway Reconciliation Log | PaymentReconciliationLog |
| Invoice | Invoice |
| Invoice Adjustment | InvoiceAdjustment |
| Invoice Item | InvoiceItem |
| Invoice Item Adjustment | InvoiceItemAdjustment |
| Invoice Payment | InvoicePayment |
| Journal Entry | JournalEntry |
| Journal Entry Item | JournalEntryItem |
| Journal Run | JournalRun |
| Order | Order |
| Order Action | OrderAction |
| Order ELP | OrderElp |
| Order Line Items | OrderLineItems |
| Order Item | OrderItem |
| Order MRR | OrderMrr |
| Order Quantity | OrderQuantity |
| Order TCB | OrderTcb |
| Order TCV | OrderTcv |
| Payment | Payment |
| Payment Application | PaymentApplication |
| Payment Application Item | PaymentApplicationItem |
| Payment Method | PaymentMethod |
| Payment Method Snapshot | PaymentMethodSnapshot |
| Payment Method Transaction Log | PaymentMethodTransactionLog |
| Payment Method Update | UpdaterDetail |
| Payment Part | PaymentPart |
| Payment Part Item | PaymentPartItem |
| Payment Run | PaymentRun |
| Payment Transaction Log | PaymentTransactionLog |
| Processed Usage | ProcessedUsage |
| Product | Product |
| Product Feature | ProductFeature |
| Product Rate Plan | ProductRatePlan |
| Product Rate Plan Charge | ProductRatePlanCharge |
| Product Rate Plan Charge Tier | ProductRatePlanChargeTier |
| Rate Plan | RatePlan |
| Rate Plan Charge | RatePlanCharge |
| Rate Plan Charge Tier | RatePlanChargeTier |
| Refund | Refund |
| Refund Application | RefundApplication |
| Refund Application Item | RefundApplicationItem |
| Refund Invoice Payment | RefundInvoicePayment |
| Refund Part | RefundPart |
| Refund Part Item | RefundPartItem |
| Refund Transaction Log | RefundTransactionLog |
| Revenue Charge Summary | RevenueChargeSummary |
| Revenue Charge Summary Item | RevenueChargeSummaryItem |
| Revenue Event | RevenueEvent |
| Revenue Event Credit Memo Item | RevenueEventCreditMemoItem |
| Revenue Event Debit Memo Item | RevenueEventDebitMemoItem |
| Revenue Event Invoice Item | RevenueEventInvoiceItem |
| Revenue Event Invoice Item Adjustment | RevenueEventInvoiceItemAdjustment |
| Revenue Event Item | RevenueEventItem |
| Revenue Event Item Credit Memo Item | RevenueEventItemCreditMemoItem |
| Revenue Event Item Debit Memo Item | RevenueEventItemDebitMemoItem |
| Revenue Event Item Invoice Item | RevenueEventItemInvoiceItem |
| Revenue Event Item Invoice Item Adjustment | RevenueEventItemInvoiceItemAdjustment |
| Revenue Event Type | RevenueEventType |
| Revenue Schedule | RevenueSchedule |
| Revenue Schedule Credit Memo Item | RevenueScheduleCreditMemoItem |
| Revenue Schedule Debit Memo Item | RevenueScheduleDebitMemoItem |
| Revenue Schedule Invoice Item | RevenueScheduleInvoiceItem |
| Revenue Schedule Invoice Item Adjustment | RevenueScheduleInvoiceItemAdjustment |
| Revenue Schedule Item | RevenueScheduleItem |
| Revenue Schedule Item Credit Memo Item | RevenueScheduleItemCreditMemoItem |
| Revenue Schedule Item Debit Memo Item | RevenueScheduleItemDebitMemoItem |
| Revenue Schedule Item Invoice Item | RevenueScheduleItemInvoiceItem |
| Revenue Schedule Item Invoice Item Adjustment | RevenueScheduleItemInvoiceItemAdjustment |
| Subscription | Subscription |
| Subscription Product Feature | SubscriptionProductFeature |
| Taxable Item Snapshot | TaxableItemSnapshot |
| Taxation Item | TaxationItem |
| Updater Batch | UpdaterBatch |
| Usage | Usage |
Welcome to the reference for the Zuora Billing REST API!
To learn about the common use cases of Zuora Billing REST APIs, check out the API Guides.
In addition to Zuora API Reference; Billing, we also provide API references for other Zuora products:
API Reference: Collect
API Reference: Revenue
The Zuora REST API provides a broad set of operations and resources that:
Enable Web Storefront integration from your website.
Support self-service subscriber sign-ups and account management.
Process revenue schedules through custom revenue rule models.
Enable manipulation of most objects in the Zuora Billing Object Model.
Want to share your opinion on how our API works for you? Tell us how you feel about using our API and what we can do to make it better.
Access to the API
If you have a Zuora tenant, you can access the Zuora REST API via one of the following endpoints:
| Tenant | Base URL for REST Endpoints |
|-------------------------|-------------------------|
|US Production | https://rest.zuora.com |
|US API Sandbox | https://rest.apisandbox.zuora.com|
|US Performance Test | https://rest.pt1.zuora.com |
|US Production Copy | Submit a request at Zuora Global Support to enable the Zuora REST API in your tenant and obtain the base URL for REST endpoints. See REST endpoint base URL of Production Copy (Service) Environment for existing and new customers for more information. |
|US Cloud Production | https://rest.na.zuora.com |
|US Cloud API Sandbox | https://rest.sandbox.na.zuora.com |
|US Central Sandbox | https://rest.test.zuora.com |
|EU Production | https://rest.eu.zuora.com |
|EU API Sandbox | https://rest.sandbox.eu.zuora.com |
|EU Central Sandbox | https://rest.test.eu.zuora.com |
The Production endpoint provides access to your live user data. Sandbox tenants are a good place to test code without affecting real-world data. If you would like Zuora to provision a Sandbox tenant for you, contact your Zuora representative for assistance.
If you do not have a Zuora tenant, go to https://www.zuora.com/resource/zuora-test-drive and sign up for a Production Test Drive tenant. The tenant comes with seed data, including a sample product catalog.
API Changelog
You can find the Changelog of the API Reference: Billing in the Zuora Community.
Authentication
OAuth v2.0
Zuora recommends that you use OAuth v2.0 to authenticate to the Zuora REST API. Currently, OAuth is not available in every environment. See Zuora Testing Environments for more information.
Zuora recommends you to create a dedicated API user with API write access on a tenant when authenticating via OAuth, and then create an OAuth client for this user. See Create an API User for how to do this. By creating a dedicated API user, you can control permissions of the API user without affecting other non-API users.
If a user is deactivated, all of the user's OAuth clients will be automatically deactivated.
Authenticating via OAuth requires the following steps:
Create a Client
Generate a Token
Make Authenticated Requests
Create a Client
You must first create an OAuth client in the Zuora UI. To do this, you must be an administrator of your Zuora tenant. This is a one-time operation. You will be provided with a Client ID and a Client Secret. Please note this information down, as it will be required for the next step.
Note: The OAuth client will be owned by a Zuora user account. If you want to perform PUT, POST, or DELETE operations using the OAuth client, the owner of the OAuth client must have a Platform role that includes the "API Write Access" permission.
Generate a Token
After creating a client, you must make a call to obtain a bearer token using the Generate an OAuth token operation. This operation requires the following parameters:
client_id - the Client ID displayed when you created the OAuth client in the previous step
client_secret - the Client Secret displayed when you created the OAuth client in the previous step
granttype - must be set to clientcredentials
Note: The Client ID and Client Secret mentioned above were displayed when you created the OAuth Client in the prior step. The Generate an OAuth token response specifies how long the bearer token is valid for. You should reuse the bearer token until it is expired. When the token is expired, call Generate an OAuth token again to generate a new one.
Make Authenticated Requests
To authenticate subsequent API requests, you must provide a valid bearer token in an HTTP header:
Authorization: Bearer {bearer_token}
If you have Zuora Multi-entity enabled, you need to set an additional header to specify the ID of the entity that you want to access. You can use the scope field in the Generate an OAuth token response to determine whether you need to specify an entity ID.
If the scope field contains more than one entity ID, you must specify the ID of the entity that you want to access. For example, if the scope field contains entity.1a2b7a37-3e7d-4cb3-b0e2-883de9e766cc and entity.c92ed977-510c-4c48-9b51-8d5e848671e9, specify one of the following headers:
Zuora-Entity-Ids: 1a2b7a37-3e7d-4cb3-b0e2-883de9e766cc
Zuora-Entity-Ids: c92ed977-510c-4c48-9b51-8d5e848671e9
Note: For a limited period of time, Zuora will accept the entityId header as an alternative to the Zuora-Entity-Ids header. If you choose to set the entityId header, you must remove all "-" characters from the entity ID in the scope field.
If the scope field contains a single entity ID, you do not need to specify an entity ID.
Other Supported Authentication Schemes
Zuora continues to support the following additional legacy means of authentication:
Use username and password. Include authentication with each request in the header:
apiAccessKeyId
apiSecretAccessKey
Zuora recommends that you create an API user specifically for making API calls. See Create an API User for more information.
Use an authorization cookie. The cookie authorizes the user to make calls to the REST API for the duration specified in Administration > Security Policies > Session timeout. The cookie expiration time is reset with this duration after every call to the REST API. To obtain a cookie, call the Connections resource with the following API user information:
ID
Password
For CORS-enabled APIs only: Include a 'single-use' token in the request header, which re-authenticates the user with each request. See below for more details.
Entity Id and Entity Name
The entityId and entityName parameters are only used for Zuora Multi-entity. These are the legacy parameters that Zuora will only continue to support for a period of time. Zuora recommends you to use the Zuora-Entity-Ids parameter instead.
The entityId and entityName parameters specify the Id and the name of the entity that you want to access, respectively. Note that you must have permission to access the entity.
You can specify either the entityId or entityName parameter in the authentication to access and view an entity.
If both entityId and entityName are specified in the authentication, an error occurs.
If neither entityId nor entityName is specified in the authentication, you will log in to the entity in which your user account is created.
To get the entity Id and entity name, you can use the GET Entities REST call. For more information, see API User Authentication.
Token Authentication for CORS-Enabled APIs
The CORS mechanism enables REST API calls to Zuora to be made directly from your customer's browser, with all credit card and security information transmitted directly to Zuora. This minimizes your PCI compliance burden, allows you to implement advanced validation on your payment forms, and makes your payment forms look just like any other part of your website.
For security reasons, instead of using cookies, an API request via CORS uses tokens for authentication.
The token method of authentication is only designed for use with requests that must originate from your customer's browser; it should not be considered a replacement to the existing cookie authentication mechanism.
See Zuora CORS REST for details on how CORS works and how you can begin to implement customer calls to the Zuora REST APIs. See HMAC Signatures for details on the HMAC method that returns the authentication token.
Requests and Responses
Request IDs
As a general rule, when asked to supply a "key" for an account or subscription (accountKey, account-key, subscriptionKey, subscription-key), you can provide either the actual ID or the number of the entity.
HTTP Request Body
Most of the parameters and data accompanying your requests will be contained in the body of the HTTP request.
The Zuora REST API accepts JSON in the HTTP request body. No other data format (e.g., XML) is supported.
Data Type
(Actions and CRUD operations only) We recommend that you do not specify the decimal values with quotation marks, commas, and spaces. Use characters of +-0-9.eE, for example, 5, 1.9, -8.469, and 7.7e2. Also, Zuora does not convert currencies for decimal values.
Testing a Request
Use a third party client, such as curl, Postman, or Advanced REST Client, to test the Zuora REST API.
You can test the Zuora REST API from the Zuora API Sandbox or Production tenants. If connecting to Production, bear in mind that you are working with your live production data, not sample data or test data.
Testing with Credit Cards
Sooner or later it will probably be necessary to test some transactions that involve credit cards. For suggestions on how to handle this, see [Going Live With Your Payment Gateway](https://knowledgecenter.zuora.com/CBBilling/MPaymentGateways/CManagingPaymentGateways/BGoingLivePaymentGateways#TestingwithCreditCards "CZuoraUserGuides/ABillingandPayments/MPaymentGateways/CManagingPaymentGateways/BGoingLivePaymentGateways#TestingwithCredit_Cards"
).
Concurrent Request Limits
Zuora enforces tenant-level concurrent request limits. See Concurrent Request Limits for more information.
Timeout Limit
If a request does not complete within 120 seconds, the request times out and Zuora returns a Gateway Timeout error.
Error Handling
If a request to Zuora Billing REST API with an endpoint starting with /v1 (except Actions and CRUD operations) fails, the response will contain an eight-digit error code with a corresponding error message to indicate the details of the error.
The following code snippet is a sample error response that contains an error code and message pair:
The success field indicates whether the API request has succeeded. The processId field is a Zuora internal ID that you can provide to Zuora Global Support for troubleshooting purposes.
The reasons field contains the actual error code and message pair. The error code begins with 5 or 6 means that you encountered a certain issue that is specific to a REST API resource in Zuora Billing. For example, 53100320 indicates that an invalid value is specified for the termType field of the subscription object.
The error code beginning with 9 usually indicates that an authentication-related issue occurred, and it can also indicate other unexpected errors depending on different cases. For example, 90000011 indicates that an invalid credential is provided in the request header.
When troubleshooting the error, you can divide the error code into two components: REST API resource code and error category code. See the following Zuora error code sample:
Note: Zuora determines resource codes based on the request payload. Therefore, if GET and DELETE requests that do not contain payloads fail, you will get 500000 as the resource code, which indicates an unknown object and an unknown field.
The error category code of these requests is valid and follows the rules described in the Error Category Code section.
In such case, you can refer to the returned error message to troubleshoot.
REST API Resource Code
The 6-digit resource code indicates the REST API resource, typically a field of a Zuora object, on which the issue occurs. In the preceding example, 531003 refers to the termType field of the subscription object.
The value range for all REST API resource codes is from 500000 to 679999. See Resource Codes in the Knowledge Center for a full list of resource codes.
Error Category Code
The 2-digit error category code identifies the type of error, for example, resource not found or missing required field.
The following table describes all error categories and the corresponding resolution:
| Code | Error category | Description | Resolution |
|:--------|:--------|:--------|:--------|
| 10 | Permission or access denied | The request cannot be processed because a certain tenant or user permission is missing. | Check the missing tenant or user permission in the response message and contact Zuora Global Support for enablement. |
| 11 | Authentication failed | Authentication fails due to invalid API authentication credentials. | Ensure that a valid API credential is specified. |
| 20 | Invalid format or value | The request cannot be processed due to an invalid field format or value. | Check the invalid field in the error message, and ensure that the format and value of all fields you passed in are valid. |
| 21 | Unknown field in request | The request cannot be processed because an unknown field exists in the request body. | Check the unknown field name in the response message, and ensure that you do not include any unknown field in the request body. |
| 22 | Missing required field | The request cannot be processed because a required field in the request body is missing. | Check the missing field name in the response message, and ensure that you include all required fields in the request body. |
| 30 | Rule restriction | The request cannot be processed due to the violation of a Zuora business rule. | Check the response message and ensure that the API request meets the specified business rules. |
| 40 | Not found | The specified resource cannot be found. | Check the response message and ensure that the specified resource exists in your Zuora tenant. |
| 45 | Unsupported request | The requested endpoint does not support the specified HTTP method. | Check your request and ensure that the endpoint and method matches. |
| 50 | Locking contention | This request cannot be processed because the objects this request is trying to modify are being modified by another API request, UI operation, or batch job process. | Resubmit the request first to have another try. If this error still occurs, contact Zuora Global Support with the returned Zuora-Request-Id value in the response header for assistance. |
| 60 | Internal error | The server encounters an internal error. | Contact Zuora Global Support with the returned Zuora-Request-Id value in the response header for assistance. |
| 70 | Request exceeded limit | The total number of concurrent requests exceeds the limit allowed by the system. | Resubmit the request after the number of seconds specified by the Retry-After value in the response header. Check Concurrent request limits for details about Zuora’s concurrent request limit policy. |
| 90 | Malformed request | The request cannot be processed due to JSON syntax errors. | Check the syntax error in the JSON request body and ensure that the request is in the correct JSON format. |
| 99 | Integration error | The server encounters an error when communicating with an external system, for example, payment gateway, tax engine provider. | Check the response message and take action accordingly. |
Pagination
When retrieving information (using GET methods), the optional pageSize query parameter sets the maximum number of rows to return in a response. The maximum is 40; larger values are treated as 40. If this value is empty or invalid, pageSize typically defaults to 10.
The default value for the maximum number of rows retrieved can be overridden at the method level.
If more rows are available, the response will include a nextPage element, which contains a URL for requesting the next page. If this value is not provided, no more rows are available. No "previous page" element is explicitly provided; to support backward paging, use the previous call.
Array Size
For data items that are not paginated, the REST API supports arrays of up to 300 rows. Thus, for instance, repeated pagination can retrieve thousands of customer accounts, but within any account an array of no more than 300 rate plans is returned.
API Versions
The Zuora REST API are version controlled. Versioning ensures that Zuora REST API changes are backward compatible. Zuora uses a major and minor version nomenclature to manage changes. By specifying a version in a REST request, you can get expected responses regardless of future changes to the API.
Major Version
The major version number of the REST API appears in the REST URL. Currently, Zuora only supports the v1 major version. For example, POST https://rest.zuora.com/v1/subscriptions.
Minor Version
Zuora uses minor versions for the REST API to control small changes. For example, a field in a REST method is deprecated and a new field is used to replace it.
Some fields in the REST methods are supported as of minor versions. If a field is not noted with a minor version, this field is available for all minor versions. If a field is noted with a minor version, this field is in version control. You must specify the supported minor version in the request header to process without an error.
If a field is in version control, it is either with a minimum minor version or a maximum minor version, or both of them. You can only use this field with the minor version between the minimum and the maximum minor versions. For example, the invoiceCollect field in the POST Subscription method is in version control and its maximum minor version is 189.0. You can only use this field with the minor version 189.0 or earlier.
If you specify a version number in the request header that is not supported, Zuora will use the minimum minor version of the REST API. In our REST API documentation, if a field or feature requires a minor version number, we note that in the field description.
You only need to specify the version number when you use the fields require a minor version. To specify the minor version, set the zuora-version parameter to the minor version number in the request header for the request call. For example, the collect field is in 196.0 minor version. If you want to use this field for the POST Subscription method, set the zuora-version parameter to 196.0 in the request header. The zuora-version parameter is case sensitive.
For all the REST API fields, by default, if the minor version is not specified in the request header, Zuora will use the minimum minor version of the REST API to avoid breaking your integration.
Minor Version History
The supported minor versions are not serial. This section documents the changes made to each Zuora REST API minor version.
The following table lists the supported versions and the fields that have a Zuora REST API minor version.
| Fields | Minor Version | REST Methods | Description |
|:--------|:--------|:--------|:--------|
| invoiceCollect | 189.0 and earlier | Create Subscription; Update Subscription; Renew Subscription; Cancel Subscription; Suspend Subscription; Resume Subscription; Create Account|Generates an invoice and collects a payment for a subscription. |
| collect | 196.0 and later | Create Subscription; Update Subscription; Renew Subscription; Cancel Subscription; Suspend Subscription; Resume Subscription; Create Account|Collects an automatic payment for a subscription. |
| invoice | 196.0 and 207.0| Create Subscription; Update Subscription; Renew Subscription; Cancel Subscription; Suspend Subscription; Resume Subscription; Create Account|Generates an invoice for a subscription. |
| invoiceTargetDate | 196.0 and earlier | Preview Subscription |Date through which charges are calculated on the invoice, as yyyy-mm-dd. |
| invoiceTargetDate | 207.0 and earlier | Create Subscription; Update Subscription; Renew Subscription; Cancel Subscription; Suspend Subscription; Resume Subscription; Create Account|Date through which charges are calculated on the invoice, as yyyy-mm-dd. |
| targetDate | 207.0 and later | Preview Subscription |Date through which charges are calculated on the invoice, as yyyy-mm-dd. |
| targetDate | 211.0 and later | Create Subscription; Update Subscription; Renew Subscription; Cancel Subscription; Suspend Subscription; Resume Subscription; Create Account|Date through which charges are calculated on the invoice, as yyyy-mm-dd. |
| includeExisting DraftInvoiceItems | 196.0 and earlier| Preview Subscription; Update Subscription | Specifies whether to include draft invoice items in subscription previews. Specify it to be true (default) to include draft invoice items in the preview result. Specify it to be false to excludes draft invoice items in the preview result. |
| includeExisting DraftDocItems | 207.0 and later | Preview Subscription; Update Subscription | Specifies whether to include draft invoice items in subscription previews. Specify it to be true (default) to include draft invoice items in the preview result. Specify it to be false to excludes draft invoice items in the preview result. |
| previewType | 196.0 and earlier| Preview Subscription; Update Subscription | The type of preview you will receive. The possible values are InvoiceItem(default), ChargeMetrics, and InvoiceItemChargeMetrics. |
| previewType | 207.0 and later | Preview Subscription; Update Subscription | The type of preview you will receive. The possible values are LegalDoc(default), ChargeMetrics, and LegalDocChargeMetrics. |
| runBilling | 211.0 and later | Create Subscription; Update Subscription; Renew Subscription; Cancel Subscription; Suspend Subscription; Resume Subscription; Create Account|Generates an invoice or credit memo for a subscription. Note: Credit memos are only available if you have the Invoice Settlement feature enabled. |
| invoiceDate | 214.0 and earlier | Invoice and Collect |Date that should appear on the invoice being generated, as yyyy-mm-dd. |
| invoiceTargetDate | 214.0 and earlier | Invoice and Collect |Date through which to calculate charges on this account if an invoice is generated, as yyyy-mm-dd. |
| documentDate | 215.0 and later | Invoice and Collect |Date that should appear on the invoice and credit memo being generated, as yyyy-mm-dd. |
| targetDate | 215.0 and later | Invoice and Collect |Date through which to calculate charges on this account if an invoice or a credit memo is generated, as yyyy-mm-dd. |
| memoItemAmount | 223.0 and earlier | Create credit memo from charge; Create debit memo from charge | Amount of the memo item. |
| amount | 224.0 and later | Create credit memo from charge; Create debit memo from charge | Amount of the memo item. |
| subscriptionNumbers | 222.4 and earlier | Create order | Container for the subscription numbers of the subscriptions in an order. |
| subscriptions | 223.0 and later | Create order | Container for the subscription numbers and statuses in an order. |
| creditTaxItems | 238.0 and earlier | Get credit memo items; Get credit memo item | Container for the taxation items of the credit memo item. |
| taxItems | 238.0 and earlier | Get debit memo items; Get debit memo item | Container for the taxation items of the debit memo item. |
| taxationItems | 239.0 and later | Get credit memo items; Get credit memo item; Get debit memo items; Get debit memo item | Container for the taxation items of the memo item. |
| chargeId | 256.0 and earlier | Create credit memo from charge; Create debit memo from charge | ID of the product rate plan charge that the memo is created from. |
| productRatePlanChargeId | 257.0 and later | Create credit memo from charge; Create debit memo from charge | ID of the product rate plan charge that the memo is created from. |
| comment | 256.0 and earlier | Create credit memo from charge; Create debit memo from charge; Create credit memo from invoice; Create debit memo from invoice; Get credit memo items; Get credit memo item; Get debit memo items; Get debit memo item | Comments about the product rate plan charge, invoice item, or memo item. |
| description | 257.0 and later | Create credit memo from charge; Create debit memo from charge; Create credit memo from invoice; Create debit memo from invoice; Get credit memo items; Get credit memo item; Get debit memo items; Get debit memo item | Description of the the product rate plan charge, invoice item, or memo item. |
Version 207.0 and Later
The response structure of the Preview Subscription and Update Subscription methods are changed. The following invoice related response fields are moved to the invoice container:
amount
amountWithoutTax
taxAmount
invoiceItems
targetDate
chargeMetrics
Zuora Billing Object Model
The following diagram is a high-level view of how key business objects are related to one another within Zuora Billing.
Click the diagram to open it in a new tab and zoom in.
For more information about the different sections of the diagram, see
Zuora Billing business object model.
This diagram is intended to provide a conceptual understanding; it does not illustrate a specific way to integrate with Zuora.
The diagram includes the Orders feature and the Invoice Settlement feature.
If your organization does not use either of these features, see
Zuora Billing business object model prior to Orders and Invoice Settlement
for an alternative diagram.
API Names
You can use the Describe object operation to list the fields of each Zuora object that is available in your tenant. When you call the operation, you must specify the API name of the Zuora object.
The following table provides the API name of each Zuora object:
| Object | API Name |
|-----------------------------------------------|--------------------------------------------|
| Account | Account |
| Accounting Code | AccountingCode |
| Accounting Period | AccountingPeriod |
| Amendment | Amendment |
| Application Group | ApplicationGroup |
| Billing Run | BillingRun - API name used in the Describe object operation, Export ZOQL queries, and Data Query. BillRun - API name used in the Actions. See the CRUD oprations of Bill Run for more information about the BillRun object. BillingRun and BillRun have different fields. |
| Contact | Contact |
| Contact Snapshot | ContactSnapshot |
| Credit Balance Adjustment | CreditBalanceAdjustment |
| Credit Memo | CreditMemo |
| Credit Memo Application | CreditMemoApplication |
| Credit Memo Application Item | CreditMemoApplicationItem |
| Credit Memo Item | CreditMemoItem |
| Credit Memo Part | CreditMemoPart |
| Credit Memo Part Item | CreditMemoPartItem |
| Credit Taxation Item | CreditTaxationItem |
| Custom Exchange Rate | FXCustomRate |
| Debit Memo | DebitMemo |
| Debit Memo Item | DebitMemoItem |
| Debit Taxation Item | DebitTaxationItem |
| Discount Applied Metrics | DiscountAppliedMetrics |
| Entity | Tenant |
| Feature | Feature |
| Gateway Reconciliation Event | PaymentGatewayReconciliationEventLog |
| Gateway Reconciliation Job | PaymentReconciliationJob |
| Gateway Reconciliation Log | PaymentReconciliationLog |
| Invoice | Invoice |
| Invoice Adjustment | InvoiceAdjustment |
| Invoice Item | InvoiceItem |
| Invoice Item Adjustment | InvoiceItemAdjustment |
| Invoice Payment | InvoicePayment |
| Journal Entry | JournalEntry |
| Journal Entry Item | JournalEntryItem |
| Journal Run | JournalRun |
| Order | Order |
| Order Action | OrderAction |
| Order ELP | OrderElp |
| Order Line Items | OrderLineItems |
| Order Item | OrderItem |
| Order MRR | OrderMrr |
| Order Quantity | OrderQuantity |
| Order TCB | OrderTcb |
| Order TCV | OrderTcv |
| Payment | Payment |
| Payment Application | PaymentApplication |
| Payment Application Item | PaymentApplicationItem |
| Payment Method | PaymentMethod |
| Payment Method Snapshot | PaymentMethodSnapshot |
| Payment Method Transaction Log | PaymentMethodTransactionLog |
| Payment Method Update | UpdaterDetail |
| Payment Part | PaymentPart |
| Payment Part Item | PaymentPartItem |
| Payment Run | PaymentRun |
| Payment Transaction Log | PaymentTransactionLog |
| Processed Usage | ProcessedUsage |
| Product | Product |
| Product Feature | ProductFeature |
| Product Rate Plan | ProductRatePlan |
| Product Rate Plan Charge | ProductRatePlanCharge |
| Product Rate Plan Charge Tier | ProductRatePlanChargeTier |
| Rate Plan | RatePlan |
| Rate Plan Charge | RatePlanCharge |
| Rate Plan Charge Tier | RatePlanChargeTier |
| Refund | Refund |
| Refund Application | RefundApplication |
| Refund Application Item | RefundApplicationItem |
| Refund Invoice Payment | RefundInvoicePayment |
| Refund Part | RefundPart |
| Refund Part Item | RefundPartItem |
| Refund Transaction Log | RefundTransactionLog |
| Revenue Charge Summary | RevenueChargeSummary |
| Revenue Charge Summary Item | RevenueChargeSummaryItem |
| Revenue Event | RevenueEvent |
| Revenue Event Credit Memo Item | RevenueEventCreditMemoItem |
| Revenue Event Debit Memo Item | RevenueEventDebitMemoItem |
| Revenue Event Invoice Item | RevenueEventInvoiceItem |
| Revenue Event Invoice Item Adjustment | RevenueEventInvoiceItemAdjustment |
| Revenue Event Item | RevenueEventItem |
| Revenue Event Item Credit Memo Item | RevenueEventItemCreditMemoItem |
| Revenue Event Item Debit Memo Item | RevenueEventItemDebitMemoItem |
| Revenue Event Item Invoice Item | RevenueEventItemInvoiceItem |
| Revenue Event Item Invoice Item Adjustment | RevenueEventItemInvoiceItemAdjustment |
| Revenue Event Type | RevenueEventType |
| Revenue Schedule | RevenueSchedule |
| Revenue Schedule Credit Memo Item | RevenueScheduleCreditMemoItem |
| Revenue Schedule Debit Memo Item | RevenueScheduleDebitMemoItem |
| Revenue Schedule Invoice Item | RevenueScheduleInvoiceItem |
| Revenue Schedule Invoice Item Adjustment | RevenueScheduleInvoiceItemAdjustment |
| Revenue Schedule Item | RevenueScheduleItem |
| Revenue Schedule Item Credit Memo Item | RevenueScheduleItemCreditMemoItem |
| Revenue Schedule Item Debit Memo Item | RevenueScheduleItemDebitMemoItem |
| Revenue Schedule Item Invoice Item | RevenueScheduleItemInvoiceItem |
| Revenue Schedule Item Invoice Item Adjustment | RevenueScheduleItemInvoiceItemAdjustment |
| Subscription | Subscription |
| Subscription Product Feature | SubscriptionProductFeature |
| Taxable Item Snapshot | TaxableItemSnapshot |
| Taxation Item | TaxationItem |
| Updater Batch | UpdaterBatch |
| Usage | Usage |