API overview new

This guide covers the basics of creating a customer account, generating an invoice, and applying a payment using Zuora's API.

Basics of customer accounts, invoicing, and payments

developers/api-docs/1-api/developer-blogs/how-we-built-a-reliable-and-secure-ai-based-feature

Developer blogs

developers/api-docs/1-api/allof-comparison//db/organizations/zuora/repositories/prod-sitemap/content/documents/external_publications/api_reference/json/zuora_api_create_account_allof_comparison.json

Allof Comparison

developers/api-docs/1-api/allof-without-additionalproperties//db/organizations/zuora/repositories/prod-sitemap/content/documents/external_publications/api_reference/json/zuora_api_create_account_allof_comparison_without_additionalProperties.json

Allof without additionalProperties

A Test Environment is a dedicated sandbox tenant designed for development, integration, and user acceptance testing of your system configurations and business processes.


Test Environments

A Test Environment Job represents an asynchronous operation initiated to refresh a Test Environment. These jobs track the status and progress of environment provisioning and refresh.


Test Environment Jobs

A Test Environment Notification is an automated email dispatched to inform stakeholders when a Test Environment Job is completed or cancelled.


Test Environment Notifications

Actions are operations that are batch in nature. For example, the "create", "update", "delete", and other operations allow changes to up-to 50 objects at a time. The "query" operation will return up-to 2000 result records back at a time, before requiring additional pages of data to be returned via a subsequent "queryMore" operation.

