API Reference (2023-06-16)

Download OpenAPI specification:Download

Introduction

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.

In addition to Zuora API Reference, we also provide API references for other Zuora products:

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.

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 Cloud 1 Production https://rest.na.zuora.com
US Cloud 1 API Sandbox https://rest.sandbox.na.zuora.com
US Cloud 2 Production https://rest.zuora.com
US Cloud 2 API Sandbox https://rest.apisandbox.zuora.com
US Central Sandbox https://rest.test.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.
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.

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:

 {
   "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:

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.

REST API Resource Codes

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 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.

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. In this API reference, only the v1 major version is available. 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 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.
paymentOption 337.0 and later Create a payment schedule; Create multiple payment schedules at once; Create a payment; 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; List payments Array of transactional level rules for processing payments.

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

API Names for Zuora Objects

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.

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
Journal Entry JournalEntry
Journal Entry Item JournalEntryItem
Journal Run JournalRun
Notification History - Callout CalloutHistory
Notification History - Email EmailHistory
Offer Offer
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
Price Book Item PriceBookItem
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