Welcome to the REST API reference for the Zuora Billing, Payments, and Central Platform!

To learn about the common use cases of Zuora REST APIs, check out the REST API Tutorials.

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.

Some of our older APIs are no longer recommended but still available, not affecting any existing integration. To find related API documentation, see Older API Reference.

All API requests occur in a test or production environment. For details on Zuora’s environments, see Zuora Environments in the Knowledge Center. Each environment uses a different base URL. Select the appropriate base URL below that you need to use:

Environment	Base URL
US Developer & Central Sandbox Applicable for Test Drive and trial access	https://rest.test.zuora.com
US API Sandbox	https://rest.sandbox.na.zuora.com (Cloud 1) https://rest.apisandbox.zuora.com (Cloud 2)
US Production	https://rest.na.zuora.com (Cloud 1) https://rest.zuora.com (Cloud 2)
EU Developer & Central Sandbox	https://rest.test.eu.zuora.com
EU API Sandbox	https://rest.sandbox.eu.zuora.com
EU Production	https://rest.eu.zuora.com

If you do not have a Zuora tenant, go to https://www.zuora.com/resource/zuora-test-drive and sign up for a Test Drive.

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:

 {
   "success": false,
   "processId": "CBCFED6580B4E076",
   "reasons":  [
     {
      "code": 53100320,
      "message": "'termType' value should be one of: TERMED, EVERGREEN"
     }
    ]
 }

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, Payments, and Central Platform. 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 Codes section. In such case, you can refer to the returned error message to troubleshoot.

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.

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.
23	Missing required parameter	The request cannot be processed because a required query parameter is missing.	Check the missing parameter name in the response message, and ensure that you include the parameter in the query.
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.
61	Temporary error	A temporary error occurs during request processing, for example, a database communication error.	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.
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.

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.

The major version number of the REST API appears in the REST URL. In this API reference, only the v1 major version is available. For example, POST https://rest.zuora.com/v1/subscriptions.

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 consecutive. You can use the following versions to override the default version (186.0):

• 187.0
• 188.0
• 189.0
• 196.0
• 206.0
• 207.0
• 211.0
• 214.0
• 215.0
• 216.0
• 223.0
• 224.0
• 230.0
• 239.0
• 256.0
• 257.0
• 309.0
• 314.0
• 315.0
• 329.0
• 330.0
• 336.0
• 337.0
• 338.0
• 341.0

If you set the zuora-version header to a version excluded from the preceding list, the corresponding API request is processed as you use the default version, 186.0.

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	206.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	206.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	206.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.
taxationItems	309.0 and later	Preview an order	List of taxation items for an invoice item or a credit memo item.
batch	309.0 and earlier	Create a billing preview run	The customer batches to include in the billing preview run.
batches	314.0 and later	Create a billing preview run	The customer batches to include in the billing preview run.
taxationItems	315.0 and later	Preview a subscription; Update a subscription	List of taxation items for an invoice item or a credit memo item.
billingDocument	330.0 and later	Create a payment schedule; Create multiple payment schedules at once	The billing document with which the payment schedule item is associated.
paymentId	336.0 and earlier	Add payment schedule items to a custom payment schedule; Update a payment schedule; Update a payment schedule item; Preview the result of payment schedule update; Retrieve a payment schedule; Retrieve a payment schedule item; List payment schedules by customer account; Cancel a payment schedule; Cancel a payment schedule item;Skip a payment schedule item;Retry failed payment schedule items	ID of the payment to be linked to the payment schedule 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

For information about the Zuora business object model, see Zuora Business Object Model.

You can use the Describe 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 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.
Billing Preview Run	BillingPreviewRun
Configuration Templates	ConfigurationTemplates
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
Fulfillment	Fulfillment
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
Invoice Schedule	InvoiceSchedule
Invoice Schedule Item	InvoiceScheduleItem
Journal Entry	JournalEntry
Journal Entry Item	JournalEntryItem
Journal Run	JournalRun
Notification History - Callout	CalloutHistory
Notification History - Email	EmailHistory
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 Charge Definition	ProductChargeDefinition
Product Feature	ProductFeature
Product Rate Plan	ProductRatePlan
Product Rate Plan Definition	ProductRatePlanDefinition
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