The default WSDL version for Actions is 79. If you want to change the WSDL version, set the `X-Zuora-WSDL-Version` header. To find out in which WSDL version a particular object or field was introduced, see [Zuora SOAP API Version History](https://knowledgecenter.zuora.com/DC_Developers/G_SOAP_API/Zuora_SOAP_API_Version_History).

**Note**: Actions do not support the Invoice Settlement feature. This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. Actions also do not support the Orders feature.


Actions

Accounting Codes are commonly referred to as General Ledger Accounts or General Ledger Account Codes. In Zuora, the use of accounting codes are optional but recommended. 

This section contains the operations that allow you to create, update, get, delete, activate, or deactivate accounting codes in Zuora.


Accounting Codes

A key step in configuring Finance is to create accounting periods in Zuora to match your company's financial calendar. 
This allows Zuora to produce reports and data exports organized by accounting periods, and to perform the work of closing the accounting periods for the revenue sub-ledger.


Accounting Periods

Some operations in this section are similar to each other, but are
provided for different use scenarios. You should choose the one that best suits
your needs.


For example, the [Retrieve an account](https://developer.zuora.com/v1-api-reference/api/operation/GET_Account/) operation retrieves the basic information of an account, such as bill-to and sold-to contacts, billing and payments setup information, and metrics data for the account.

The [Retrieve an account summary](https://developer.zuora.com/v1-api-reference/api/operation/GET_AccountSummary/) operation returns the more detailed information of an account, such as bill-to and sold-to contacts, subscriptions, invoices, payments, and usages associated with this account.


Accounts

Delivery Adjustments are used to handle end customer delivery complaints for the Delivery Pricing charge model. For more information, see <a href="https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Delivery_Adjustments" target="_blank">Delivery Adjustments</a>.  


Delivery Adjustments

The Aggregate Query API (AQuA) is a REST API that executes multiple <a href="https://knowledgecenter.zuora.com/Zuora_Central_Platform/Query/Export_ZOQL" target="_blank">Export ZOQL</a> or <a href="https://knowledgecenter.zuora.com/Zuora_Central_Platform/Query/ZOQL" target="_blank">ZOQL</a> queries. The queries are performed in a sequential order and in a single read-only database transaction. 

AQuA enforces the following limits:

- The maximum processing time per query is 3 hours. If a query in an AQuA job is executed for longer than 3 hours, this job will be killed automatically. See the <a href="https://knowledgecenter.zuora.com/Zuora_Central_Platform/API/AB_Aggregate_Query_API/Bulk_data__extraction_from_Zuora_using_AQuA" target="_blank">best practices for bulk data extraction with AQuA</a>.

- AQuA enforces limits on both the stateful concurrent AQuA jobs and the stateless concurrent AQuA jobs per tenant:
  - The maximum number of stateful concurrent AQuA jobs per tenant is 50.  - The maximum number of stateless concurrent AQuA jobs per tenant is 50.
AQuA jobs in the following status are counted towards your concurrent AQuA job limits:
  - Submitted  - Executing
Zuora system will reject the subsequent stateful or stateless job requests once the corresponding concurrent job limit is reached.

For more information about the Aggregate Query API(AQuA), see <a href="https://knowledgecenter.zuora.com/Zuora_Central_Platform/API/AB_Aggregate_Query_API" target="_blank">Aggregate Query</a>.      


Aggregate Queries

Zuora System Health dashboard for API (API dashboard) collects and displays data about API usage, failure, performance, and concurrency limit in near real time. It enables you to view all the APIs in your Zuora tenant within the last 14 days. For more information, see <a href="https://knowledgecenter.zuora.com/Zuora_Central_Platform/Zuora_System_Health/B_APIs_dashboard" target="_blank">APIs dashboard</a>.


API Health

Use attachments in Zuora to upload documents of various formats to associate additional information with accounts, subscriptions, invoices, credit memos, or debit memos. 
Example attachments could be purchase orders (PO's), tax exemption document, or ownership transfer forms.

For more information about attachments, see <a href="https://knowledgecenter.zuora.com/Billing/Tenant_Management/F_Attachments" target="_blank">Attachments</a>.


Attachments

Zuora System Health dashboard for Bill Run (Bill Run dashboard) collects and displays data about bill run usage, failure, and performance in near real time. Through the Bill Run dashboard, you can view data about all the bill runs in your Zuora tenant within the last 30 days. For more information, see <a href="https://knowledgecenter.zuora.com/Zuora_Central_Platform/Zuora_System_Health/C_Bill_Run_dashboard" target="_blank">Bill Run dashboard</a>.


Bill Run Health

Use the Bill Run call to create ad hoc bill runs and Post, Cancel, Query, and Delete bill runs. 

For more information about bill runs, see <a href="https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/J_Billing_Operations/G_Bill_Runs" target="_blank">Bill runs</a>.


Bill Run

Billing documents include invoices, credit memos, and debit memos. 

**Note**: Credit memos and debit memos are only available if you have the <a href="https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement" target="_blank">Invoice Settlement</a> feature enabled. 


Billing Documents

A billing preview run asynchronously generates a downloadable CSV file containing a preview of future invoice item data and credit memo item data for a batch of customer accounts. 

**Note**: Credit memo item data is only available if you have the <a href="https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement" target="_blank">Invoice Settlement</a> feature enabled. 


Billing Preview Run

**Note** - The APIs in this section are legacy APIs. Zuora recommends using the newer, faster APIs for managing products and catalogs more efficiently instead.
For more information, see our latest <a href="https://developer.zuora.com/v1-api-reference/api/tag/Commerce/"
target="_blank">Commerce API</a>.


The Zuora Billing product catalog is where you define your products
and pricing. The product catalog's ability to handle sophisticated pricing models
gives you the power to easily adapt your pricing to customer and market needs,
to grow your business and drive more revenue. 


Catalog

**Note** - The APIs in this section are legacy APIs. Zuora recommends using the newer, faster APIs for managing products and catalogs more efficiently instead.
For more information, see our latest <a href="https://developer.zuora.com/v1-api-reference/api/tag/Commerce/"
target="_blank">Commerce API</a>.


A catalog group is used to group a list of product rate plans with
a specific grade.


Catalog Groups

Configuration Templates in Zuora Deployment Manager enable you to configure your tenants in minutes by importing a templated metadata configuration file. This feature eliminates the need for long manual configuration processes that would have previously taken hours. You will be able to access a comprehensive repository of industry-specific templates. It will be easier for you to deploy and release. To use this API  for migrating metadata from a source tenant to a destination tenant,   you should authenticate using credentials of the source tenant   The user will have to provide the client id and secret key from the sou.rce tenant.   To understand the known behavior of configuration templates and APIs, see the following sections: [Product Catalog deployment known facts and system behavior](https://knowledgecenter.zuora.com/Zuora_Platform/Tenant_Management/Deployment_Manager/CB_Product_Catalog_deployments/AE_Known_facts_and_system_behavior) [Product Catalog deployment FAQs](https://knowledgecenter.zuora.com/Zuora_Platform/Tenant_Management/Deployment_Manager/CB_Product_Catalog_deployments/AF_Product_Catalog_deployment_FAQs) [Deployment Manager Known Facts and Limitations](https://knowledgecenter.zuora.com/Zuora_Platform/Tenant_Management/Deployment_Manager/C_Deployment_Manager_Limitations) 


Configuration Templates

The Metadata API in Zuora promotes a programmatic way to retrieve, compare, and validate 
metadata within Zuora tenants for performing create and update actions between the source and the target.
To use this API  for migrating metadata from a source tenant to a destination tenant, 
you should authenticate using credentials of the source tenant. 
The user will have to provide the client id and secret key from the source tenant. 
To understand the known behavior of configuration templates and APIs, see the following sections:
[Product Catalog deployment known facts and system behavior](https://knowledgecenter.zuora.com/Zuora_Platform/Tenant_Management/Deployment_Manager/CB_Product_Catalog_deployments/AE_Known_facts_and_system_behavior)
[Product Catalog deployment FAQs](https://knowledgecenter.zuora.com/Zuora_Platform/Tenant_Management/Deployment_Manager/CB_Product_Catalog_deployments/AF_Product_Catalog_deployment_FAQs)
[Deployment Manager Known Facts and Limitations](https://knowledgecenter.zuora.com/Zuora_Platform/Tenant_Management/Deployment_Manager/C_Deployment_Manager_Limitations)


Metadata

The Bulk Data API operations allow you to manage bulk data loader services and perform programmatic CRUD (Create, Update, Read/export, Delete) operations. \
To perform data ingestion with a CSV file in Zuora Billing using the Data Loader Bulk Data APIs, see <a href="https://knowledgecenter.zuora.com/Zuora_Platform/Data_Management/Data_Loader/Tutorial_for_Bulk_job_API_with_CSV" target="_blank">Tutorial for Bulk job API with CSV</a>. 
For more information, see <a href="https://knowledgecenter.zuora.com/Zuora_Platform/Data_Management/Data_Loader/Process_Bulk_Job_with_JSON-lines_in_Data_Loader" target="_blank">Process Bulk Job with JSON-lines in Data Loader</a>.


Bulk Data

The Commerce APIs provide access to product catalog, plans, charges, and order
management functionality in Zuora. These endpoints are used to create, update,
and query product rate plans, charges, and dynamic pricing details that drive
subscription and billing behavior.

In a typical use case, the Commerce APIs are called to provision new products
or plans in the catalog, configure dimensional pricing, or submit orders that
create and modify subscriptions.

Changes made with these APIs affect the product catalog and active subscriptions,
depending on the endpoint. Catalog changes update future subscription behavior,
while order operations directly impact customer subscriptions in real time.'


Commerce

A commitment represents a minimum or maximum spend amount a customer is obligated to pay within a spend period, compared with customer's actual fees incurred in connection with customer's accounts and their use of applicable products. 
The Commitments API allows you to retrieve details of the commitments a customer has.


Commitments

Every time a contact is updated a snapshot is taken.


Contact Snapshots

Configurable Payment Retry APIs use basic authentication. The user name is the email address that you use for logging in Zuora. The password is the API token that is shown in the settings of Configurable Payment Retry.
Click the drop-down arrow at the end of an endpoint to display the full endpoint. To learn more about the configuration and usage of Configurable Payment Retry, see [Configurable Payment Retry](https://knowledgecenter.zuora.com/Zuora_Payments/Configure_payment_orchestration/Payment_Retry/Configurable_Payment_Retry).


Configurable Payment Retry

A contact defines the customer who holds an account or who is otherwise a person to contact about an account. An account requires a contact for the `BillToId` and `SoldToId` fields before the account can be active.


Contacts

Credit memos reduce invoice and account balances. By applying one or more credit memos to invoices with positive balances, you can reduce the invoice balances in the same way that applying a payment to an invoice.

For more information about credit memos, see <a href="https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/B_Credit_and_Debit_Memos" target="_blank">Credit and debit memos</a>.


Credit Memos

The Event Trigger service manages the business events and trigger conditions that are defined on [Zuora Business Object Model](http://knowledgecenter.zuora.com/BB_Introducing_Z_Business/D_Zuora_Business_Objects_Relationship) or custom objects. When a Zuora object changes, the trigger conditions defined on the object are evaluated, and if any condition qualifies, a business event will be triggered and turned into a notification.

**Note**: Event Triggers operations are only applicable to custom events.


Custom Event Triggers

If you use a custom exchange rate provider and upload rates with the Import Foreign Exchange Rates mass action, you can query custom foreign exchange rates from Zuora through API. 

This feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at <a href="http://support.zuora.com/" target="_blank">Zuora Global Support</a>.


Custom Exchange Rates

With Custom Objects service, you can define custom objects, extending the Zuora data model to accommodate your specific use cases.

If you use Postman, you can import the custom objects endpoints as a collection into your Postman app and try out different requests to learn how the API works. 

You can sign up for a free account on the [Postman website](https://identity.getpostman.com/signup) and download the app in case you do not use Postman yet.

Note that the Custom Object Definitions API is versioned by `Zuora-Version` in the request header. The response may be different for the same request with a different API version. Specify `Zuora-Version` in the request header if you expect a specific response schema.

### Error handling      
If the Custom Objects API call fails, an error code will be returned in the response body. See See <a href='https://docs.zuora.com/en/zuora-platform/extensibility/custom-objects/custom-objects-api/custom-objects-api-error-code' target='_blank'>Custom Objects API error code</a> for details.


Custom Object Definitions

With Custom Objects service, you can create, update, delete and find custom object records.

If you use Postman, you can import the custom objects endpoints as a collection into your Postman app and try out different requests to learn how the API works. 

You can sign up for a free account on the [Postman website](https://identity.getpostman.com/signup) and download the app in case you do not use Postman yet.

Note that the Custom Object Records API is versioned by `Zuora-Version` in the request header. The response may be different for the same request with a different API version. Specify `Zuora-Version` in the request header if you expect a specific response schema.

### Error handling      
If the Custom Objects API call fails, an error code will be returned in the response body. See <a href='https://docs.zuora.com/en/zuora-platform/extensibility/custom-objects/custom-objects-api/custom-objects-api-error-code' target='_blank'>Custom Objects API error code</a> for details.


Custom Object Records

With Custom Objects service, you can submit a bulk job request to create, update, or delete custom object records in a batch.

If you use Postman, you can import the custom objects endpoints as a collection into your Postman app and try out different requests to learn how the API works. 

You can sign up for a free account on the [Postman website](https://identity.getpostman.com/signup) and download the app in case you do not use Postman yet.

Note that the Custom Object Jobs API is versioned by `Zuora-Version` in the request header. The response may be different for the same request with a different API version. Specify `Zuora-Version` in the request header if you expect a specific response schema.

### Error handling      
If the Custom Objects API call fails, an error code will be returned in the response body. See <a href='https://docs.zuora.com/en/zuora-platform/extensibility/custom-objects/custom-objects-api/custom-objects-api-error-code' target='_blank'>Custom Objects API error code</a> for details.


Custom Object Jobs

Open Payment Method (OPM) service is a framework developed by Zuora, which allows you to integrate your custom payment method to Zuora subscription, billing, and revenue management in a dynamic and flexible manner. With the support of the OPM service, you are able to define your custom payment method types and create custom payment methods of the defined types. The custom payment method of the defined type can only be used with the custom payment gateway that you set up through the Universal Payment Connector (UPC) service. It cannot be used with the Zuora out-of-box gateway integrations such as GoCardless, Stripe, etc.

You can define up to 20 custom payment method types for one tenant. Do not define your fields with the [Zuora-reserved fields](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/MB_Set_up_custom_payment_gateways_and_payment_methods/C_Configure_and_manage_your_custom_payment_method_types_through_Zuora_REST_APIs#Zuora-reserved_fields).

See [Set up custom payment gateways and payment methods](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/MB_Set_up_custom_payment_gateways_and_payment_methods) for more information about the OPM and UPC services.

Note: You can only use the bearer token to access the "Custom Payment Method Types" API operations. Access with `apiAccessKeyId` and `apiSecretAccessKey` is not supported.


Custom Payment Method Types

A custom scheduled event notification is evaluated at the scheduled time of the related scheduled event on a daily basis. If the date meets the combination of the base field and the notification parameters, the notification will be triggered immediately.

For more information about Custom Scheduled Events, see <a href="https://knowledgecenter.zuora.com/Central_Platform/Events_and_Notifications/A_Z_Custom_Scheduled_Events" target="_blank">Custom Scheduled Events</a>.


Custom Scheduled Events

If you are an <a href="https://knowledgecenter.zuora.com/Zuora_Billing/Enable_Order_to_Revenue" target="_blank">Order to Revenue</a> user, you can use the data backfill operations to perform, view or stop data backfill tasks.


Data Backfill

The Data Labeling APIs help you to label your existing data with organization(s) in Zuora. 

Once you turned on Multi Org feature, if you don't label your existing data, they are simply unlabeled, and unlabeled data can be accessed by all organizations in your tenant.

To limit the access of your existing data, you need to label them with organization(s) you defined in the organization hierarchy management setting page. Once labeled, the data can only be accessed by users who have been granted with the labeled organization(s).

Note that you have to enable the "Multi Org" feature before using the Data Labeling APIs. 

### General guidelines

* Firstly, create the org hierarchy and determine the data categorization strategy, for example, by currency, by region, by custom fields etc.

* You have to migrate all customer accounts before labeling products in the product catalog

* You can leave the users at the root, just so long as you understand that the user would have access to all the Org Units within the Multi-org enabled tenant.

### Order of object labeling

Except for `Account` and `Product`, there are no dependencies between objects, users can label them in parallel.

But please keep in mind that the data access control ensues from the object labeling. For example, if you label a scheduled `BillRun` with `US` org, when it's triggered next time, the bill run will only pick up customer accounts of the `US` org, not others.

Likewise, labeling a user will change the user's visible data scope, for example, an `EU` user won't be able to see `US` accounts anymore.

 ### Caveats⚠️

This API is primarily designed for data migration to assist in  labeling existing datasets. 
It may also serve for data corrections, such as  reassigning an account's organizational label, 
thereby transferring the account  and its transaction data from one organization to another. 


It's important  to note that this process does not include business logic validation. 
Users  should exercise caution and judgment when employing this API for data labeling tasks.


Data Labeling

The Data Query feature enables you to perform SQL queries in your Zuora tenant. To learn how to get started with Data Query, see [Overview of Data Query](https://knowledgecenter.zuora.com/DC_Developers/BA_Data_Query/A_Overview_of_Data_Query).


Data Queries

Debit memos increase the amount a customer owes. It is a separate document from the invoice. Debit memos can be used to correct undercharging on an invoice or to levy ad hoc charges outside the context of a subscription. Just like an invoice, debit memo balances can be settled by applying either a payment or a credit memo.

For more information about debit memos, see <a href="https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/B_Credit_and_Debit_Memos" target="_blank">Credit and debit memos</a>.


Debit Memos

You can use the [Describe an object](https://developer.zuora.com/v1-api-reference/api/operation/GET_Describe/) operation to get a reference listing of each object that is available in your Zuora tenant.

By default, the information returned by the "Describe an object" operation corresponds to the latest version of the Zuora WSDL.


Describe

With the <a href="https://docs.zuora.com/en/zuora-billing/bill-your-customer/leverage-advanced-capabilities/e-invoicing/e-invoicing-overview" target="_blank">E-Invoicing</a> feature, Zuora supports electronic invoices through an integration with partners that have a local presence, where required, which guarantees compliance with local invoice regulations. 

All the operations in this section are available only if you have the E-Invoicing feature enabled.


E-Invoicing

Zuora System Health dashboard for Electronic Payments (Electronic Payment dashboard) collects and displays usage, failure, and performance data about electronic payments in near real time. It enables you to view all the electronic payments in your Zuora tenant within the last 30 days. For more information, see <a href="https://knowledgecenter.zuora.com/Zuora_Central_Platform/Zuora_System_Health/D_Electronic_Payments_dashboard" target="_blank">Electronic Payments dashboard</a>.


Electronic Payments Health

Zuora System Health dashboard for Tax Health (Tax Health dashboard) collects and displays usage, failure, and performance data about Tax in near real time. It enables you to view all the tax details in your Zuora tenant within the last 30 days. For more information, see <a href="https://knowledgecenter.zuora.com/Zuora_Billing/B_Set_up_Zuora_Billing/Apply_taxes/A_Zuora_Tax" target="_blank">Tax Health Dashboard</a>.

Tax Health

You can use the operations contained in this section to retrieve files such as export results, invoices, accounting period reports, and so on.


Files

Fulfillments are subordinate objects attached to their related order line item. Fulfillment items are subordinate objects attached to their related fulfillment. 

For more information, see <a href="https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AA_Overview_of_Order_Line_Items" target="_blank">Overview of Order Line Items</a>. 


Fulfillments

Hosted payment pages allow your customers to set up a payment method, such as providing a credit card. Since it only handles the payment method, it is suitable for a simple workflow or a complex multi-page, multi-product workflow. 

For more information, see <a href="https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/LA_Hosted_Payment_Pages" target="_blank">Hosted Payment Pages</a>.


Hosted Pages

An import uploads content, especially when you have a large amount of content. The Import object contains all of the information you need to upload content, such as a large number of usage records. 


Imports

Use invoice schedules to trigger invoice generation processes. 

For more information about invoice schedules, see <a href="https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Billing_Schedule/Billing_Schedule_overview" target="_blank">Billing Schedule overview</a>.


Invoice Schedules

Invoices provides information about customers' accounts for invoices, for examples, dates, status, and amounts. 

For more information about invoices, see <a href="https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/IA_Invoices/A1_Invoice_Introduction" target="_blank">Invoice</a>.


Invoices

Use journal runs to automatically create summary journal entities that are suitable for importing into your general ledger system.

For more information about journal runs, see <a href="https://knowledgecenter.zuora.com/Billing/Finance/F_Summary_Journal_Entries/h_Journal_Runs" target="_blank">Journal Runs</a>.


Journal Runs

Use mass updater to perform mass actions more easily.

For more information about mass updater, see <a href="https://knowledgecenter.zuora.com/Billing/Finance/Mass_Updater" target="_blank">Mass Updater</a>.


Mass Updater

Notifications are the actions taken to inform users or call third-party endpoints when a certain event happens. Typical actions include emails and callouts. Callouts typically refer to HTTP invocations, such as HTTP calls to REST services.

Zuora notification system processes the events in the same order in which they are triggered. The timing and delivery of notifications can still vary based on factors such as retries, concurrency, and network latency. But Zuora guarantees the best performance possible with the right performance boosters and tuning. 

Notifications are associated with Communication Profiles, which allow you to send specific event-driven notifications to targeted customers. Zuora provides the following Settings API to access the settings of Communication Profiles:* [Get all Communication Profiles](https://knowledgecenter.zuora.com/DC_Developers/BB_C_Settings_API/Settings_API_tutorials/Get_all_Communication_Profiles)
  * [Create a new Communication Profile](https://knowledgecenter.zuora.com/DC_Developers/BB_C_Settings_API/Settings_API_tutorials/Create_a_new_Communication_Profile)
  * [Modify a Communication Profile](https://knowledgecenter.zuora.com/DC_Developers/BB_C_Settings_API/Settings_API_tutorials/Modify_a_Communication_Profile)
  * [Get all Notifications under a particular Communication Profile](https://knowledgecenter.zuora.com/DC_Developers/BB_C_Settings_API/Settings_API_tutorials/Get_all_Notifications_under_a_particular_Communication_Profile)


Notifications

The Zuora Mediation APIs provide a comprehensive set of endpoints to manage, test, run, and monitor usage meters. These APIs support actions such as running or testing specific meter versions, importing and exporting meter configurations, managing input files, performing event store operations, and ingesting usage data in real time via streaming. All APIs follow a consistent response structure to simplify integration and error handling. Use these APIs to automate and streamline your usage processing pipeline—from data ingestion to transformation and billing.

Meters

Zuora recommends that you use OAuth v2.0 to authenticate to the Zuora REST API. 

You must first create an OAuth client in the Zuora UI before using the [Create an OAuth token](https://developer.zuora.com/api-references/api/operation/createToken) operation to create an OAuth token. See [Authentication](https://developer.zuora.com/rest-api/general-concepts/authentication/) for more information.


OAuth

System for Cross-domain Identity Management, or SCIM, is an API specification created to facilitate the management of people and groups of people in cloud-based applications and services.
  Universal Identity SCIM API is built on top of the SCIM 2.0 specification and can be integrated with major Identity Providers like Okta, Microsoft Entra ID and OneLogin.



Zuora recommends that you use OAuth v2.0 to authenticate to the Zuora REST API. 

You must first create an OAuth client in the Zuora UI before using the [Create an OAuth token](https://developer.zuora.com/api-references/api/operation/createToken) operation to create an OAuth token. See [Authentication](https://developer.zuora.com/rest-api/general-concepts/authentication/) for more information.

### Prerequisites
1. You need to have a One-ID account.
2. You need to create OAuth 2.0 Clients.
3. Use the client credentials to generate the bearer token.
4. Generate the authentication token by hitting the endpoint.


### Steps to generate the bearer token
1. Hit the endpoint to get the token:
   ```bash
   curl --location 'https://one.zuora.com/oauth2/token' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode 'client_id=52a1d024-b7cc-4d3d-8d0b-dd7b23959e10' \
     --data-urlencode 'client_secret=aQWDDjn3x9JXbMUQaddvBa2vQQMDCHXL8BgeER8' \
     --data-urlencode 'grant_type=client_credentials'
   ```

   You will get the response as below:
   ```json
   {
     "access_token": "eyJraWQiOiIxNTYwMDBkMi1lY2FjLTQxMGYtOTJmYy02Y2IxMjU1YjQ3NTAiLCJhbGciOiJSUzI1NiJ9.eyIzdWIiOiI1MWExZDAyNC1iN2NjLTRkM2QtOGQwYi1kZDdiMjM5NTllMTAiLCJhdWQiOiI1MWExZDAyNC1iN2NjLTRkM2QtOGQwYi1kZDdiMjM5NTllMTAiLCJuYmYiOjE2OTA1MzcyODksInNjb3BlIjpbImFkbWluIiwiZWMxNDFkYzItOTAxZS00ODEzLWEyNWQtZWY0ODBjZmYxZTI2Il0sImlzcyI6Imh0dHA6XC9cL2xvY2FsaG9zdDo5OTAwIiwiZXhwIjoxNjkwNTQwODg5LCJpYXQiOjE2OTA1MzcyODl9.NMZV-aERA8lTKPPsMtk_WK9ApvX-Bj-6FEIF9GP_duObzdReQkCA2ykcsPSmimw3IbJu7F4XbjZkwTCZL_vBiTaJlnQ7k3hXUzw30b3olDP2Dwc_W6Eh-CvT6s5ZxsFURCZJitfuqh82ezxHdT2lUdcDEMbELw9VpqUSBz0Dqh0tmfnFQyw4yX1be-jflT_0c8SvjyOFGRFScoxcPLq8TrrmpFvgxhT3MqowvQ9butxX6_4mTc3831FnJ6tQIihlBLH4DY11k38x3BBPzb0s9iVcEn7iczWbT0VrSr4A6g1ltATAHNChdzGTqGrhSN8JGG_PPCjJnHY_edaCmcPrUg",
     "scope": "admin rc141dc2-901e-4813-a25d-ef480cff1e26",
     "token_type": "Bearer",
     "expires_in": 3600
   }
   ```
2. Use the access token in all the following API calls. Sample curl request:
   ```bash
   curl --location --request GET 'https://one.zuora.com/scim/v2/Schemas' \
     --header 'Authorization: Bearer eyJraWQiOiIxNTYwMDBkMi1lY2FjLTQxMGYtOTJmYy02Y2IxMjU1YjQ3NTAiLCJhbGciOiJSUzI1NiJ9.eyIzdWIiOiI1MWExZDAyNC1iN2NjLTRkM2QtOGQwYi1kZDdiMjM5NTllMTAiLCJhdWQiOiI1MWExZDAyNC1iN2NjLTRkM2QtOGQwYi1kZDdiMjM5NTllMTAiLCJuYmYiOjE2OTA1MzcyODksInNjb3BlIjpbImFkbWluIiwiZWMxNDFkYzItOTAxZS00ODEzLWEyNWQtZWY0ODBjZmYxZTI2Il0sImlzcyI6Imh0dHA6XC9cL2xvY2FsaG9zdDo5OTAwIiwiZXhwIjoxNjkwNTQwODg5LCJpYXQiOjE2OTA1MzcyODl9.NMZV-aERA8lTKPPsMtk_WK9ApvX-Bj-6FEIF9GP_duObzdReQkCA2ykcsPSmimw3IbJu7F4XbjZkwTCZL_vBiTaJlnQ7k3hXUzw30b3olDP2Dwc_W6Eh-CvT6s5ZxsFURCZJitfuqh82ezxHdT2lUdcDEMbELw9VpqUSBz0Dqh0tmfnFQyw4yX1be-jflT_0c8SvjyOFGRFScoxcPLq8TrrmpFvgxhT3MqowvQ9butxX6_4mTc3831FnJ6tQIihlBLH4DY11k38x3BBPzb0s9iVcEn7iczWbT0VrSr4A6g1ltATAHNChdzGTqGrhSN8JGG_PPCjJnHY_edaCmcPrUg' \
     --header 'Content-Type: application/json'
   ```


SCIM

The Object Query API contains GET operations that allow you to query objects in your Zuora tenant in an efficient, consistent, and flexible manner.

With the `expand[]` and `filter[]` query parameters, you have the flexibility to retrieve related object information in a single call and define the returned response that best suits your needs.
You can also use the `fields[]` query parameter to define which fields are returned in the response for a given object.
The `sort[]` query parameter allows you to sort the results in ascending or descending order based on the specified field.

These parameters are case-insensitive matching.

For general Object Queries limitations and comprehensive introduction to these query parameters, see [Expand, filter, fields, and sort](https://developer.zuora.com/docs/guides/expand-filter-fields-sort/).

For filterable, expandable, and sortable fields on each object, refer to the Query Parameters section for each API operation.


Object Queries

Use operations to generate invoices and credit memos, collect payments for posted invoices, and generate previews of future invoice items for customer accounts.


Operations

Orders are contractual agreements between merchants and customers. 

You can create multiple subscriptions and subscription amendments at once in a single order. All the operations on subscriptions in orders are done by order actions. 
You can also create order line items to support your non-subscription based business models. 

Zuora calculates order delta metrics when orders take place. You can retrieve order delta metrics and measure billed and unbilled amounts by order.

For more information about Orders, see <a href="https://knowledgecenter.zuora.com/Zuora_Billing/Manage_accounts%2C_subscriptions%2C_and_non-subscription_transactions/Manage_subscription_transactions/Orders/AA_Overview_of_Orders/A_Overview_of_Orders" target="_blank">Overview Of Orders</a>. 
To learn how orders interacts with billing accounts, subscriptions, and product catalog, see [Orders API tutorials](https://developer.zuora.com/docs/get-started/api-tutorials/orders-tutorials/order-basics) which include orders code samples. You can also refer [Zuora object model](https://developer.zuora.com/v1-api-reference/object-model/) for more details. 


Orders

You need to have the [Orders](https://knowledgecenter.zuora.com/Zuora_Billing/Subscriptions/Orders) or [Orders Harmonization](https://knowledgecenter.zuora.com/Zuora_Billing/Subscriptions/Orders/Orders_Harmonization) feature enabled to use this API.


Order Actions

Use order line item to launch non-subscription and unified monetization business models in Zuora, in addition to subscription business models.
For more information about order line items, see <a href="https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AA_Overview_of_Order_Line_Items" target="_blank">Order Line Items</a>.


Order Line Items

Use payment gateways to pass authorization, payments, and settlement data securely to and from the merchant's website to the merchant's processor. 

For more information about payment gateways, see <a href="https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/M_Payment_Gateways" target="_blank">Payment Gateways</a>.


Payment Gateways

Gateway reconciliation is the process of verifying that the electronic payment and refund transactions processed in Zuora match the transactions reported by the gateway. 
For example, if Zuora processed 200 transactions through a gateway, you should see the same number of transactions on the gateway's reconciliation report, sometimes also called the settlement report.

You can complete the following Gateway Reconciliation tasks through API:
- [Settle a payment](https://developer.zuora.com/api-references/api/operation/POST_SettlePayment/)
- [Reject a payment](https://developer.zuora.com/api-references/api/operation/POST_RejectPayment/)
- [Reverse a payment](https://developer.zuora.com/api-references/api/operation/POST_ReversePayment/)
- [Reconcile a refund](https://developer.zuora.com/api-references/api/operation/POST_ReconcileRefund/)


Payment Gateway Reconciliation

A Payment Method Snapshot is a copy of the particular Payment Method used in a transaction. If the Payment Method is deleted, the Snapshot continues to retain the data used in each of the past transactions. 
As such, the Snapshot helps with display of historical transactions, integrations to external systems, and reporting.


Payment Method Snapshots

The PaymentMethodTransactionLog object contains payment method transaction log data.

You can use the [CRUD: Retrieve a payment method transaction log](https://developer.zuora.com/v1-api-reference/api/operation/Object_GETPaymentMethodTransactionLog/) operation to export such data.


Payment Method Transaction Logs

Payment methods represents payment method details associated with a customer account.


Payment Methods

Zuora Payment Method Updater (PMU) enables merchants to automatically incorporate changes made to a customer's credit cards. For more information about Zuora PMU, see <a href="https://knowledgecenter.zuora.com/Zuora_Payments/Payment_Method_Updater" target="_blank">Payment Method Updater</a>.


Payment Method Updater

Use payment runs to collect payments using electronic payment methods, for example, credit cards and ACH.
For more information about payment runs, see <a href="https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/K_Payment_Operations/CA_Payment_Runs/A_Introduction_to_Payment_Runs" target="_blank">Payment Runs</a>.


Payment Runs

Payment profiles enable payment flexibility for subscribers by allowing payment methods to be associated with specific subscriptions. 

To learn more about the configuration and usage of Payment Profiles, see <a href="https://knowledgecenter.zuora.com/Zuora_Payments/Payment_Operations/Payment_Profiles" target="_blank">Payment Profiles</a>.  


Payment Profiles

Use payment schedules to split invoice or account balances into several installments and automatically process payments for the installments.
For more information about payment schedules, see <a href="https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Payment_Schedules/A_Payment_Schedules_overview" target="_blank">Payment Schedules</a>.


Payment Schedules

Use payment transaction logs to export logs of all transactions from Zuora to the Gateway for Payments.


Payment Transaction Logs

The Delayed Capture feature allows you to authorize the availability of funds for a transaction but delay the capture of funds until a later time.

You can use the [Create authorization](https://developer.zuora.com/api-references/api/operation/POST_CreateAuthorization/) operation to authorize a payment amount before capturing the payment. 
Subsequently, you can use [Create a payment](https://developer.zuora.com/api-references/api/operation/POST_CreatePayment) or [Create an order](https://developer.zuora.com/api-references/api/operation/POST_Order/) to capture the authorized funds, or use [Cancel authorization](https://developer.zuora.com/api-references/api/operation/POST_CancelAuthorization) to cancel the authorization.


Payment Authorization

Use payments to process payments, for example, automate recurring payments, manage overpayments, and create refunds.
For more information about payments, see <a href="https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/K_Payment_Operations" target="_blank">Payments</a>.


Payments

The Prepaid with Drawdown feature is a pricing model for consumption-based services, such as data storage. Under this model, customers pay upfront to receive a number of units, usually for a period of time like a month or a year. Then they consume against that prepayment balance in a use-it-or-lose-it fashion, with a possibility of topping up more units or being charged for any overage. This model strikes a balance between upfront commitment and the pure pay-as-you-go pricing models. For more information, see <a href="https://knowledgecenter.zuora.com/Zuora_Billing/Bill_your_customers/Bill_for_usage_or_prepaid_products/Advanced_Consumption_Billing/Prepaid_with_Drawdown" target="_blank">Prepaid with Drawdown</a>.


Prepaid with Drawdown

**Note** - The APIs in this section are legacy APIs. Zuora recommends using the newer, faster APIs for managing products and catalogs more efficiently instead.
For more information, see our latest <a href="https://developer.zuora.com/v1-api-reference/api/tag/Commerce/"
target="_blank">Commerce API</a>.


Use product charge definitions to define the attributes that can determine
the charge behavior, such as billing attributes, pricing attributes, taxation
attributes, or accounting attributes.\n\nThe Product Charge Definition object
is in the **Early Adopter** phase. We are actively soliciting feedback from
a small set of early adopters before releasing it as generally available. If
you are interested, please reach out to your CSM. 


Product Charge Definitions

**Note** - The APIs in this section are legacy APIs. Zuora recommends using the newer, faster APIs for managing products and catalogs more efficiently instead.
For more information, see our latest <a href="https://developer.zuora.com/v1-api-reference/api/tag/Commerce/"
target="_blank">Commerce API</a>.


Use product rate plan definitions to reuse charges in different product
rate plans. The Product Rate Plan Definition object is in the **Early Adopter**
phase. We are actively soliciting feedback from a small set of early adopters
before releasing it as generally available. If you are interested, please reach
out to your CSM. 


Product Rate Plan Definitions

**Note** - The APIs in this section are legacy APIs. Zuora recommends using the newer, faster APIs for managing products and catalogs more efficiently instead.
For more information, see our latest <a href="https://developer.zuora.com/v1-api-reference/api/tag/Commerce/"
target="_blank">Commerce API</a>.


To manage product rate plan charge tiers, use the [Product Rate Plan
Charges](https://developer.zuora.com/api-references/api/tag/Product-Rate-Plan-Charges)
operations instead to update the corresponding product rate plan charge with all
the tiers.


Product Rate Plan Charge Tiers

**Note** - The APIs in this section are legacy APIs. Zuora recommends using the newer, faster APIs for managing products and catalogs more efficiently instead.
For more information, see our latest <a href="https://developer.zuora.com/v1-api-reference/api/tag/Commerce/"
target="_blank">Commerce API</a>.


A product rate plan charge represents a charge model or a set of fees
associated with a product rate plan, which is the part of a product that your
customers subscribe to. Each product rate plan can have multiple product rate
plan charges.


Product rate plan charges can be of three types: one-time fees, recurring fees,
and usage fees. For example, the $50 activation fee for the Topaz product rate
plan is a one-time product rate plan charge.


Product Rate Plan Charges

**Note** - The APIs in this section are legacy APIs. Zuora recommends using the newer, faster APIs for managing products and catalogs more efficiently instead.
For more information, see our latest <a href="https://developer.zuora.com/v1-api-reference/api/tag/Commerce/"
target="_blank">Commerce API</a>.


A product rate plan is the part of a product that your customers subscribe
to. Each product can have multiple product rate plans, and each product rate plan
can have multiple product rate plan charges, which are fees for products and their
product rate plans.


Product Rate Plans

**Note** - The APIs in this section are legacy APIs. Zuora recommends using the newer, faster APIs for managing products and catalogs more efficiently instead.
 For more information, see our latest <a href="https://developer.zuora.com/v1-api-reference/api/tag/Commerce/"
 target="_blank">Commerce API</a>.


 A product is an item or service that your company sells. In the subscription
 economy, a product is generally a service that your customers subscribe to rather
 than a physical item that they purchase one time. For example, customers subscribe
 to a service that provides them a car when and where they need a car rather than
 buying a car outright.


 A Product object contains all of the items in a specific product, especially product
 rate plans and product rate plan charges. Each Product object can have multiple
 rate plans, which in turn can each have multiple rate plan charges. Each rate
 plan charge can have multiple tiers. Taken together, all of these items create
 a single product.


 Customers subscribe to products that are in your product catalog. Product objects
 collectively compose your product catalog. You create your product catalog by
 creating products. As soon as you create your first product, you create your product
 catalog.


Products

A Ramp is a time container to associate with rate plan charges in your subscription. Inside the Ramp, you can further define a set of Ramp Intervals (time-based periods) where products or pricing can change. These periods are sub time containers to enable you to report out-of-the-box metrics based on Ramp Intervals.

**Notes**: You must have both the Ramps feature and Orders feature enabled for your tenant to use the Ramps operations.

For more information, see <a href="https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Ramps_and_Ramp_Metrics" target="_blank">Ramps and Ramp Metrics</a>.


Ramps

A rate plan is part of a subscription or an amendment to a subscription, and it comes from a product rate plan. Like a product and its product rate plans, a subscription can have one or more rate plans. 
Rate plans are sometimes called subscription rate plans. Rate plans that are part of an amendment are sometimes called amendment rate plans.

Rate plans represent a price or a collection of prices for a service you sell. An individual rate plan contains all charges specific to a particular subscription.


Rate Plans

Zuora allows you to issue and track refunds on payments. Similar to external payments, users can enter external refunds to track refunds that have been performed outside of Zuora Payments (for example, by issuing a check). 
In addition, you can make electronic refunds using our supported payment gateways, which will automatically refund money to the customer.


Refunds

If you are an <a href="https://knowledgecenter.zuora.com/Zuora_Billing/Enable_Order_to_Revenue" target="_blank">Order to Revenue</a> user, you can use the Regenerate operations to regenerate transactions objects.     


Regenerate

The REST API used in Payment Pages 2.0 are CORS (Cross-Origin Resource Sharing) enabled and therefore requires a digital signature. 

You can use the [Generate an RSA signature](https://developer.zuora.com/v1-api-reference/api/operation/POST_RSASignatures/) operation to generate the required digital signature and token for a Payment Pages 2.0 form, then use the [Decrypt an RSA signature](https://developer.zuora.com/v1-api-reference/api/operation/POST_DecryptRSASignatures/) operation to decrypt the signature to validate the signature and key." 


RSA Signatures

You can create billing document sequence sets through the REST API or the Zuora UI, allowing distinct numbering sequences for billing documents, payments, and refunds. 

To create a billing document sequence set through the Zuora UI, see <a href="https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Billing_Settings/Prefix_and_Numbering_Configuration_for_Billing_Documents/Create_Billing_Document_Sequence_Sets" target="_blank">Create Billing Document Sequence Sets</a> for more information.


Sequence Sets

The Setting API provides a central API for managing settings in your Zuora tenant.

If you use Postman, you can import the Settings API endpoints as a collection into your Postman app and try out different requests to learn how the API works.
You can sign up for a free account on the [Postman website](https://identity.getpostman.com/signup) and download the app in case you do not use Postman yet.


Settings

A light-weight API to sign up customers and subscribe. 

You need to have the [Orders](https://knowledgecenter.zuora.com/Zuora_Billing/Subscriptions/Orders) or [Orders Harmonization](https://knowledgecenter.zuora.com/Zuora_Billing/Subscriptions/Orders/Orders_Harmonization) feature enabled to use this API.


Sign Up

A subscription is a product or service that has recurring charges,
such as a monthly flat fee or charges based on usage. Subscriptions can also include
one-time charges, such as activation fees. Every subscription must be associated
with an account. At least one active account must exist before any subscriptions
can be created.


For more information, see <a href="https://knowledgecenter.zuora.com/Billing/Subscriptions/Subscriptions"
target="_blank">Subscriptions</a>.


Subscriptions

An omnichannel subscription is a subscription originating from external and source systems, such as the Apple App Store, Google Play Store, and Roku Store. 

To create, update, delete, or retrieve an omnichannel subscription, you must turn on the Omni-Channel Subscription feature. For more information, see <a href="https://docs.zuora.com/en/zuora-billing/manage-accounts-subscriptions-and-non-subscriptions/manage-subscription-transactions/common-subscription-information/omni-channel-subscription"
target="_blank">Omni-Channel Subscription</a>.  


Omnichannel Subscriptions

A summary journal entry is a summary of Zuora transaction amounts organized by accounting code and general ledger segments. A segment adds more reporting granularity through business dimensions, such as country or product. 

For more information, see <a href="https://knowledgecenter.zuora.com/Billing/Finance/F_Summary_Journal_Entries/A_SJE_Introduction" target="_blank">Summary Journal Entries Introduction</a>


Summary Journal Entries

The Summary Statement feature provides a comprehensive overview of billing activities for each account using HTML templates that compile data like invoices, credit memos, payments, and more.  The associated APIs help automate the creation and management of these statements. See <a href="https://knowledgecenter.zuora.com/Zuora_Billing/Zuora_Billing_Reporting/Account_Summary_Statement" target="_blank">Account Summary Statements </a> for more information.


Summary Statements

The TaxationItem object is used to add a tax amount to an invoice item. In the typical use case, the tax amount that you specify in the object is calculated by <a href="https://knowledgecenter.zuora.com/Billing/Taxes/A_Zuora_Tax" target="_blank">Z-Tax</a> or a third-party tax engine such as <a href="https://knowledgecenter.zuora.com/Billing/Taxes/Direct_Avalara_Integration" target="_blank">Avalara</a> or <a href="https://knowledgecenter.zuora.com/Billing/Taxes/Additional_resources_on_taxes/AA_Connect_Tax_Engines" target="_blank">Connect tax engine</a>.

Changes that you make with this object affect the product charges in your product catalog, but not the charges in existing subscriptions.


Taxation Items

Consumption of a billable service or resource (such as database storage space or bundles of emails sent) provides the basis for some charge models - simple usage, tiered pricing, or volume pricing. 
To make this work, usage must be tracked in the system and usage charges must be calculated and invoiced. 
Usage is always billed in arrears - for example, you might bill customers in February for their January usage. Usage can be billed on a recurring monthly, quarterly, semi-annual, or annual basis.

### Limitations for dynamic pricing usage charges  

Legacy Billing Usage APIs (for example, "Upload a usage file" and the "CRUD: Create/Update/Delete a   usage record" operations) do not support usage records that are associated with a dynamic pricing   usage charge. When a usage record is associated with a product rate plan charge that is configured   for dynamic pricing, these endpoints reject the request and do not create, update, or delete the record. For dynamic pricing usage charges, usage events must be ingested through Mediation  (for example, via Meters and the Rating processor) rather than through the legacy Billing usage upload APIs. 

For more information about working with usage data, see <a href="https://docs.zuora.com/en/zuora-billing/bill-your-customer/usage-billing/usage-billing---prepayment-credits-and-commitment" target="_blank">Usage</a>.


Usage

A workflow is a sequence of tasks that are performed based on predefined logic. A workflow improves efficiency and reduces errors by automating a series of complex tasks that otherwise need to be performed manually and repetitively.

For more information, see <a href="https://knowledgecenter.zuora.com/Central_Platform/Workflow" target="_blank">Workflow</a>.


Workflows

**Note:** You can only use the operations in this section if you have the Billing - Revenue Integration feature enabled. See <a href="https://knowledgecenter.zuora.com/Zuora_Revenue/Billing_-_Revenue_Integration" target="_blank">Billing - Revenue Integration</a> for more information.
The APIs in this section are legacy APIs. Zuora recommends using the newer, faster APIs for managing products and catalogs more efficiently instead. For more information, see our latest <a href="https://developer.zuora.com/v1-api-reference/api/tag/Commerce/" target="_blank">Commerce API</a>.


Zuora Revenue Integration

developers/api-docs/1-api/legacy-api-reference//db/organizations/zuora/repositories/prod-sitemap/content/documents/external_publications/api_reference/json/older_api_reference_20251114.json

Legacy API Reference

developers/api-docs/1-api/api-overview-new

Check our API reference for your integration

API docs

iframe test

Zuora’s original, 100% coverage, billing, payments, and platform API

Welcome to Zuora Product Documentation

Explore our rich library of product information

zuora-footer