# API Reference Welcome to the v1 API reference for the Zuora Billing, Payments, and Platform! To learn about the common use cases of the Zuora v1 API, check out the [API Tutorials](https://developer.zuora.com/docs/get-started/tutorials/). **Important**: This API Reference only showcases the parameters, fields, and behaviors available for the latest API minor version (`2025-08-12`). For more information about Zuora API versions, see [API versions](https://developer.zuora.com/v1-api-reference/api-versions/) and [API upgrades](https://developer.zuora.com/v1-api-reference/api-upgrades/). We recommend that you upgrade to the latest API version to take advantage of the latest Zuora capabilities. For instructions about upgrading the API version, see [API upgrade guide](https://developer.zuora.com/v1-api-reference/api-upgrade-guide/). Try the v1 API in our Postman collection: Run In Postman 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](https://developer.zuora.com/v1-api-reference/older-api/overview/). ### More OpenAPI specification options To support your integration with our OpenAPI specifications, whether using in-house solutions or third-party tools, we provide the following resources: - **Order-to-Cash operations (detailed)**: Download Order-to-Cash OpenAPI spec, which includes full descriptions and examples - **Order-to-Cash operations (compact)**: Download Order-to-Cash Compact OpenAPI spec, which excludes descriptions and code examples. - **Full OpenAPI spec (compact)**: Download Compact OpenAPI Spec, which covers the entire API set without descriptions or samples. If you need a different API specification beyond the options above, contact Zuora Global Support, and we will provide a custom spec tailored to your needs. Version: 2026-02-20 ## Servers US Developer & Central Sandbox (incl. Test Drive) ``` https://rest.test.zuora.com ``` US API Sandbox Cloud 1 ``` https://rest.sandbox.na.zuora.com ``` US API Sandbox Cloud 2 ``` https://rest.apisandbox.zuora.com ``` US Production Cloud 1 ``` https://rest.na.zuora.com ``` US Production Cloud 2 ``` https://rest.zuora.com ``` 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 ``` APAC Developer & Central Sandbox ``` https://rest.test.ap.zuora.com ``` APAC Production ``` https://rest.ap.zuora.com ``` ## Security ### bearerAuth Use `Bearer {{token}}` in the `Authorization` header for authentication. Type: http Scheme: bearer ### basicAuth 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. Type: http Scheme: basic ## Download OpenAPI description [API Reference](https://developer.zuora.com/_bundle/v1-api-reference/api/index.yaml) ## OAuth 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. ### Create an OAuth token - [POST /oauth/token](https://developer.zuora.com/v1-api-reference/api/oauth/createtoken.md): Creates a bearer token that enables an OAuth client to authenticate with the Zuora REST API. The OAuth client must have been created using the Zuora UI. See Authentication for more information. Note: When using this operation, do not set any authentication headers such as Authorization, apiAccessKeyId, or apiSecretAccessKey. You should not use this operation to generate a large number of bearer tokens in a short period of time; each token should be used until it expires. If you receive a 429 Too Many Requests response when using this operation, reduce the frequency of requests. This endpoint is rate limited by IP address. For the rate limit information of authentication, see Rate and concurrent request limits. ## Commerce 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.' ### Create a product rate plan charge with Dynamic Pricing - [POST /commerce/charges](https://developer.zuora.com/v1-api-reference/api/commerce/createproductrateplanchargewithdynamicpricing.md): Create a product rate plan charge (PRPC) in the Product Catalog. Use this endpoint to configure Dynamic Pricing, including default pricing at the charge level and conditional rate cards evaluated by attribute values. ### Update a product rate plan charge with Dynamic Pricing - [PUT /commerce/charges](https://developer.zuora.com/v1-api-reference/api/commerce/updateproductrateplanchargewithdynamicpricing.md): Update an existing product rate plan charge (PRPC). Use this API to update default pricing and/or conditional rate cards. ### Query a product rate plan charge with Dynamic Pricing - [POST /commerce/charges/query](https://developer.zuora.com/v1-api-reference/api/commerce/queryproductrateplanchargewithdynamicpricing.md): Returns a product rate plan charge (PRPC) by evaluating Dynamic Pricing against the provided attribute values. If a matching rate-card row is found, its pricing is returned; otherwise, the default charge-level pricing is used (if defined). This operation can be used to simulate pricing resolution without creating or updating the charge. ### Create a product with plans and charges - [POST /commerce/products](https://developer.zuora.com/v1-api-reference/api/commerce/createproduct.md): Create a product in the Product Catalog with one or more plans and charges. Charges can be usage (per-unit), recurring (flat fee), or other supported models. ### Update a product - [PUT /commerce/products](https://developer.zuora.com/v1-api-reference/api/commerce/updateproduct.md): Updates an existing product in the Product Catalog. Use this API to update core product fields such as name, description, category, effective dates, and custom fields. ### Create a product rate plan - [POST /commerce/plans](https://developer.zuora.com/v1-api-reference/api/commerce/createplan.md): Create a product rate plan (Plan) under an existing product. A plan includes one or more charges. Each charge must include: - name - charge_model - charge_type - bill_cycle - trigger_event - end_date_condition - pricing Optional charge fields include: unit_of_measure, list_price_base, and accounting (with accounting_code, deferred_revenue_account, recognized_revenue_account). ### Update a product rate plan - [PUT /commerce/plans](https://developer.zuora.com/v1-api-reference/api/commerce/updateproductrateplan.md): Updates an existing Product Rate Plan (PRP) in the Product Catalog. Use this API to update core plan fields such as name, description, grade, and effective dates. ### Query product rate plan details - [POST /commerce/plans/query](https://developer.zuora.com/v1-api-reference/api/commerce/querycommerceproductrateplans.md): Retrieve details of a single product rate plan (PRP) from the Product Catalog. You can expand associated product rate plan charges for each plan. This operation is a strict lookup and requires product_rate_plan_key. It does not support attributes or other list-style filters. To browse or filter plans (including by attributes), use the "Query product rate plans" operation (POST /commerce/plans/list). ### Query product rate plans - [POST /commerce/plans/list](https://developer.zuora.com/v1-api-reference/api/commerce/querycommerceplanslist.md): Queries product rate plans (PRPs) from the Product Catalog using filters such as plan ID, name, or product ID. You can optionally expand related Product Rate Plan Charges (PRPCs) in the response. ### Retrieve a product by key - [POST /commerce/products/{product_key}](https://developer.zuora.com/v1-api-reference/api/commerce/getproductbykey.md): Retrieves detailed information about a specific product by its unique product number or ID. You can optionally specify related objects to expand in the request body. ### Query legacy products from the Product Catalog - [POST /commerce/legacy/products/list](https://developer.zuora.com/v1-api-reference/api/commerce/querylegacyproducts.md): This operation is functionally equivalent to the "Query products from the Product Catalog" operation, except that it returns results in the V1 response format. It is primarily intended for customers migrating from older V1 integrations who want to use new Commerce capabilities — such as Dynamic Pricing—without refactoring their existing integrations. Unlike the "Query products from the Product Catalog" operation, this operation does not retrieve a different set of products. It returns the same product catalog data as the newer operation, but formatted in a flattened V1-style response structure that: - Uses flattened fields instead of grouped objects such as discount_options, revenue, or bill_cycle. - Retains V1 field names for easier migration from existing V1 operations, for example: - Retrieve a product rate plan charge. - Retrieve a product rate plan. - Retrieve a product. - Keeps certain objects, such as netsuite and customFields, as grouped structures instead of flattening them. Recommended Usage - Use this operation if you are migrating from V1 APIs and need to maintain compatibility with existing integrations. - For new integrations, use the "Query products from the Product Catalog" operation instead, as it returns structured responses optimized for the Commerce feature. ### Update a product rate plan charge tier - [PUT /commerce/tiers](https://developer.zuora.com/v1-api-reference/api/commerce/updatetier.md): Updates the price and other editable attributes, when supported, for a specific Product Rate Plan Charge Tier. ### Query purchase options by PRP ID - [POST /commerce/purchase-options/list](https://developer.zuora.com/v1-api-reference/api/commerce/querypurchaseoptionsbyprpid.md): Retrieves one or more product rate plans (PRPs) from the Product Catalog based on specified filters such as product ID or PRP ID. You can optionally expand related product rate plan charges (PRPCs) in the response. ## Accounts 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. ### Create an account - [POST /v1/accounts](https://developer.zuora.com/v1-api-reference/api/accounts/post_account.md): Creates a customer account with a payment method, a bill-to contact, and optional sold-to and ship-to contacts. Request and response field descriptions and sample code are provided. Use this operation to optionally create a subscription, invoice for that subscription, and collect payment through the default payment method. The transaction is atomic; if any part fails for any reason, the entire transaction is rolled back. This operation is CORS Enabled, so you can use client-side Javascript to invoke the call. ### Notes 1. The account is created in active status. 2. If the autoPay field is set to true in the request, you must provide one of the paymentMethod, creditCard, or hpmCreditCardPaymentMethodId field, but not multiple. The one provided becomes the default payment method for this account. If the credit card information is declined or cannot be verified, no account is created. 3. Customer accounts created with this call are automatically be set to Auto Pay. 4. If the invoiceDeliveryPrefsEmail field is not specified in the request, the account's email delivery preference is always automatically set to false, no matter whether the workEmail or personalEmail field is specified. ### Defaults for customerAcceptanceDate and serviceActivationDate Default values for customerAcceptanceDate and serviceActivationDate are set as follows. | | serviceActivationDate(SA) specified | serviceActivationDate (SA) NOT specified | | ------------- |:------------- | :-----| | customerAcceptanceDate (CA) specified| SA uses value in the request call; CA uses value in the request call| CA uses value in the request call;SA uses CE as default | | customerAcceptanceDate (CA) NOT specified | SA uses value in the request call; CA uses SA as default | SA and CA use CE as default | This call supports a subset of the functionality of our Create an order call. For use cases where you create a subscription and a billing account at the same time, we recommend using "Create an order" instead of this call. The Orders call has the following advantages: - Provides options for managing the entire subscription lifecycle from creation through to cancellation using different order actions. - Allows the creation or modifying of multiple subscriptions in a single order. - Allows a single order to combine both recurring subscription digital goods or services with order line items for physical goods. - Orders are treated as atomic transactions. If any part fails, the entire order, subscription, and billing account creation are rolled back. You should use this call if you need to create a standalone billing account, and create orders, subscriptions, standalone invoices, or dynamic usage charges later. There are no deprecation plans for this call and we will continue to support this call for existing users. ### Delete an account - [DELETE /v1/accounts/{account-key}](https://developer.zuora.com/v1-api-reference/api/accounts/delete_account.md): Deletes a specific account asynchronously. Notes and Limitations: - For account deletion, the system will start a backend job to remove all transactions under the accounts and change the status of the accounts to 'Cancelled'. This backend job is asynchronous and will take some time, depending on the job size. - An account cannot be deleted when the account is either the invoice owner or the subscription owner of a subscription and the subscription's invoice owner and subscription owner are two different accounts. An exception to this limitation is if the Enable Force Deletion for Account? setting is set to Yes, you can force delete an account that is the subscription owner of a subscription while the invoice owner is a different account. Force deleting this account deletes all its subscriptions, but the relevant invoices will not be impacted. - An account cannot be deleted if this account has ever been involved in an Owner Transfer amendment or order action, either as the current owner or as the previous owner. ### Retrieve an account - [GET /v1/accounts/{account-key}](https://developer.zuora.com/v1-api-reference/api/accounts/get_account.md): Retrieves basic information about a customer account. This operation is a quick retrieval that doesn't include the account's subscriptions, invoices, payments, or usage details. Use Get account summary to get more detailed information about an account. ### Update an account - [PUT /v1/accounts/{account-key}](https://developer.zuora.com/v1-api-reference/api/accounts/put_account.md): Updates a customer account by specifying the account-key. ### Notes 1. Only the fields to be changed should be specified. Any field that is not included in the request body will not be changed. 2. If an empty field is submitted with this operation, the corresponding field in the account is emptied. 3. Email addresses: If no email addresses are specified, no change is made to the email addresses or to the email delivery preference. If either the personalEmail or workEmail of billToContact is specified (or both), the system updates the corresponding email address(es) and the email delivery preference is set to true. (In that case, emails go to the workEmail address, if it exists, or else the personalEmail.) On the other hand, if as a result of this call both of the email addresses for the account are empty, the email delivery preference is set to false. 4. The Bill To, Sold To, and Ship To contacts are separate contact entities. However, if you set the soldToSameAsBillTo field to true when creating an account, the Bill To and Sold To contacts will refer to the same contact entity. As a result, updating either contact will update both. The same behavior applies to the shipToSameAsBillTo field and the Ship To contact. In this case, if you want to update only one of the contacts, you must create a new contact and then update the Bill To, Sold To, or Ship To contact to reference the newly created one. ### List payment methods of an account - [GET /v1/accounts/{account-key}/payment-methods](https://developer.zuora.com/v1-api-reference/api/accounts/get_acountpaymentmethods.md): Retrieves the payment methods of the specified customer account. Note: This operation also supports retrieving custom payment methods created through the Open Payment Method service. ### Retrieve configuration of cascading payment methods for an account - [GET /v1/accounts/{account-key}/payment-methods/cascading](https://developer.zuora.com/v1-api-reference/api/accounts/getaccountpaymentmethodcascading.md): Zuora provides the Cascading Payment Method feature to dynamically retry the failed payment with alternative payment methods according to a predefined priority list. Use this API operation to retrieve the configuration information for Cascading Payment Method of a specified account, including the cascading consent value and the priority list of payment methods. Before you use this API operation, ensure that the Cascading Payment Method feature is enabled. For more information about the Cascading Payment Method feature, see Cascade payment methods. ### Configure cascading payment methods for an account - [PUT /v1/accounts/{account-key}/payment-methods/cascading](https://developer.zuora.com/v1-api-reference/api/accounts/putaccountpaymentmethodcascading.md): Zuora provides the Cascading Payment Method feature to dynamically retry the failed payment with alternative payment methods according to a predefined priority list. Use this API operation to configure the cascading consent for a specified account and set up the priority list of payment methods to be used in Cascading Payment Method. Before you use this API operation, ensure that the Cascading Payment Method feature is enabled. For more information about the Cascading Payment Method feature, see Cascade payment methods. ### Retrieve the default payment method of an account - [GET /v1/accounts/{account-key}/payment-methods/default](https://developer.zuora.com/v1-api-reference/api/accounts/get_acountdefaultpaymentmethod.md): Retrieves the default payment method of the specified customer account. Notes: This operation also supports retrieving the custom payment method created through the Open Payment Method service. This operation only works with an electronic payment method and does not work with non-electronic payment methods. ### Retrieve an account summary - [GET /v1/accounts/{account-key}/summary](https://developer.zuora.com/v1-api-reference/api/accounts/get_accountsummary.md): Retrieves detailed information about the specified customer account. The response includes the account information and a summary of the account’s subscriptions, invoices, payments, and usages. ### Notes Returns only the six most recent subscriptions based on the subscription updatedDate. Within those subscriptions, there may be many rate plans and many rate plan charges. These items are subject to the maximum limit on the array size. ## Contacts 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. ### Create a contact - [POST /v1/contacts](https://developer.zuora.com/v1-api-reference/api/contacts/post_createcontact.md): Creates a contact for a specified account. Each account must have at least one contact before it can be saved. You can add a maximum of 2000 contacts to an account. ### Delete a contact - [DELETE /v1/contacts/{contactId}](https://developer.zuora.com/v1-api-reference/api/contacts/delete_contact.md): Deletes a contact. ### Retrieve a contact - [GET /v1/contacts/{contactId}](https://developer.zuora.com/v1-api-reference/api/contacts/get_contact.md): Retrieves detailed information about a specific contact. ### Update a contact - [PUT /v1/contacts/{contactId}](https://developer.zuora.com/v1-api-reference/api/contacts/put_contact.md): Updates a contact for a specified account. You can update contacts for cancelled accounts. ### Transfer a contact - [PUT /v1/contacts/{contactId}/transfer](https://developer.zuora.com/v1-api-reference/api/contacts/transfercontent.md): This operation transfers contacts of the accounts within the Customer Hierarchy when removing the account. ### Scrub a contact - [PUT /v1/contacts/{contactId}/scrub](https://developer.zuora.com/v1-api-reference/api/contacts/put_scrubcontact.md): Scrubs the sensitive data of a specific contact. You can use this operation to replace all sensitive data in a contact and its related contact snapshot with dummy values that will be stored in Zuora databases. After scrubbing a contact, it is good practice to delete it. Otherwise, it might cause errors in subsequent operations. Note: To use this operation, you must ensure that the "Scrub Sensitive Data of Contact" billing permission is enabled in your user role. Contact your tenant administrator if you want to enable this permission. See Scrub Contacts for more information. ## Contact Snapshots Every time a contact is updated a snapshot is taken. ### Retrieve a contact snapshot - [GET /v1/contact-snapshots/{contact-snapshot-id}](https://developer.zuora.com/v1-api-reference/api/contact-snapshots/get_contactsnapshot.md): Retrieves detailed information about the snapshot of a contact, either a bill-to contact or sold-to contact. ## Sign Up 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 - [POST /v1/sign-up](https://developer.zuora.com/v1-api-reference/api/sign-up/post_signup.md): This call performs many actions. You can use this operation to implement the standard requirements for signing up a customer, such as validating the uniqueness of an account and limiting the number of subscriptions per account. Also, you can use this operation to create a subscription, generate an invoice, and collect payment for a new or existing customer. Note: You need to have the Orders or Orders Harmonization feature enabled to use this API. For a new customer, you can perform the following tasks in one call. Note that you can skip creating a payment meethod and still get the subscription and invoice successfully created. * Create an account * Create a payment method * Subscribe to a product in the product catalog and create a subscription * Generate an invoice * Collect payment For an existing customer, you can use an account identification field of an external system to specify the account. You can make make asynchronous requests when using the "Sign up" operation. This call supports a subset of the functionality of our Create an order call. We generally recommend using "Create an order" instead of this call because the Orders call has the following advantages: - Provides options for managing the entire subscription lifecycle from creation through to cancellation using different order actions. - Allows the creation or modifying of multiple subscriptions in a single order. - Allows a single order to combine both recurring subscription digital goods or services with order line items for physical goods. - Orders are treated as atomic transactions. If any part fails, the entire order, subscription, and billing account creation are rolled back. This call does have some unique abilities not supported by "Create an order". You should consider using this call when you need to: - Use Account UPSERT functionality by specifying a custom external identifier. - Limit the number of subscriptions on an account There are no deprecation plans for this call and we will continue to support this call. ## Orders 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 Overview Of Orders. To learn how orders interacts with billing accounts, subscriptions, and product catalog, see [Zuora object model](https://developer.zuora.com/v1-api-reference/object-model/). ### Preview an order - [POST /v1/orders/preview](https://developer.zuora.com/v1-api-reference/api/orders/post_previeworder.md): Notes: - This operation is only available if you have the Orders feature enabled. If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing functions for subscription and billing management and the new features on Zuora Billing. - The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. - You cannot preview enhanced discounts and usage charges. - You can skip the accounting period validation to avoid backdated subscription cancellation caused order preview failure. To skip the accounting period validation, submit a request at Zuora Global Support. Retrieves the preview of the charge metrics and invoice items of a specified order. Preview for subscriptions and order line items are both supported. This operation is only an order preview and no order is created. You can also use this operation to preview billing for a standalone order. For more information, see Preview billing for a standalone order. #### Billing preview behavior regarding draft invoices By default, the billing preview behavior regarding draft invoices is as below: - When you preview billing for your order and the order contains subscriptions only, the draft invoices are excluded. - When you preview billing for your order and the order contains order line items only, the draft invoices are included. - When you preview billing for an order that contains both subscriptions order line items, the draft invoices are included for both subscriptions and order line items. However, if you want to always exclude the draft invoices in billing preview, submit a request at Zuora Global Support. #### Limits on Orders API The limit of orders allowed on a subscription is 1000. The limit of order line items allowed in an order is 100. Zuora has the following limits on the Orders synchronous API to prevent performance degradation: - Up to 50 subscriptions are allowed in a single Create an order or Preview an order operation call. - Up to 50 order actions are allowed in a single Create an order or Preview an order operation call. - Up to 50 order actions are allowed on a single subscription in a Create an order or Preview an order operation call. If you have an Order that exceeds any limits of the above, Zuora recommends you use the following asynchronous API operations: - Create an order asynchronously - Preview an order asynchronously - Retrieve the status and response of a job for checking the status of the asynchronous API operations Zuora has the following limits on the Orders asynchronous API operations to prevent performance degradation: - Up to 300 subscriptions are allowed in a single Create an order asynchronously or Preview an order asynchronously operation call. - Up to 300 order actions are allowed in a single Create an order asynchronously or Preview an order asynchronously operation call. - Up to 300 order actions are allowed on a single subscription\ in a Create an order asynchronously or Preview an order asynchronously operation call. ### Preview an order asynchronously - [POST /v1/async/orders/preview](https://developer.zuora.com/v1-api-reference/api/orders/post_previeworderasynchronously.md): Notes: - This operation is only available if you have the Orders feature enabled. Orders is now generally available as of Zuora Billing Release 284 (August 2020). If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing functions for subscription and billing management and the new features on Zuora Billing. - The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. - You cannot preview enhanced discounts and usage charges. In the case where a normal "Preview an order" operation call will time out, use this operation instead to preview an order asynchronously. A job will be previewing the order in the back end; the job ID will be returned for tracking the job status and result. #### Billing preview behavior regarding draft invoices By default, the billing preview behavior regarding draft invoices is as below: * When you preview billing for your order and the order contains subscriptions only, the draft invoices are excluded. * When you preview billing for your order and the order contains order line items only, the draft invoices are included. * When you preview billing for an order that contains both subscriptions order line items, the draft invoices are included for both subscriptions and order line items. However, if you want to always exclude the draft invoices in billing preview, submit a request at Zuora Global Support. #### Limits on Orders API The limit of orders allowed on a subscription is 1000. The limit of order line items allowed in an order is 100. Zuora has the following limits on the Orders synchronous API to prevent performance degradation: * Up to 50 subscriptions are allowed in a single Create an order or Preview an order operation call. * Up to 50 order actions are allowed in a single Create an order or Preview an order operation call. * Up to 50 order actions are allowed on a single subscription in a Create an order or Preview an order operation call. If you have an Order that exceeds any limits of the above, Zuora recommends you use the following asynchronous API operations: * Create an order asynchronously * Preview an order asynchronously * Retrieve the status and response of a job for checking the status of the asynchronous API operations Zuora has the following limits on the Orders asynchronous API operations to prevent performance degradation: * Up to 300 subscriptions are allowed in a single Create an order asynchronously or Preview an order asynchronously operation call. * Up to 300 order actions are allowed in a single Create an order asynchronously or Preview an order asynchronously operation call. * Up to 300 order actions are allowed on a single subscription in a Create an order asynchronously or Preview an order asynchronously operation call. ### List orders - [GET /v1/orders](https://developer.zuora.com/v1-api-reference/api/orders/get_allorders.md): Note: This feature is only available if you have the Order Metrics feature enabled. As of Zuora Billing Release 284, Orders is generally available and the Order Metrics feature is no longer available as a standalone feature. If you are an existing Subscribe and Amend customer and want Order Metrics only, you must turn on Orders Harmonization. You can still keep the existing Subscribe and Amend API integrations to create and manage subscriptions. Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. Retrieves information about all orders in your tenant. You can set the status query parameter to an order status to retrieve orders in that order status. If you do not set a value for this query parameter, the query parameter has a default value all, and orders of all statuses are returned. By default, it returns the first page of the orders. ### Create an order - [POST /v1/orders](https://developer.zuora.com/v1-api-reference/api/orders/post_order.md): Note: This operation is only available if you have the Orders feature enabled. If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing functions for subscription and billing management and the new features on Zuora Billing. Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. You can use this operation to create subscriptions and make changes to subscriptions by creating orders. You can also use this operation to create order line items by creating orders. The following tutorials demonstrate how to use this operation: * Create a Subscription * Add a Product to a Subscription * Create a Ramp Deal * Add a Product Mid-Interval Update on a Ramp Deal * Add a Product in a Ramp Deal * Change the Terms and Conditions of a Ramp Deal * Change the Owner of a Subscription * Change the Terms and Conditions of a Subscription * Renew a Subscription * Renew a Subscription and Upgrade a Product * Replace a Product in a Subscription * Update a Product in a Subscription * Cancel a Subscription * Remove a Product from a Subscription * Create sales order line items * Associate order line items with new subscriptions * Return order line items You can also use this operation to create orders and save the orders as Scheduled Orders. In addition, you can use this operation to place a standalone order to subscribe without pre-defining a product catalog in Zuora Billing. For more information, see Create a subscription using a standalone order. Note: If you received a timeout error message when creating an order, the call is still running in the backend and the order will be created. The limit of orders allowed on a subscription is 1000. The limit of order line items allowed in an order is 100. Zuora has the following limits on the Orders synchronous API to prevent performance degradation: * Up to 50 subscriptions are allowed in a single Create an order or Preview an order operation call. * Up to 50 order actions are allowed in a single Create an order or Preview an order operation call. * Up to 50 order actions are allowed on a single subscription in a Create an order or Preview an order operation call. If you have an Order that exceeds any limits of the above, Zuora recommends you use the following asynchronous API operations: * Create an order asynchronously * Preview an order asynchronously * Retrieve the status and response of a job for checking the status of the asynchronous API operations Zuora has the following limits on the Orders asynchronous API operations to prevent performance degradation: * Up to 300 subscriptions are allowed in a single Create an order asynchronously or Preview an order asynchronously operation call. * Up to 300 order actions are allowed in a single Create an order asynchronously or Preview an order asynchronously operation call. * Up to 300 order actions are allowed on a single subscription in a Create an order asynchronously or Preview an order asynchronously operation call. Note: When you are to suspend a subcription (via the suspend order action), if in the same "Create an order" call you are to perform other subsequent order actions on the supscription to suspend, you must first resume the subscription (via a resume order action). Note: When using this operation to create an account, create a subscription, run billing, and collect payment in a single call, if any error occurs during the call, such as a payment processing failure and a tax engine failure, then all the other steps will be rolled back. This means that the invoice will not be generated, the subscription will not be created, and the account will not be created. Note: The characters #, ?, and / are not allowed in the Orders operations. ### Create an order asynchronously - [POST /v1/async/orders](https://developer.zuora.com/v1-api-reference/api/orders/post_createorderasynchronously.md): Note: This operation is only available if you have the Orders feature enabled. If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing functions for subscription and billing management and the new features on Zuora Billing. Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. In the case where a normal "Create an order" operation call will time out, use this operation instead to create an order asynchronously. A job will be creating the order in the back end; the job ID will be returned for tracking the job status and result. Note that this operation doesn't support auto-refund and invoice write-off during subscription cancellation. Use the "Create an order" operation instead. The limit of orders allowed on a subscription is 1000. The limit of order line items allowed in an order is 100. Zuora has the following limits on the Orders synchronous API to prevent performance degradation: * Up to 50 subscriptions are allowed in a single Create an order or Preview an order operation call. * Up to 50 order actions are allowed in a single Create an order or Preview an order operation call. * Up to 50 order actions are allowed on a single subscription in a Create an order or Preview an order operation call. If you have an Order that exceeds any limits of the above, Zuora recommends you use the following asynchronous API operations: * Create an order asynchronously * Preview an order asynchronously * Retrieve the status and response of a job for checking the status of the asynchronous API operations Zuora has the following limits on the Orders asynchronous API operations to prevent performance degradation: * Up to 300 subscriptions are allowed in a single Create an order asynchronously or Preview an order asynchronously operation call. * Up to 300 order actions are allowed in a single Create an order asynchronously or Preview an order asynchronously operation call. * Up to 300 order actions are allowed on a single subscription in a Create an order asynchronously or Preview an order asynchronously operation call. ### Delete an order - [DELETE /v1/orders/{orderNumber}](https://developer.zuora.com/v1-api-reference/api/orders/delete_order.md): Note: This operation is only available if you have the Orders feature enabled. If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing functions for subscription and billing management and the new features on Zuora Billing. Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. Deletes a specified order. * All the subscriptions changed by this order are deleted. After the deletion, the subscriptions are rolled back to the previous version. * All the order line items created in this order are deleted. You are not allowed to delete an order in the following situations: - The charges that are affected by this order are invoiced. - The order is reverted and in the Reverted status. ### Retrieve an order - [GET /v1/orders/{orderNumber}](https://developer.zuora.com/v1-api-reference/api/orders/get_order.md): Note: This feature is only available if you have the Order Metrics feature enabled. As of Zuora Billing Release 284, Orders is generally available and the Order Metrics feature is no longer available as a standalone feature. If you are an existing Subscribe and Amend customer and want Order Metrics only, you must turn on Orders Harmonization. You can still keep the existing Subscribe and Amend API integrations to create and manage subscriptions. Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. Retrieves the detailed information about a specified order. ### Update an order - [PUT /v1/orders/{orderNumber}](https://developer.zuora.com/v1-api-reference/api/orders/put_order.md): Notes: - This operation is only available if you have the Orders feature enabled. If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing functions for subscription and billing management and the new features on Zuora Billing. - Update an order is only valid for draft or scheduled orders. - This operation doesn't support auto-refund and invoice write-off during subscription cancellation. Use the "Create an order" operation instead. - You must provide full payload when using the "Update an order" operation. That is, if you want to edit one order action, you need to provide all other order actions in the payload. Otherwise, the other order actions will be removed. ### Delete an order asynchronously - [DELETE /v1/async/orders/{orderNumber}](https://developer.zuora.com/v1-api-reference/api/orders/deleteorderasynchronously.md): Note: This operation is only available if you have the Orders feature enabled. If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing\ functions for subscription and billing management and the new features on Zuora Billing. Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who\ onboard on Orders will have the Order Line Items feature enabled by default. Deletes a specified order. All the subscriptions changed by this order are deleted. After the deletion, the subscriptions are rolled back to the previous version. All the order line items created in this order are deleted. You are not allowed to delete an order in the following situations: - The charges that are affected by this order are invoiced. - The order is reverted and in the Reverted status. ### Retrieve the status and response of a job - [GET /v1/async-jobs/{jobId}](https://developer.zuora.com/v1-api-reference/api/orders/get_jobstatusandresponse.md): Note: This operation is only available if you have the Orders feature enabled. If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing functions for subscription and billing management and the new features on Zuora Billing. Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. Get the status and response of an asynchronous job. Currently, an asynchronous job created by "Create an order asynchronously" or "Preview an order asynchronously" is supported. ### List orders of a subscription owner - [GET /v1/orders/subscriptionOwner/{accountNumber}](https://developer.zuora.com/v1-api-reference/api/orders/get_ordersbysubscriptionowner.md): Note: This feature is only available if you have the Order Metrics feature enabled. As of Zuora Billing Release 284, Orders is generally available and the Order Metrics feature is no longer available as a standalone feature. If you are an existing Subscribe and Amend customer and want Order Metrics only, you must turn on Orders Harmonization. You can still keep the existing Subscribe and Amend API integrations to create and manage subscriptions. Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. Retrieves the detailed information about all orders for a specified subscription owner. Any orders containing the changes on the subscriptions owned by this account are returned. Note: You cannot retrieve detailed information about draft orders or scheduled orders through this operation. ### List orders by subscription number - [GET /v1/orders/subscription/{subscriptionNumber}](https://developer.zuora.com/v1-api-reference/api/orders/get_ordersbysubscriptionnumber.md): Note: This feature is only available if you have the Order Metrics feature enabled. As of Zuora Billing Release 284, Orders is generally available and the Order Metrics feature is no longer available as a standalone feature. If you are an existing Subscribe and Amend customer and want Order Metrics only, you must turn on Orders Harmonization. You can still keep the existing Subscribe and Amend API integrations to create and manage subscriptions. Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. Retrieves the detailed information about all orders for a specified subscription. You can set the status query parameter to an order status to retrieve orders in that order status. If you do not set a value for this query parameter, the query parameter has a default value all, and orders of all statuses are returned. ### List orders of an invoice owner - [GET /v1/orders/invoiceOwner/{accountNumber}](https://developer.zuora.com/v1-api-reference/api/orders/get_ordersbyinvoiceowner.md): Note: This feature is only available if you have the Order Metrics feature enabled. As of Zuora Billing Release 284, Orders is generally available and the Order Metrics feature is no longer available as a standalone feature. If you are an existing Subscribe and Amend customer and want Order Metrics only, you must turn on Orders Harmonization. You can still keep the existing Subscribe and Amend API integrations to create and manage subscriptions. Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. Retrieves the detailed information about all orders for a specified invoice owner. You can set the status query parameter to an order status to retrieve orders in that order status. If you do not set a value for this query parameter, the query parameter has a default value all, and orders of all statuses are returned. ### Update order custom fields - [PUT /v1/orders/{orderNumber}/customFields](https://developer.zuora.com/v1-api-reference/api/orders/put_updateordercustomfields.md): Note: This feature is only available if you have the Order Metrics feature enabled. As of Zuora Billing Release 284, Orders is generally available and the Order Metrics feature is no longer available as a standalone feature. If you are an existing Subscribe and Amend customer and want Order Metrics only, you must turn on Orders Harmonization. You can still keep the existing Subscribe and Amend API integrations to create and manage subscriptions. Note: To update the custom fields of an order line item, you must use the "Update an order line item" or "Update order line items" operation. Updates the custom fields of a specified order. ### Update subscription custom fields - [PUT /v1/subscriptions/{subscriptionNumber}/customFields](https://developer.zuora.com/v1-api-reference/api/orders/put_updatesubscriptioncustomfields.md): Note: This operation is only available if you have the Orders feature enabled. If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing functions for subscription and billing management and the new features on Zuora Billing. Updates the custom fields of a specified subscription. ### Update order action trigger dates - [PUT /v1/orders/{orderNumber}/triggerDates](https://developer.zuora.com/v1-api-reference/api/orders/put_ordertriggerdates.md): Note: This operation is only available if you have the Orders feature enabled. If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing functions for subscription and billing management and the new features on Zuora Billing. Updates the triggering dates for either of the following order actions: * CreateSubscription * AddProduct * UpdateProduct * RemoveProduct * RenewSubscription * TermsAndConditions ### Activate an order - [PUT /v1/orders/{orderNumber}/activate](https://developer.zuora.com/v1-api-reference/api/orders/put_orderactivate.md): Note: This operation is only available if you have the Orders feature enabled. If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing functions for subscription and billing management and the new features on Zuora Billing. Activate order is only available for draft orders. ### Cancel an order - [PUT /v1/orders/{orderNumber}/cancel](https://developer.zuora.com/v1-api-reference/api/orders/put_ordercancel.md): Note: This operation is only available if you have the Orders feature enabled. If you are an existing Zuora Subscribe and Amend customer, we recommend you enable Orders Harmonization to access the Orders feature. With Orders, you can access both existing functions for subscription and billing management and the new features on Zuora Billing. Note: Cancellation is only valid for draft or scheduled orders. If the order is not in draft or scheduled status, the API returns an error. ### Revert an order - [POST /v1/orders/{orderNumber}/revert](https://developer.zuora.com/v1-api-reference/api/orders/revertorder.md): Reverts an order though this operation. Note: This operation is only available if you have the following features turned on: - Orders - Single Version Subscription For information on what orders can be reverted, see Revert orders. ### List pending orders by subscription number - [GET /v1/orders/subscription/{subscription-key}/pending](https://developer.zuora.com/v1-api-reference/api/orders/get_pendingordersbysubscriptionnumber.md): Note: This feature is only available if you have the Order Metrics feature enabled. As of Zuora Billing Release 284, Orders is generally available and the Order Metrics feature is no longer available as a standalone feature. If you are an existing Subscribe and Amend customer and want Order Metrics only, you must turn on Orders Harmonization. You can still keep the existing Subscribe and Amend API integrations to create and manage subscriptions. Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. Retrieves the detailed information about all pending orders for a specified subscription. ## Order Actions 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. ### Update an order action - [PUT /v1/orderActions/{id}](https://developer.zuora.com/v1-api-reference/api/order-actions/put_orderactions.md): Updates the change reason and custom fields for an order action. ## Order Line Items 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 Order Line Items. ### Retrieve an order line item - [GET /v1/order-line-items/{itemId}](https://developer.zuora.com/v1-api-reference/api/order-line-items/get_orderlineitem.md): Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. If you are a new customer who onboard on Orders Harmonization and want to enable the Order Line Items feature, submit a request at Zuora Global Support. If you are an existing Orders or Orders Harmonization customer and want to enable the Order Line Items feature, submit a request at Zuora Global Support. Retrieves the detailed information about a specified order line item. The following tutorial demonstrates how to use this operation: * View details of an order line item ### Update an order line item - [PUT /v1/order-line-items/{itemId}](https://developer.zuora.com/v1-api-reference/api/order-line-items/put_orderlineitem.md): Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. If you are a new customer who onboard on Orders Harmonization and want to enable the Order Line Items feature, submit a request at Zuora Global Support. If you are an existing Orders or Orders Harmonization customer and want to enable the Order Line Items feature, submit a request at Zuora Global Support. Updates a specified order line item. The following tutorials demonstrate how to use this operation: * Update an order line item * Cancel an order line item ### Update order line items - [POST /v1/order-line-items/bulk](https://developer.zuora.com/v1-api-reference/api/order-line-items/post_orderlineitems.md): Note: The Order Line Items feature is now generally available to all Zuora customers. You need to enable the Orders feature to access the Order Line Items feature. As of Zuora Billing Release 313 (November 2021), new customers who onboard on Orders will have the Order Line Items feature enabled by default. If you are a new customer who onboard on Orders Harmonization and want to enable the Order Line Items feature, submit a request at Zuora Global Support. If you are an existing Orders or Orders Harmonization customer and want to enable the Order Line Items feature, submit a request at Zuora Global Support. Bulk-updates multiple order line items. You can also choose to generate an invoice for these updated order line items. The maximum number of order line items allowable to update in a call is 100. ## Fulfillments 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 Overview of Order Line Items. ### Create fulfillments - [POST /v1/fulfillments](https://developer.zuora.com/v1-api-reference/api/fulfillments/create_fulfillment.md): Creates one or multiple Fulfillment objects. You can also generate invoices or memos for these Fulfillment objects in this API call. The following tutorials demonstrate how to use this operation: * Create a sales order line item with fulfillments * Create a return order line item with fulfillments ### Delete a fulfillment - [DELETE /v1/fulfillments/{key}](https://developer.zuora.com/v1-api-reference/api/fulfillments/delete_fulfillment.md): Deletes a specified fulfillment. A fulfillment can only be deleted when it is in the Executing state. ### Retrieve a fulfillment - [GET /v1/fulfillments/{key}](https://developer.zuora.com/v1-api-reference/api/fulfillments/get_fulfillment.md): Retrieves the detailed information about a specified fulfillment. The following tutorial demonstrates how to use this operation: * View details of a fulfillment ### Update a fulfillment - [PUT /v1/fulfillments/{key}](https://developer.zuora.com/v1-api-reference/api/fulfillments/put_fulfillment.md): Updates a specified fulfillment. The state field of a fulfillment can only be updated when it is in a different state, to trigger the state transition. The other fields of a fulfillment can only be updated when the fulfillment is in the Executing state, or when the fulfillment is in the Booked state and the user has the "Allow Edit Of Booked Order Line Items" permission. The following tutorial demonstrates how to use this operation: * Update or cancel a fulfillment ### Create fulfillment items - [POST /v1/fulfillment-items](https://developer.zuora.com/v1-api-reference/api/fulfillments/create_fulfillmentitem.md): Creates one or multiple fulfillment items. ### Delete a fulfillment item - [DELETE /v1/fulfillment-items/{id}](https://developer.zuora.com/v1-api-reference/api/fulfillments/delete_fulfillmentitem.md): Deletes a specified fulfillment item. ### Retrieve a fulfillment item - [GET /v1/fulfillment-items/{id}](https://developer.zuora.com/v1-api-reference/api/fulfillments/get_fulfillmentitem.md): Retrieves the detailed information about a specified fulfillment item. ### Update a fulfillment item - [PUT /v1/fulfillment-items/{id}](https://developer.zuora.com/v1-api-reference/api/fulfillments/put_fulfillmentitem.md): Updates a specified fulfillment item. ## Ramps 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 Ramps and Ramp Metrics. ### Retrieve a ramp - [GET /v1/ramps/{rampNumber}](https://developer.zuora.com/v1-api-reference/api/ramps/get_rampbyrampnumber.md): Note: This operation is only available if you have the Ramps feature enabled. The Orders feature must be enabled before you can access the Ramps feature. The Ramps feature is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see Zuora Editions for pricing information coming October 2020. Retrieves the latest definition of a specified ramp. ### List all ramp metrics of a ramp - [GET /v1/ramps/{rampNumber}/ramp-metrics](https://developer.zuora.com/v1-api-reference/api/ramps/get_rampmetricsbyrampnumber.md): Note: This operation is only available if you have the Ramps feature enabled. The Orders feature must be enabled before you can access the Ramps feature. The Ramps feature is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see Zuora Editions for pricing information coming October 2020. Retrieves key metrics about a specified ramp, including the following metrics: * TCB, TCV in the Ramp level * TCB, TCV in the Interval level * TCB, TCV, Quantity, and MRR in Interval Metrics * Delta TCB, Delta TCV, Delta Quantity, and Delta MRR in Interval Delta Metrics See Key metrics for Ramps for more information. ### Retrieve a ramp by subscription key - [GET /v1/subscriptions/{subscriptionKey}/ramps](https://developer.zuora.com/v1-api-reference/api/ramps/get_rampsbysubscriptionkey.md): Note: This operation is only available if you have the Ramps feature enabled. The Orders feature must be enabled before you can access the Ramps feature. The Ramps feature is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see Zuora Editions for pricing information coming October 2020. Retrieves the definition of the ramp associated with a specified subscription. ### List ramp metrics by subscription key - [GET /v1/subscriptions/{subscriptionKey}/ramp-metrics](https://developer.zuora.com/v1-api-reference/api/ramps/get_rampmetricsbysubscriptionkey.md): Note: This operation is only available if you have the Ramps feature enabled. The Orders feature must be enabled before you can access the Ramps feature. The Ramps feature is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see Zuora Editions for pricing information coming October 2020. Retrieves key ramp metrics about a specified subscription, including the following metrics: * TCB, TCV in the Ramp level * TCB, TCV in the Interval level * TCB, TCV, Quantity, and MRR in Interval Metrics * Delta TCB, Delta TCV, Delta Quantity, and Delta MRR in Interval Delta Metrics See Key metrics for Ramps for more information. ### List ramp metrics by order number - [GET /v1/orders/{orderNumber}/ramp-metrics](https://developer.zuora.com/v1-api-reference/api/ramps/get_rampmetricsbyordernumber.md): Note: This operation is only available if you have the Ramps feature enabled. The Orders feature must be enabled before you can access the Ramps feature. The Ramps feature is available for customers with Enterprise and Nine editions by default. If you are a Growth customer, see Zuora Editions for pricing information coming October 2020. Retrieves key ramp metrics about a specified order, including the following metrics: * TCB, TCV in the Ramp level * TCB, TCV in the Interval level * TCB, TCV, Quantity, and MRR in Interval Metrics * Delta TCB, Delta TCV, Delta Quantity, and Delta MRR in Interval Delta Metrics See Key metrics for Ramps for more information. ## Subscriptions 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 Subscriptions. ### Preview a subscription - [POST /v1/subscriptions/preview](https://developer.zuora.com/v1-api-reference/api/subscriptions/post_previewsubscription.md): The REST API reference describes how to create a new subscription in preview mode. This call does not require a valid customer account. It can be used to show potential new customers a preview of a subscription with complete details and charges before creating an account, or to let existing customers preview a subscription with all charges before committing. Notes: - The response of the Preview Subscription call is based on the REST API minor version you set in the request header. The response structure might be different if you use different minor version numbers. - If you have the Invoice Settlement feature enabled, we recommend that you set the Zuora-Version parameter to 207.0 or later available versions. Otherwise, an error is returned. - Default values for customerAcceptanceDate and serviceActivationDate are set as follows. | | serviceActivationDate(SA) specified | serviceActivationDate (SA) NOT specified | | ------------- |:-------------| :-----| | customerAcceptanceDate (CA) specified | SA uses value in the request call; CA uses value in the request call| CA uses value in the request call;SA uses CE as default | | customerAcceptanceDate (CA) NOT specified | SA uses value in the request call; CA uses SA as default | SA and CA use CE as default | ### Preview a subscription by subscription key - [POST /v1/subscriptions/{subscription-key}/preview](https://developer.zuora.com/v1-api-reference/api/subscriptions/previewexistingsubscription.md): Describes how to preview an existing subscription to view information about existing and future invoices or credit memos. Note: The Zuora-Version parameter must be 207.0 or later. ### Create a subscription - [POST /v1/subscriptions](https://developer.zuora.com/v1-api-reference/api/subscriptions/post_subscription.md): This operation describes how to create a new subscription for an existing customer account. ### Notes If you have the Invoice Settlement feature enabled, it is best practice to set the Zuora-Version parameter to 211.0 or later available versions. Otherwise, an error occurs. Default values for customerAcceptanceDate and serviceActivationDate are set as follows. This API operation does not support creating a pending subscription. | | serviceActivationDate(SA) specified | serviceActivationDate (SA) NOT specified | | ------------- |:------------- | :-----| | customerAcceptanceDate (CA) specified| SA uses value in the request call; CA uses value in the request call| CA uses value in the request call;SA uses CE as default | | customerAcceptanceDate (CA) NOT specified | SA uses value in the request call; CA uses SA as default | SA and CA use CE as default | This call supports a subset of the functionality of our Create an order call. We recommend using "Create an order" instead of this call because the Orders call has the following advantages: - Provides options for managing the entire subscription lifecycle from creation through to cancellation using different order actions. - Allows the creation or modifying of multiple subscriptions in a single order. - Allows a single order to combine both recurring subscription digital goods or services with order line items for physical goods. - Orders are treated as atomic transactions. If any part fails, the entire order and subscription changes are rolled back. This call can be used to create a single subscription and there are no deprecation plans for this call. We will continue to support this call. ### List subscriptions by account key - [GET /v1/subscriptions/accounts/{account-key}](https://developer.zuora.com/v1-api-reference/api/subscriptions/get_subscriptionsbyaccount.md): Retrieves all subscriptions associated with the specified account. Zuora only returns the latest version of the subscriptions. Subscription data is returned in reverse chronological order based on updatedDate. Note that the rate plans inside the subscriptions are not sorted specifically and are returned in a random order. ### Retrieve a subscription by key - [GET /v1/subscriptions/{subscription-key}](https://developer.zuora.com/v1-api-reference/api/subscriptions/get_subscriptionsbykey.md): This REST API reference describes how to retrieve detailed information about a specified subscription in the latest version. ### Update a subscription - [PUT /v1/subscriptions/{subscription-key}](https://developer.zuora.com/v1-api-reference/api/subscriptions/put_subscription.md): Use this call to make the following kinds of changes to a subscription: - Add a note - Change the renewal term or auto-renewal flag - Change the term length or change between evergreen and termed - Add a new product rate plan - Remove an existing subscription rate plan - Change the quantity or price of an existing subscription rate plan - Change rate plans - to replace the existing rate plans in a subscription with other rate plans. Changing rate plans is currently not supported for the Billing - Revenue Integration feature. When Billing - Revenue Integration is enabled, changing rate plans will no longer be applicable in Zuora Billing. ### Notes: - The "Update a subscription" call creates a new subscription object that has a new version number and to which the subscription changes are applied. The new subscription object has the same subscription name but a new, different, subscription ID. The Status field of the new subscription object will be set to Active unless the change applied was a cancelation or suspension in which case the status reflects that. The Status field of the originating subscription object changes from Active to Expired. A status of Expired does not imply that the subscription itself has expired or ended, merely that this subscription object is no longer the most recent. - In one request, this call can make: - Up to 9 combined add, update, and remove changes - No more than 1 change to terms & conditions - Updates are performed in the following sequence: 1. First change the notes on the existing subscription, if requested. 2. Then change the terms and conditions, if requested. 3. Then perform the remaining amendments based upon the effective dates specified. If multiple amendments have the same contract-effective dates, then execute adds before updates, and updates before removes. - The update operation is atomic. If any of the updates fails, the entire operation is rolled back. - The response of the Update Subscription call is based on the REST API minor version you set in the request header. The response structure might be different if you use different minor version numbers. - If you have the Invoice Settlement feature enabled, it is best practice to set the Zuora-Version parameter to 211.0 or later available versions. Otherwise, an error occurs. ### Override a Tiered Price There are two ways you override a tiered price: - Override a specific tier number. For example: tiers[{tier:1,price:8},{tier:2,price:6}] - Override the entire tier structure. For example: tiers[{tier:1,price:8,startingUnit:1,endingUnit:100,priceFormat:"FlatFee"}, {tier:2,price:6,startingUnit:101,priceFormat:"FlatFee"}] If you just override a specific tier, do not include the startingUnit field in the request. ### Retrieve a subscription by key and version - [GET /v1/subscriptions/{subscription-key}/versions/{version}](https://developer.zuora.com/v1-api-reference/api/subscriptions/get_subscriptionsbykeyandversion.md): This REST API reference describes how to retrieve detailed information about a specified subscription in a specified version. When you create a subscription amendment, you create a new version of the subscription. You can use this method to retrieve information about a subscription in any version. ### Renew a subscription - [PUT /v1/subscriptions/{subscription-key}/renew](https://developer.zuora.com/v1-api-reference/api/subscriptions/put_renewsubscription.md): Renews a termed subscription using existing renewal terms. When you renew a subscription, the current subscription term is extended by creating a new term. If any charge in your subscription has the billing period set as SubscriptionTerm, a new charge segment is generated for the new term. Note: If you have the Invoice Settlement feature enabled, it is best practice to set the Zuora-Version parameter to 211.0 or later available versions. Otherwise, an error occurs. ### Cancel a subscription - [PUT /v1/subscriptions/{subscription-key}/cancel](https://developer.zuora.com/v1-api-reference/api/subscriptions/put_cancelsubscription.md): This REST API reference describes how to cancel an active subscription. Note: If you have the Invoice Settlement feature enabled, it is best practice to set the Zuora-Version parameter to 211.0 or later available versions. Otherwise, an error occurs. ### Resume a subscription - [PUT /v1/subscriptions/{subscription-key}/resume](https://developer.zuora.com/v1-api-reference/api/subscriptions/put_resumesubscription.md): This REST API reference describes how to resume a suspended subscription. Note: If you have the Invoice Settlement feature enabled, it is best practice to set the Zuora-Version parameter to 211.0 or later available versions. Otherwise, an error occurs. ### Suspend a subscription - [PUT /v1/subscriptions/{subscription-key}/suspend](https://developer.zuora.com/v1-api-reference/api/subscriptions/put_suspendsubscription.md): This REST API reference describes how to suspend an active subscription. Note: If you have the Invoice Settlement feature enabled, it is best practice to set the Zuora-Version parameter to 211.0 or later available versions. Otherwise, an error occurs. ### Delete a subscription by number - [PUT /v1/subscriptions/{subscription-key}/delete](https://developer.zuora.com/v1-api-reference/api/subscriptions/put_deletesubscription.md): This REST API reference describes how to delete a subscription of the specified subscription number. ### Update subscription custom fields of a subscription version - [PUT /v1/subscriptions/{subscriptionNumber}/versions/{version}/customFields](https://developer.zuora.com/v1-api-reference/api/subscriptions/put_updatesubscriptioncustomfieldsofaspecifiedversion.md): Updates the custom fields of a specified subscription version. ### List subscription metrics by subscription numbers - [GET /v1/subscriptions/subscription-metrics](https://developer.zuora.com/v1-api-reference/api/subscriptions/getmetricsbysubscriptionnumbers.md): Lists subscription metrics for the subscriptions that you specify by subscription numbers. ## Omnichannel 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 Omni-Channel Subscription. ### Create an omnichannel subscription - [POST /v1/omni-channel-subscriptions](https://developer.zuora.com/v1-api-reference/api/omnichannel-subscriptions/postomnichannelsubscription.md): Creates or updates an omnichannel subscription for a customer account. You can also create a new customer account and assign it to the new omnichannel subscription. ### Retrieve an omnichannel subscription - [GET /v1/omni-channel-subscriptions/{subscriptionKey}](https://developer.zuora.com/v1-api-reference/api/omnichannel-subscriptions/getomnichannelsubscription.md): Retrieves the information about a specific omnichannel subscription. ### Delete an omnichannel subscription - [DELETE /v1/omni-channel-subscriptions/{subscriptionKey}](https://developer.zuora.com/v1-api-reference/api/omnichannel-subscriptions/deleteomnichannelsubscription.md): Deletes a specified omnichannel subscription. ## Subscription Change History The change histories of single version subscriptions. **Note**: To access the change histories, you must turn on the following features: - Orders - Single Version Subscription ### List change histories of a subscription - [GET /v1/subscription-change-logs/{subscriptionNumber}](https://developer.zuora.com/v1-api-reference/api/subscription-change-history/getsubscriptionchangelogsbysubscriptionnumber.md): Lists subscription change histories of a single version subscription. Each history maps to an order. See the subscriptions > fields, ratePlans > fields, and ratePlanCharges > fields fields for the changes in the subscription, subscription rate plans, and subscription rate plan charges. Note: This operation is only available if you have the following features turned on: - Orders - Single Version Subscription ### List change histories of subscriptions by order number - [GET /v1/subscription-change-logs/orders/{orderNumber}](https://developer.zuora.com/v1-api-reference/api/subscription-change-history/getsubscriptionchangelogsbyordernumber.md): List the change histories of single version subscriptions that are included in and processed by an order. Each history maps to a subscription associated with this order. See the subscriptions > fields, ratePlans > fields, and ratePlanCharges > fields fields for the changes in the subscription, subscription rate plans, and subscription rate plan charges. Note: This operation is only available if you have the following features turned on: - Orders - Single Version Subscription ### Retrieve a change history of a subscription by version - [GET /v1/subscription-change-logs/{subscriptionNumber}/versions/{version}](https://developer.zuora.com/v1-api-reference/api/subscription-change-history/getsubscriptionchangelogbyversion.md): Retrieves the change history of a single version subscription by version. This version indicates the creation sequence of the orders associated with the subscription and starts from 1. See the subscription > fields, ratePlans > fields, and ratePlanCharges > fields fields for the changes in the subscription, subscription rate plans, and subscription rate plan charges. Note: This operation is only available if you have the following features turned on: - Orders - Single Version Subscription ## Rate Plans 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. ### Retrieve a rate plan - [GET /v1/rateplans/{ratePlanId}](https://developer.zuora.com/v1-api-reference/api/rate-plans/get_rateplan.md): Retrieves the detailed information about a specific subscription rate plan. - If you have the Orders feature enabled, this operation retrieves information about a subscription rate plan and the related order that has amended the rate plan. - If you have the Orders Harmonization feature enabled, this operation retrieves information about a subscription rate plan and the related order and amendment that have amended the rate plan. The returned objects may be different since amendment, order, and order action are generated asynchronously. - If all are generated, the related amendment and order, including the order action, are returned. - If not, only the related amendment may be returned before generating the order and order action. - If you are an existing Zuora Subscribe and Amend customer, this operation retrieves information about a subscription rate plan and the related amendment that has amended the rate plan. Note: Orders is now generally available as of Zuora Billing Release 284 (August 2020). If you are an existing Zuora Subscribe and Amend customer and want to adopt Orders, see What is Orders Harmonization and join the Orders Harmonization community group for more information. If you want to enable Orders, submit a request at Zuora Global Support. Note: You can only retrieve information about the following order actions: - addProduct - updateProduct - removeProduct - changePlan ## Commitments 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. ### List commitments for an account - [GET /v1/commitments](https://developer.zuora.com/v1-api-reference/api/commitments/getcommitments.md): Retrieves a paginated list of commitments for a commitment owner account. ### Retrieve a commitment - [GET /v1/commitments/{commitmentKey}](https://developer.zuora.com/v1-api-reference/api/commitments/getcommitmentbykey.md): Retrieves the details of a specific commitment using its ID or number. ### List periods for a commitment - [GET /v1/commitments/periods](https://developer.zuora.com/v1-api-reference/api/commitments/getcommitmentperiods.md): Lists periods of the specified commitment. You can paginate the results using page and pageSize query parameters. ### Retrieve the balance for a commitment - [GET /v1/commitments/{commitmentId}/balance](https://developer.zuora.com/v1-api-reference/api/commitments/getcommitmentbalance.md): Retrieves the balance amount for a specific commitment for current and past periods. Future periods are not covered. Note: This API will not work for tenants that are configured to skip commitment evaluation in Zuora Billing, and calls to this API are rejected. ### List schedules for a commitment - [GET /v1/commitments/{commitmentKey}/schedules](https://developer.zuora.com/v1-api-reference/api/commitments/listcommitmentschedules.md): Retrieves all the schedules for a specific commitment. ## Prepaid with Drawdown 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 Prepaid with Drawdown. ### Reverse fund rollover - [POST /v1/ppdd/reverse-rollover](https://developer.zuora.com/v1-api-reference/api/prepaid-with-drawdown/post_reverserollover.md): This REST API reference describes how to manually reverse fund rollover from source validity period to destination validity period. There are no path or query parameters. Note: This API will not work if the associated prepayment charge has rollover enabled. ### Trigger fund rollover - [POST /v1/ppdd/rollover](https://developer.zuora.com/v1-api-reference/api/prepaid-with-drawdown/post_rollover.md): Prepaid with Drawdown Rollover enables you to transfer the accumulative carryover of your customers’ prepaid balance funds to the following validity period when using Prepaid with Drawdown. This REST API reference describes how to manually trigger fund rollover from source validity period to destination validity period. There are no path or query parameters. Note: This API will not work if rollover is enabled in the associated prepayment charge. If you want to trigger rollover automatically, see Create prepayment charge with rollover for more information. ### Deplete funds - [POST /v1/prepaid-balance-funds/deplete](https://developer.zuora.com/v1-api-reference/api/prepaid-with-drawdown/depletefunds.md): Depleting a prepaid balance fund enables you to expire the remaining balance, which can be recognized by revenue. When an expiry request is received, the remaining fund balance is reduced to zero, and the related objects like PrepaidBalance, ValidityPeriodSummary, PrepaidBalanceTransaction, and DailyConsumption will be updated. ## Usage 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 Usage. ### Upload a usage file - [POST /v1/usage](https://developer.zuora.com/v1-api-reference/api/usage/post_usage.md): This REST API reference describes how to post or import usage data for one or more accounts in the CSV format. There are no path or query parameters. The data is uploaded using the HTTP multipart/form-data POST method and applied to the user's tenant. ### How this REST API Call Works The content of the uploaded usage file must follow the format used by the UI import tool. It must be a comma-separated (CSV) file with a corresponding .csv extension. The length of the file name must not exceed 50 characters. The file size must not exceed 4MB. See Downloading the Usage Template to learn about how to download the usage file template. At the completion of the upload, before the file contents are actually being processed, the API returns a response containing the byte count of the received file and a URL for checking the status of the import process. Of the five possible results displayed at that URL (Pending, Processing, Completed, Canceled, and Failed) only a Completed status indicates that the import was successful. The operation is atomic; if any record fails, the file is rejected. In that case, the entire import is rolled back and all stored data is returned to its original state. To view the actual import status, enter the resulting status URL from the checkImportStatus response using a tool such as POSTMAN. This additional step provides more information about why the import has failed. To manage the information after a successful upload, use the web-based UI. #### Dynamic pricing usage charges When the uploaded file contains rows that reference a product rate plan charge configured for dynamic pricing, the upload is rejected and those rows are not imported. Legacy Billing usage import does not support sending usage to dynamic pricing usage charges. To send usage to a dynamic pricing usage charge, use Mediation to ingest and rate the events. Mediation generates usage records that are later consumed by Billing, instead of relying on this bulk upload endpoint. ### Usage File Format The usage file uses the following headings: | Heading | Description | Required | |-----------------|--------|----------| | ACCOUNT_ID | Enter the account number, e.g., the default account number, such as A00000001, or your custom account number. Although this field is labeled as Account_Id, it is not the actual Account ID nor Account Name. | Yes | | UOM | Enter the unit of measure. This must match the UOM for the usage. | Yes | | QTY | Enter the quantity. | Yes | | STARTDATE | Enter the start date of the usage. This date determines the invoice item service period the associated usage is billed to. Date format is based on locale of the current user. Default date format: MM/DD/YYYY. | Yes | | ENDDATE | Enter the end date of the usage. This is not used in calculations for usage billing and is optional. Date format is based on locale of the current user. Default date format: MM/DD/YYYY. Note: The value of this column is optional, but the column header is required. | No | | PRODUCT_RATE_PLAN_CHARGE_ID | Enter a product rate plan charge number so that you can charge your customer with a dynamic usage charge for the corresponding uploaded usage record. Note: The value of this column is optional, but the column header is required. To use this field, you must set the X-Zuora-WSDL-Version request header to 146 or higher. Otherwise, an error occurs. | No | | SUBSCRIPTION_ID | Enter the subscription number or subscription name. If you created the subscription in the Zuora application, Zuora created a number automatically in a format similar to A-S00000001. If you do not provide a value for this field, the associated usage will be added to all subscriptions for the specified Account that use this Unit Of Measure. If your Accounts can have multiple subscriptions and you do not want double or triple counting of usage, you must specify the Subscription or Charge ID in each usage record. Note: The value of this column is optional, but the column header is required. | No | | CHARGE_ID | Enter the charge number (not the charge name). You can see the charge ID, e.g., C-00000001, when you add your rate plan to your subscription and view your individual charges. If your Accounts can have multiple subscriptions and you do not want double or triple counting of usage, you must specify the specific Subscription or Charge ID in each usage record. This field is related to the Charge Number on the subscription rate plan. Note: The value of this column is optional, but the column header is required. | No | | DESCRIPTION | Enter a description for the charge. | No | | UNIQUE_KEY | Enter a specific identifier for this usage record. Note: This Heading is supported by the following features: Prepaid with Drawdown, and Unbilled Usage. See Upload usage record with unique key for more information. | No | ### Retrieve usage rate detail for an invoice item - [GET /v1/invoices/invoice-item/{invoice-item-id}/usage-rate-detail](https://developer.zuora.com/v1-api-reference/api/usage/get_usage_rate_detail_by_invoice_item.md): Use this REST API operation to retrieve the usage rate detail for an invoice item to understand how the total amount is calculated. The information is the same as the Rate Detail presented on PDF invoices. Notes and limitations: - Do not support the Overage Charge Model, Tiered with Overage Charge Model, and Multi-attribute Pricing Charge Model. - Do not support invoices in Cancelled or Reversed status. - Do not support Active rating. - In terms of rating group options, only the Usage rating by billing period is supported. - Do not support On-demand usage rating. - Tax calculation is not involved. ### CRUD: Create a usage record - [POST /v1/object/usage](https://developer.zuora.com/v1-api-reference/api/usage/object_postusage.md): Creates a usage record. ### CRUD: Delete a usage record - [DELETE /v1/object/usage/{id}](https://developer.zuora.com/v1-api-reference/api/usage/object_deleteusage.md): Deletes a usage record. Usage records that are associated with a dynamic pricing usage charge cannot be deleted with this legacy Billing endpoint. When a delete request targets such a record, the operation fails and the usage record is not removed. Operations on dynamic pricing usage are supported only via Mediation-driven flows. ### CRUD: Retrieve a usage record - [GET /v1/object/usage/{id}](https://developer.zuora.com/v1-api-reference/api/usage/object_getusage.md): Retrieve a usage record. ### CRUD: Update a usage record - [PUT /v1/object/usage/{id}](https://developer.zuora.com/v1-api-reference/api/usage/object_putusage.md): Updates a usage record. Updating usage records that are associated with a dynamic pricing usage charge is not supported through this endpoint. The request fails and the record is not updated. Use Mediation-based flows to manage such usage. ## Meters 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. ### Run a specific version of a meter - [POST /meters/run/{meterId}/{version}](https://developer.zuora.com/v1-api-reference/api/meters/runspecificversionofmeter.md): Executes a specific version of a meter in Zuora Mediation. You can choose to run it with either a local file or event store source by providing optional configurations. ### Test a specific version of a meter - [POST /meters/debug/{meterId}/{version}](https://developer.zuora.com/v1-api-reference/api/meters/testspecificversionofmeter.md): Test a specific version of a meter in Zuora Mediation without executing a full run. It supports multiple input methods, including uploaded files, sample files, and manual test data. This is useful for validating meter logic and transformations before meter run. ### Retrieve summary data for a meter - [POST /meters/{meterId}/summary](https://developer.zuora.com/v1-api-reference/api/meters/retrievemetersummarydata.md): Retrieves summary data for a specific meter in Zuora Mediation, providing a rolled-up view of a meter run or time window. The API supports grouping by Operator ID, Error Code, or Session ID, and allows optional filters such as Query From Time, Query To Time, Operator IDs, and Session IDs. The API returns aggregated output and error counts per group and includes validation with detailed error responses for invalid parameters or formats. ### Retrieve the run status of a specific meter version - [GET /meters/{meterId}/{version}/runStatus](https://developer.zuora.com/v1-api-reference/api/meters/getrunstatusofspecificmeterversion.md): Retrieves the current run status of a specific meter version in Zuora Mediation. It returns an integer code indicating the status, such as RUNNING, COMPLETED, or FAILED, which helps monitor the meter's execution state. ### Retrieve the audit trail entries for a meter - [GET /meters/{meterId}/auditTrail/entries](https://developer.zuora.com/v1-api-reference/api/meters/getaudittrailentriesformeter.md): Retrieves the audit trail entries for a specific meter in Zuora Mediation. The API provides detailed, record-level information about what happened during processing, including Payload and error details, operator information, and the trace ID/event ID. ### Retrieve the list of export jobs for a meter - [GET /meters/{meterId}/auditTrail/export](https://developer.zuora.com/v1-api-reference/api/meters/getaudittrailexportjobs.md): Retrieves the list of previously initiated export jobs for a specific meter in Zuora Mediation. The API supports advanced filtering by time range, run status, run type, export type, session IDs, and operator IDs. Use the returned status and fileList fields to determine whether a job is complete and which files to download. Then use the "Retrieve the presigned URL for an export job" API operation with each fileKey in fileList to obtain the download URLs. ### Create a job to export audit trail data for a meter - [POST /meters/{meterId}/auditTrail/export](https://developer.zuora.com/v1-api-reference/api/meters/createaudittrailexportjob.md): Creates a background job to export the audit trail entries for a specific meter in Zuora Mediation. This API is for large-scale, offline access to audit data. Only one export job is processed per tenant at a time, and each export has a record limit, for example, up to 5 million rows per report. Use the returned requestId with the "Retrieve the list of export jobs for a meter" API operation to track the job status and retrieve the generated file names from fileList, then download them using the "Retrieve the presigned URL for an export job" API operation. ### Retrieve the presigned URL for an export job - [GET /meters/auditTrail/presignedUrl](https://developer.zuora.com/v1-api-reference/api/meters/getpresignedurlformeterexport.md): Returns a pre-signed URL that you can use to download a specific export file (usually from object storage such as S3). The fileKey corresponds to one entry from the fileList array in the List API. Use the returned URL in the data field directly in a browser or via a HTTP client to download the export file. ### Export details of a specific meter - [GET /meters/export/{meterId}](https://developer.zuora.com/v1-api-reference/api/meters/exportspecificmeter.md): The Export Meter operation exports the full definition of a specific meter in Zuora Mediation, including metadata, all versions, event schemas, and operator configurations (source, processor, sink). It's useful for reviewing, backing up, or replicating meter setups across environments. ### Import a meter definition - [POST /meters/import](https://developer.zuora.com/v1-api-reference/api/meters/importmeterdefinition.md): Import a meter definition into Zuora Mediation using a file exported from the Export Meter API. ### Upload a file - [POST /meters/files](https://developer.zuora.com/v1-api-reference/api/meters/uploadmeteringfile.md): Uploads and stores a file in Zuora Mediation for use in meter processing. Supported formats include CSV, Excel, and JSON. You can specify metadata like headers, delimiters, sheets, and data ranges. ### Ingest usage events for a meter - [POST /usage/bulk/{meterGlobalId}](https://developer.zuora.com/v1-api-reference/api/meters/ingestusageevents.md): Ingests usage events directly into Zuora Mediation in real time. You can send a single event or batch multiple events in a JSON array to optimize throughput. Each event must conform to the meter's event schema. This operation is supported only for meters that use the Streaming API as their source in Zuora Mediation. You can use this API to bulk-ingest events into a meter only when the meter's source is configured as a Streaming API operator. For meters that use other sources, use the appropriate ingestion mechanism for that source instead. ### Bulk delete events from an event store - [POST /meters/events/bulkDelete](https://developer.zuora.com/v1-api-reference/api/meters/bulkdeleteeventsfromeventstore.md): Allows you to delete multiple events from an event store in Zuora Mediation using a file that lists the event IDs to be removed. It is useful for cleaning up or correcting data in bulk. ### Retrieve the latest query job of a specific event store - [GET /meters/events/stores/{id}/jobs/latest](https://developer.zuora.com/v1-api-reference/api/meters/getlatestqueryjobofspecificeventstore.md): Retrieves the most recent query job executed on a specific event store in Zuora Mediation. It returns metadata such as query type (e.g., DELETE), status, record counts, and timestamps. ### Submit an event store query - [POST /meters/event-store-queries](https://developer.zuora.com/v1-api-reference/api/meters/submiteventstorequery.md): Submits a SQL-style asynchronous query to the Event Store to retrieve and inspect metering events for validation, troubleshooting, and reconciliation. The API returns a queryId that can be used to poll and fetch paginated results. ### Retrieve the results for an event store query - [GET /meters/event-store-queries/{queryId}](https://developer.zuora.com/v1-api-reference/api/meters/getqueryresultsforeventstore.md): Retrieves paginated result rows and column metadata for a previously submitted Event Store query using its queryId, including total row count, row-level field values, and readiness status. Query execution is asynchronous. ## Delivery Adjustments Delivery Adjustments are used to handle end customer delivery complaints for the Delivery Pricing charge model. For more information, see Delivery Adjustments. ### List all delivery adjustments of a subscription - [GET /v1/adjustments](https://developer.zuora.com/v1-api-reference/api/delivery-adjustments/get_subscription_adjustments.md): Describes how to retrieve detailed information about delivery adjustments of a subscription. Note: The Delivery Adjustments feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Enable billing features by yourself in the Knowledge Center. ### Create a delivery adjustment - [POST /v1/adjustments](https://developer.zuora.com/v1-api-reference/api/delivery-adjustments/create_adjustment.md): Describes how to create one or more delivery adjustments for a subscription. Notes: - The Delivery Adjustments feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Enable billing features by yourself in the Knowledge Center. - This operation supports a partial success scenario: when at least one eligible delivery adjustment exists for a given time period, “success = true” as well as eligible delivery adjustments and ineligible delivery adjustments are returned in the response; only when no delivery adjustment is eligible, “success=false” is returned. ### Preview a delivery adjustment - [POST /v1/adjustments/preview](https://developer.zuora.com/v1-api-reference/api/delivery-adjustments/preview_adjustment.md): Describes how to preview delivery adjustments of a subscription. Notes: - The Delivery Adjustments feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Enable billing features by yourself in the Knowledge Center. - This operation supports a partial success scenario: when at least one eligible delivery adjustment exists for a given time period, “success = true” as well as eligible delivery adjustments and ineligible delivery adjustments are returned in the response; only when no delivery adjustment is eligible, “success=false” is returned. ### Retrieve a delivery adjustment - [GET /v1/adjustments/{adjustment-key}](https://developer.zuora.com/v1-api-reference/api/delivery-adjustments/get_adjustment.md): Describes how to retrieve detailed information about a delivery adjustment. Note: The Delivery Adjustments feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Enable billing features by yourself in the Knowledge Center. ### Cancel a delivery adjustment - [PUT /v1/adjustments/{adjustmentId}/cancel](https://developer.zuora.com/v1-api-reference/api/delivery-adjustments/put_canceladjustment.md): Describes how to cancel an unbilled delivery adjustment. Note: The Delivery Adjustments feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Enable billing features by yourself in the Knowledge Center. ## Billing Documents Billing documents include invoices, credit memos, and debit memos. **Note**: Credit memos and debit memos are only available if you have the Invoice Settlement feature enabled. ### List billing documents for an account - [GET /v1/billing-documents](https://developer.zuora.com/v1-api-reference/api/billing-documents/get_billingdocuments.md): Retrieves the information about all billing documents associated with a specified account. The billing documents contain invoices, credit memos, and debit memos. To retrieve information about credit memos and debit memos, you must have the Invoice Settlement feature enabled. You can use query parameters to restrict the data returned in the response. Examples: - /billing-documents?accountId=4028905f5e4feb38015e50af9aa002d1&sort=+documentDate - /billing-documents?accountId=4028905f5e4feb38015e50af9aa002d1&status=Posted - /billing-documents?accountNumber=A00000001&sort=+documentDate - /billing-documents?accountNumber=A00000001&status=Posted ### Create a job to hard delete billing document files - [POST /v1/accounts/billing-documents/files/deletion-jobs](https://developer.zuora.com/v1-api-reference/api/billing-documents/post_billingdocumentfilesdeletionjob.md): Creates an asynchronous job to permanently delete all billing document PDF files for specific accounts. After the deletion job is completed, all billing document PDF files are permanently deleted. To retrieve the status of a deletion job, call Retrieve a job of hard deleting billing document files. Note: This operation can be used only if you have the Billing user permission "Hard Delete Billing Document Files" enabled. ### Retrieve a job of hard deleting billing document files - [GET /v1/accounts/billing-documents/files/deletion-jobs/{jobId}](https://developer.zuora.com/v1-api-reference/api/billing-documents/get_billingdocumentfilesdeletionjob.md): Retrieves information about an asynchronous job of permanently deleting all billing document PDF files for specific accounts. Note: This operation can be used only if you have the Billing user permission "Hard Delete Billing Document Files" enabled. ### Generate billing documents by account ID - [POST /v1/accounts/{key}/billing-documents/generate](https://developer.zuora.com/v1-api-reference/api/billing-documents/post_generatebillingdocuments.md): Generates draft or posted billing documents for a specified account. You can also generate billing documents for specified subscriptions of a specified account. The billing documents contain invoices and credit memos. To generate credit memos, you must have the Invoice Settlement feature enabled. Note: You cannot generate billing documents for cancelled or suspended subscriptions. ## Invoices Invoices provides information about customers' accounts for invoices, for examples, dates, status, and amounts. For more information about invoices, see Invoice. ### Create a standalone invoice - [POST /v1/invoices](https://developer.zuora.com/v1-api-reference/api/invoices/post_standaloneinvoice.md): Creates a standalone invoice for selling physical goods, services or other items on a non-recurring basis to your subscription customers. To use this operation, you must have the Modify Invoice and at least one of the Create Standalone Invoice With Product Catalog or Create Standalone Invoice Without Product Catalog user permissions. See Billing Roles for more information. ### Update invoices - [PUT /v1/invoices](https://developer.zuora.com/v1-api-reference/api/invoices/put_batchupdateinvoices.md): Updates multiple invoices in batches with one call. The following tutorials demonstrate how to use this operation: - Add and delete invoice items of draft standalone invoices - Edit due dates of draft standalone invoices - Edit invoice item prices and custom fields of draft standalone invoices ### Limitations - You can update a maximum of 50 invoices by one call. ### Create standalone invoices - [POST /v1/invoices/batch](https://developer.zuora.com/v1-api-reference/api/invoices/post_standaloneinvoices.md): Creates multiple standalone invoices for selling physical goods, services or other items on a non-recurring basis to your subscription customers. To use this operation, you must have the Modify Invoice and at least one of the Create Standalone Invoice With Product Catalog or Create Standalone Invoice Without Product Catalog user permissions. See Billing Roles for more information. ### Limitations This operation has the following limitations: * You can create a maximum of 50 invoices in one request. * You can create a maximum of 1,000 invoice items in one request. ### Post invoices - [POST /v1/invoices/bulk-post](https://developer.zuora.com/v1-api-reference/api/invoices/post_postinvoices.md): Posts multiple invoices. You can post a maximum of 50 invoices in one single request. Additionally, you can also update invoice dates while posting the invoices. Note : This operation is synchronous and invoices within the bulk request are posted one by one. The maximum batch size depends on the posting performance, which varies with invoice complexity and integrations with external tax engines. ### Retrieve the PDF file generation status of invoices - [GET /v1/invoices/pdf-status](https://developer.zuora.com/v1-api-reference/api/invoices/getinvoicepdfstatus.md): Retrieves the PDF generation statuses of a batch of invoices. ### Delete an invoice - [DELETE /v1/invoices/{invoiceKey}](https://developer.zuora.com/v1-api-reference/api/invoices/delete_deleteinvoice.md): Deletes a specific invoice. Whether to delete an invoice synchronously or asynchronously depends on the number of invoice items contained in the invoice. By default, if an invoice contains less than 100 items, the invoice is deleted synchronously. Otherwise, the invoice is deleted asynchronously. If you want to change the threshold, submit a request at Zuora Global Support. ### Retrieve an invoice - [GET /v1/invoices/{invoiceKey}](https://developer.zuora.com/v1-api-reference/api/invoices/get_getinvoice.md): Retrieves a specific invoice. ### Update an invoice - [PUT /v1/invoices/{invoiceKey}](https://developer.zuora.com/v1-api-reference/api/invoices/put_updateinvoice.md): Updates a specific invoice. The following tutorials demonstrate how to use this operation: - Add and delete invoice items of draft standalone invoices - Edit due dates of draft standalone invoices - Edit invoice item prices and custom fields of draft standalone invoices ### List all application parts of an invoice - [GET /v1/invoices/{invoiceKey}/application-parts](https://developer.zuora.com/v1-api-reference/api/invoices/get_invoiceapplicationparts.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. If you are in Zuora version 341, this operation will return only processed payments applied to the invoices. If you are in the Zuora version less than 341, this operation behavior remains the same and returns all payments associated with the invoice regardless of the payment status. Retrieves information about the payments or credit memos that are applied to a specified invoice. ### Email an invoice - [POST /v1/invoices/{invoiceKey}/emails](https://developer.zuora.com/v1-api-reference/api/invoices/post_emailinvoice.md): Sends a posted invoice to the specified email addresses manually. ### Notes - You must activate the Manual Email For Invoice | Manual Email For Invoice notification before emailing invoices. To include the invoice PDF in the email, select the Include Invoice PDF check box in the Edit notification dialog from the Zuora UI. See Create and Edit Notifications for more information. - Zuora sends the email messages based on the email template you set. You can set the email template to use in the Delivery Options panel of the Edit notification dialog from the Zuora UI. By default, the Invoice Posted Default Email Template template is used. See Create and Edit Email Templates for more information. - The invoices are sent only to the work email addresses or personal email addresses of the Bill To contact if the following conditions are all met: * The useEmailTemplateSetting field is set to false. * The email addresses are not specified in the emailAddresses field. ### List all files of an invoice - [GET /v1/invoices/{invoiceKey}/files](https://developer.zuora.com/v1-api-reference/api/invoices/get_invoicefiles.md): Retrieves the information about all PDF files of a specified invoice. Invoice PDF files are returned in reverse chronological order by the value of the versionNumber field. Note: This API only retrieves the PDF files that have been generated. If the latest PDF file is being generated, it will not be included in the response. You can use the Query action to get the latest PDF file, for example: "select Body from Invoice where Id = '2c93808457d787030157e0324aea5158'". See Query an Invoice Body for more information. ### Upload a file for an invoice - [POST /v1/invoices/{invoiceKey}/files](https://developer.zuora.com/v1-api-reference/api/invoices/post_uploadfileforinvoice.md): Uploads an externally generated invoice PDF file for an invoice that is in Draft or Posted status. To use this operation, you must enable the Modify Invoice permission. See Billing Permissions for more information. This operation has the following restrictions: - Only the PDF file format is supported. - The maximum size of the PDF file to upload is 4 MB. - A maximum of 50 PDF files can be uploaded for one invoice. - Ensure that each uploaded PDF file has a unique name. Duplicate filenames are not allowed when attaching files to an invoice. ### List all items of an invoice - [GET /v1/invoices/{invoiceKey}/items](https://developer.zuora.com/v1-api-reference/api/invoices/get_invoiceitems.md): Retrieves the information about all items of a specified invoice. ### List all taxation items of an invoice item - [GET /v1/invoices/{invoiceKey}/items/{itemId}/taxation-items](https://developer.zuora.com/v1-api-reference/api/invoices/get_taxationitemsofinvoiceitem.md): Retrieves information about the taxation items of a specific invoice item. ### Reverse an invoice - [PUT /v1/invoices/{invoiceKey}/reverse](https://developer.zuora.com/v1-api-reference/api/invoices/put_reverseinvoice.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Reverses a posted invoice. The reversal operation is performed asynchronously when the invoice contains more than 2,000 items in total. Restrictions You are not allowed to reverse an invoice if any of the following restrictions is met: * Payments and credit memos are applied to the invoice. * The invoice is split. * The invoice is not in Posted status. * The total amount of the invoice is less than 0 (a negative invoice). * Using Tax Connector for Extension Platform to calculate taxes. * An invoice contains more than 50,000 items in total, including invoice items, discount items, and taxation items. See Invoice Reversal for more information. ### Create taxation items for an invoice - [POST /v1/invoices/{invoiceKey}/taxation-items](https://developer.zuora.com/v1-api-reference/api/invoices/post_inv_taxationitems.md): Creates taxation items for an invoice. ### Write off an invoice - [PUT /v1/invoices/{invoiceKey}/write-off](https://developer.zuora.com/v1-api-reference/api/invoices/put_writeoffinvoice.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Writes off a posted invoice. By writing off an invoice, a credit memo is created and applied to the invoice. The generated credit memo items and credit memo taxation items are applied to invoice items and invoice taxation items based on the configured default application rule. If an invoice is written off, the balance of each invoice item and invoice taxation item must be zero. If you set the Create credit memos mirroring invoice items billing rule to Yes, you can write off an invoice even if all its items have zero balance. Restrictions: You cannot write off an invoice if any of the following restrictions is met: * The balance of an invoice has been changed before Invoice Settlement is enabled. For example, before Invoice Settlement is enabled, any credit balance adjustments, invoice item adjustments, or invoice adjustments have been applied to an invoice. * An invoice contains more than 2,000 items in total, including invoice items, discount items, and taxation items. See Invoice Write-off for more information. ## Credit Memos 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 Credit and debit memos. ### List credit memos - [GET /v1/credit-memos](https://developer.zuora.com/v1-api-reference/api/credit-memos/get_creditmemos.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about all credit memos. For a use case of this operation, see Get credit memo. ### Filtering You can use query parameters to restrict the data returned in the response. Each query parameter corresponds to one field in the response body. If the value of a filterable field is string, you can set the corresponding query parameter to null when filtering. Then, you can get the response data with this field value being null. Examples: - /v1/credit-memos?status=Posted - /v1/credit-memos?referredInvoiceId=null&status=Draft - /v1/credit-memos?status=Posted&type=External&sort=+number ### Create a credit memo from a charge - [POST /v1/credit-memos](https://developer.zuora.com/v1-api-reference/api/credit-memos/post_creditmemofromprpc.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Creates an ad-hoc credit memo from a product rate plan charge. Zuora supports the creation of credit memos from any type of product rate plan charge. The charges can also have any amount and any charge model, except for discout charge models. When credit memos are created from product rate plan charges, the specified amount with decimal places is now validated based on the decimal places supported by each currency. You can create a credit memo only if you have the user permission. See Billing Roles for more information. ### Create credit memos - [POST /v1/credit-memos/bulk](https://developer.zuora.com/v1-api-reference/api/credit-memos/post_createcreditmemos.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Creates multiple credit memos from invoices or product rate plan charges. You can create a maximum of 50 credit memos in one single request. - If you set the sourceType request field to Invoice, you can create multiple credit memos from invoices. - If you set the sourceType request field to Standalone, you can create multiple credit memos from product rate plan charges. The credit memos that are created are each in separate database transactions. If the creation of one credit memo fails, other credit memos can still be created successfully. You can create credit memos only if you have the user permission. See Billing Roles for more information. Zero-amount memo items are supported in the following scenarios: - If you want to correct taxation items only for an invoice, you can set the memo item amount to zero, but the taxation item amount to non-zero. - If you want to correct personal data in an invoice, you can set the memo item amount to zero to create a zero-amount credit memo from an invoice. ### Update credit memos - [PUT /v1/credit-memos/bulk](https://developer.zuora.com/v1-api-reference/api/credit-memos/put_updatecreditmemos.md): Notes: - This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. - You can update credit memos only if you have the user permission. See Billing Roles for more information. Updates the basic and finance information about multiple credit memos. You can update a maximum of 50 credit memos in one single request. Currently, Zuora supports updating tax-exclusive memo items, but does not support updating tax-inclusive memo items. If the amount of a memo item is updated, the tax will be recalculated in the following conditions: - The memo is created from a product rate plan charge and you use Avalara to calculate the tax. - The memo is created from an invoice and you use Avalara or Zuora Tax to calculate the tax. The Edit credit and debit memos tutorial demonstrates how to use this operation to add and delete memo items. The credit memos that are updated are each in separate database transactions. If the update of one credit memo fails, other credit memos can still be updated successfully. ### Retrieve the PDF file generation status of credit memos - [GET /v1/credit-memos/pdf-status](https://developer.zuora.com/v1-api-reference/api/credit-memos/get_creditmemopdfstatus.md): Retrieves the PDF generation statuses of a batch of credit memos. ### List all taxation items of a credit memo item - [GET /v1/credit-memos/{creditMemoId}/items/{cmitemid}/taxation-items](https://developer.zuora.com/v1-api-reference/api/credit-memos/get_taxationitemsofcreditmemoitem.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves information about the taxation items of a specific credit memo item. ### Write off a credit memo - [PUT /v1/credit-memos/{creditMemoId}/write-off](https://developer.zuora.com/v1-api-reference/api/credit-memos/put_writeoffcreditmemo.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Write off a fully unapplied credit memo. When writing off a credit memo, a debit memo is automatically created, and then the credit memo to be written off is fully applied to the debit memo. Note that this operation only supports writing off credit memos that are fully unapplied. Credit memos that are not fully unapplied cannot be written off by this operation. ### Delete a credit memo - [DELETE /v1/credit-memos/{creditMemoKey}](https://developer.zuora.com/v1-api-reference/api/credit-memos/delete_creditmemo.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Deletes a credit memo. Only credit memos with the Cancelled status can be deleted. You can delete a credit memo only if you have the user permission. See Billing Roles for more information. ### Retrieve a credit memo - [GET /v1/credit-memos/{creditMemoKey}](https://developer.zuora.com/v1-api-reference/api/credit-memos/get_creditmemo.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about a specific credit memo. For a use case of this operation, see Get credit memo. ### Update a credit memo - [PUT /v1/credit-memos/{creditMemoKey}](https://developer.zuora.com/v1-api-reference/api/credit-memos/put_updatecreditmemo.md): Notes: - This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. - You can update a credit memo only if you have the user permission. See Billing Roles for more information. Updates the basic and finance information about a credit memo. Currently, Zuora supports updating tax-exclusive memo items, but does not support updating tax-inclusive memo items. If the amount of a memo item is updated, the tax will be recalculated in the following conditions: - The memo is created from a product rate plan charge and you use Avalara to calculate the tax. - The memo is created from an invoice and you use Avalara or Zuora Tax to calculate the tax. The Edit credit and debit memos tutorial demonstrates how to use this operation to add and delete memo items. ### Apply a credit memo - [PUT /v1/credit-memos/{creditMemoKey}/apply](https://developer.zuora.com/v1-api-reference/api/credit-memos/put_applycreditmemo.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Applies a posted credit memo to one or more invoices and debit memos. You can apply a credit memo to an invoice or a debit memo only if you have the user permission. See Billing Roles for more information. When you apply a credit memo, the total number of credit memo items and the items that credit memo items to be applied to must be less than or equal to 15,000. If the limit is hit, you can follow the following instructions: - If you want to apply one credit memo to multiple invoices or debit memos, decrease the number of invoices or debit memos in the request. - If you want to apply one credit memo to a single invoice or debit memo with a large volume of items, you have to specify invoice items or debit memo items in the request. The maximum number of invoice items or debit memo items that you can specify in the request is 1,000. - If a credit memo has a large volume of items, you have to specify credit memo items in the request. The maximum number of credit memo items that you can specify in the request is 1,000. If the Proration application rule is used, when applying credit memos, the following quantity must be less than or equal to 10,000: (number of invoice items + number of debit memo items) * number of credit memo items Otherwise, the First In First Out rule will be used instead of the Proration rule. ### Cancel a credit memo - [PUT /v1/credit-memos/{creditMemoKey}/cancel](https://developer.zuora.com/v1-api-reference/api/credit-memos/put_cancelcreditmemo.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Cancels a credit memo. Only credit memos with the Draft status can be cancelled. You can cancel a credit memo only if you have the user permission. See Billing Roles for more information. ### Email a credit memo - [POST /v1/credit-memos/{creditMemoKey}/emails](https://developer.zuora.com/v1-api-reference/api/credit-memos/post_emailcreditmemo.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Sends a posted credit memo to the specified email addresses manually. ### Notes - You must activate the Email Credit Memo | Manually email Credit Memo notification before emailing credit memos. To include the credit memo PDF in the email, select the Include Credit Memo PDF check box in the Edit notification dialog from the Zuora UI. See Create and Edit Notifications for more information. - Zuora sends the email messages based on the email template you set. You can set the email template to use in the Delivery Options panel of the Edit notification dialog from the Zuora UI. By default, the Manual Email for Credit Memo Default Template template is used. See Create and Edit Email Templates for more information. - The credit memos are sent only to the work email addresses or personal email addresses of the Bill To contact if the following conditions are all met: * The useEmailTemplateSetting field is set to false. * The email addresses are not specified in the emailAddresses field. ### Upload a file for a credit memo - [POST /v1/credit-memos/{creditMemoKey}/files](https://developer.zuora.com/v1-api-reference/api/credit-memos/post_uploadfileforcreditmemo.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Uploads an externally generated PDF file for a credit memo that is in Draft or Posted status. To use this operation, you must enable the Modify Modify Credit Memo permission. See Billing Permissions for more information. This operation has the following restrictions: - Only the PDF file format is supported. - The maximum size of the PDF file to upload is 4 MB. - A maximum of 50 PDF files can be uploaded for one credit memo. ### List all files of a credit memo - [GET /v1/credit-memos/{creditMemoKey}/files](https://developer.zuora.com/v1-api-reference/api/credit-memos/get_creditmemofiles.md): Retrieves the information about all PDF files of a specified credit memo. Credit Memo PDF files are returned in reverse chronological order by the value of the versionNumber field. Note: This API only retrieves the PDF files that have been generated. If the latest PDF file is being generated, it will not be included in the response. ### List credit memo items - [GET /v1/credit-memos/{creditMemoKey}/items](https://developer.zuora.com/v1-api-reference/api/credit-memos/get_creditmemoitems.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about all items of a credit memo. A credit memo item is a single line item in a credit memo. ### Filtering You can use query parameters to restrict the data returned in the response. Each query parameter corresponds to one field in the response body. If the value of a filterable field is string, you can set the corresponding query parameter to null when filtering. Then, you can get the response data with this field value being null. Examples: - /v1/credit-memos/402890245c7ca371015c7cb40ac30015/items?amount=100 - /v1/credit-memos/402890245c7ca371015c7cb40ac30015/items?amount=100&sort=createdDate ### Retrieve a credit memo item - [GET /v1/credit-memos/{creditMemoKey}/items/{cmitemid}](https://developer.zuora.com/v1-api-reference/api/credit-memos/get_creditmemoitem.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about a specific item of a credit memo. A credit memo item is a single line item in a credit memo. ### List all parts of a credit memo - [GET /v1/credit-memos/{creditMemoKey}/parts](https://developer.zuora.com/v1-api-reference/api/credit-memos/get_creditmemoparts.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about all parts of a credit memo. A credit memo can consist of an unapplied part, and several parts applied to invoices and debit memos. You can use this operation to get all the applied and unapplied portions of a credit memo. Note that a fully refunded credit memo does not contain any credit memo part. ### Retrieve a credit memo part - [GET /v1/credit-memos/{creditMemoKey}/parts/{partid}](https://developer.zuora.com/v1-api-reference/api/credit-memos/get_creditmemopart.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about a specific credit memo part. A credit memo can consist of an unapplied part, and several parts applied to invoices and debit memos. A fully refunded credit memo does not contain any credit memo part. ### Generate a credit memo PDF file - [POST /v1/credit-memos/{creditMemoKey}/pdfs](https://developer.zuora.com/v1-api-reference/api/credit-memos/post_creditmemopdf.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Creates a PDF file for a specified credit memo. To access the generated PDF file, you can download it by clicking View PDF on the detailed credit memo page through the Zuora UI. This REST API operation can be used only if you have the billing document file generation feature and the Billing user permission "Regenerate PDF" enabled. ### Post a credit memo - [PUT /v1/credit-memos/{creditMemoKey}/post](https://developer.zuora.com/v1-api-reference/api/credit-memos/put_postcreditmemo.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Posts a credit memo to activate it. You can post credit memos only if you have the Billing permissions. ### Refund a credit memo - [POST /v1/credit-memos/{creditMemoKey}/refund](https://developer.zuora.com/v1-api-reference/api/credit-memos/post_refundcreditmemo.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Refunds a full or partial posted credit memo to your customers. Only the amount of unapplied part could be refunded. You can refund a credit memo only if you have the user permission. See Billing Roles for more information. When you refund a credit memo, the total number of credit memo items to be refunded must be less than or equal to 15,000. For a use case of this operation, see Refund processing. ### Reverse a credit memo - [PUT /v1/credit-memos/{creditMemoKey}/reverse](https://developer.zuora.com/v1-api-reference/api/credit-memos/put_reversecreditmemo.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Reverses a posted credit memo. See Reverse credit memos for more information. You can reverse a credit memo only if you have the user permission. See Billing Roles for more information. Restrictions You cannot reverse credit memos if any of the following conditions is met: * A credit memo's applied amount is not 0. * A credit memo is not in Posted status. * A credit memo contains more than 2,000 items in total, including credit memo items, discount items, and taxation items. ### Create taxation items for a credit memo - [POST /v1/credit-memos/{creditMemoKey}/taxation-items](https://developer.zuora.com/v1-api-reference/api/credit-memos/post_cm_taxationitems.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Creates taxation items for a credit memo. ### Unapply a credit memo - [PUT /v1/credit-memos/{creditMemoKey}/unapply](https://developer.zuora.com/v1-api-reference/api/credit-memos/put_unapplycreditmemo.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Unapplies an applied credit memo from one or more invoices and debit memos. The full applied amount from invoices and debit memos is transferred into the unapplied amount of the credit memo. You can unapply a credit memo from an invoice or a debit memo only if you have the user permission. See Billing Roles for more information. When you unapply a credit memo, the total number of credit memo items and the items that credit memo items to be unapplied from must be less than or equal to 15,000. If the limit is hit, you can follow the following instructions: - If you want to unapply one credit memo without specifying invoices or debit memos and the limit is hit, you have to specify the invoice items or debit memo items in the request to decrease the number of items. - If you want to unapply one credit memo from multiple specified invoices or debit memos, decrease the number of invoices or debit memos in the request. - If you want to unapply one credit memo from a single invoice or debit memo with a large volume of items, you have to specify invoice items or debit memo items in the request. The maximum number of invoice items or debit memo items that you can specify in the request is 1,000. - If a credit memo has a large volume of items, you have to specify credit memo items in the request. The maximum number of credit memo items that you can specify in the request is 1,000. - When unapplying a credit memo, the total number of the credit memo's item parts must be less than or equal to 1,000. Otherwise, the operation would fail and an error message would pop up. When you see this error, you can try using the Unapply a credit memo API as an alternative. Similarly, make sure that all the requirements listed in the API reference are met. ### Unpost a credit memo - [PUT /v1/credit-memos/{creditMemoKey}/unpost](https://developer.zuora.com/v1-api-reference/api/credit-memos/put_unpostcreditmemo.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Unposts a credit memo that is in Posted status. If a credit memo has been applied or refunded, you are not allowed to unpost it. After a credit memo is unposted, its status becomes Draft. You can unpost credit memos only if you have the Billing permissions. You can prevent an unpost operation by configuring the 'Do not allow unposting invoices and memos if their revenue is already recognized in a closed accounting period' accounting rule. The default value of this rule is set to 'disabled.' For more information, see Configure Accounting Rules. ### Create a credit memo from an invoice - [POST /v1/credit-memos/invoice/{invoiceKey}](https://developer.zuora.com/v1-api-reference/api/credit-memos/post_creditmemofrominvoice.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Creates an ad-hoc credit memo from an invoice. You can create a credit memo from an invoice only if you have the user permission. See Billing Roles for more information. For a use case of this operation, see Create credit memo. Zero-amount memo items are supported in the following scenarios: - If you want to correct taxation items only for an invoice, you can set the memo item amount to zero, but the taxation item amount to non-zero. - If you want to correct personal data in an invoice, you can set the memo item amount to zero to create a zero-amount credit memo from an invoice. ### Retrieve an async unapply credit memo job by ID - [GET /v1/credit-memos/unapply-async-jobs/{unapplyAsyncJobId}](https://developer.zuora.com/v1-api-reference/api/credit-memos/getunapplycreditmemoasyncjob.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves information about a specific Async Credit Memo Unapply job. ### Retrieve an async unapply credit memo job by ID - [GET /v1/credit-memos/apply-async-jobs/{applyAsyncJobId}](https://developer.zuora.com/v1-api-reference/api/credit-memos/getapplycreditmemoasyncjob.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves information about a specific Async Credit Memo Apply job. ### Apply a credit memo aysnchronously - [PUT /v1/credit-memos/{creditMemoKey}/apply-async](https://developer.zuora.com/v1-api-reference/api/credit-memos/applycreditmemoasync.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Asynchronously applies a posted credit memo to one or more invoices You can apply a credit memo to an invoice only if you have the user permission. See Billing Roles for more information. When you apply a credit memo, the total number of credit memo items and the items that credit memo items to be applied to must be less than or equal to 300,000. The maximum number of invoices that you can specify in the request is 1,000 If the Proration application rule is used, when applying credit memos, the following quantity must be less than or equal to 10,000: (number of invoice items) * number of credit memo items Otherwise, the First In First Out rule will be used instead of the Proration rule. ### Unapply a credit memo asynchronously - [PUT /v1/credit-memos/{creditMemoKey}/unapply-async](https://developer.zuora.com/v1-api-reference/api/credit-memos/unapplycreditmemoasync.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Asynchronously Unapplies an applied credit memo from one or more invoices. The full applied amount from invoices is transferred into the unapplied amount of the credit memo. You can unapply a credit memo from an invoice only if you have the user permission. See Billing Roles When you unapply a credit memo, the total number of credit memo items and the items that credit memo items to be unapplied from must be less than or equal to 300,000. The maximum number of invoices that you can specify in the request is 1,000 ## Debit Memos 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 Credit and debit memos. ### List debit memos - [GET /v1/debit-memos](https://developer.zuora.com/v1-api-reference/api/debit-memos/get_debitmemos.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about all debit memos associated with all customer accounts. ### Filtering You can use query parameters to restrict the data returned in the response. Each query parameter corresponds to one field in the response body. If the value of a filterable field is string, you can set the corresponding query parameter to null when filtering. Then, you can get the response data with this field value being null. Examples: - /v1/debit-memos?status=Posted - /v1/debit-memos?referredInvoiceId=null&status=Draft - /v1/debit-memos?status=Posted&type=External&sort=+number ### Create a debit memo from a charge - [POST /v1/debit-memos](https://developer.zuora.com/v1-api-reference/api/debit-memos/post_debitmemofromprpc.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Creates an ad-hoc debit memo from a product rate plan charge. Zuora supports the creation of debit memos from any type of product rate plan charge. The charges can also have any amount and any charge model, except for discout charge models. When debit memos are created from product rate plan charges, the specified amount with decimal places is now validated based on the decimal places supported by each currency. You can create a debit memo only if you have the user permission. See Billing Roles for more information. ### Update due dates for debit memos - [PUT /v1/debit-memos](https://developer.zuora.com/v1-api-reference/api/debit-memos/put_updatedebitmemosduedates.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Updates the due date for multiple debit memos in one single request. This API operation will be deprecated. You can use the Update debit memos instead, which provides more flexible functionality. ### Create debit memos - [POST /v1/debit-memos/bulk](https://developer.zuora.com/v1-api-reference/api/debit-memos/post_createdebitmemos.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Creates multiple debit memos from invoices or product rate plan charges. You can create a maximum of 50 debit memos in one single request. - If you set the sourceType request field to Invoice, you can create multiple debit memos from invoices. - If you set the sourceType request field to Standalone, you can create multiple debit memos from product rate plan charges. The debit memos that are created are each in separate database transactions. If the creation of one debit memo fails, other debit memos can still be created successfully. You can create debit memos only if you have the user permission. See Billing Roles for more information. ### Update debit memos - [PUT /v1/debit-memos/bulk](https://developer.zuora.com/v1-api-reference/api/debit-memos/put_updatedebitmemos.md): Notes: - This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. - You can update debit memos only if you have the user permission. See Billing Roles for more information. Updates the basic and finance information about multiple debit memos. You can update a maximum of 50 credit memos in one single request. Currently, Zuora supports updating tax-exclusive memo items, but does not support updating tax-inclusive memo items. If the amount of a memo item is updated, the tax will be recalculated in the following conditions: - The memo is created from a product rate plan charge and you use Avalara to calculate the tax. - The memo is created from an invoice and you use Avalara or Zuora Tax to calculate the tax. The Edit credit and debit memos tutorial demonstrates how to use this operation to add and delete memo items. The credit memos that are updated are each in separate database transactions. If the update of one debit memo fails, other debit memos can still be updated successfully. ### Retrieve the PDF file generation status of debit memos - [GET /v1/debit-memos/pdf-status](https://developer.zuora.com/v1-api-reference/api/debit-memos/get_debitmemopdfstatus.md): Retrieves the PDF generation statuses of a batch of debit memos. ### List all application parts of a debit memo - [GET /v1/debit-memos/{debitMemoId}/application-parts](https://developer.zuora.com/v1-api-reference/api/debit-memos/get_debitmemoapplicationparts.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves information about the payments or credit memos that are applied to a specified debit memo. If you use the Zuora version 341.0 or a later available version, this operation will return only processed payments applied to the debit memos. For Zuora versions earlier than 341.0, it returns all payments associated with the debit memo regardless of the payment status. ### List all taxation items of a debit memo item - [GET /v1/debit-memos/{debitMemoId}/items/{dmitemid}/taxation-items](https://developer.zuora.com/v1-api-reference/api/debit-memos/get_taxationitemsofdebitmemoitem.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves information about the taxation items of a specific debit memo item. ### Delete a debit memo - [DELETE /v1/debit-memos/{debitMemoKey}](https://developer.zuora.com/v1-api-reference/api/debit-memos/delete_debitmemo.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Deletes a debit memo. Only debit memos with the Cancelled status can be deleted. You can delete a debit memo only if you have the user permission. See Billing Roles for more information. The Edit credit and debit memos tutorial demonstrates how to use this operation to add and delete memo items. ### Retrieve a debit memo - [GET /v1/debit-memos/{debitMemoKey}](https://developer.zuora.com/v1-api-reference/api/debit-memos/get_debitmemo.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about a specific debit memo. ### Update a debit memo - [PUT /v1/debit-memos/{debitMemoKey}](https://developer.zuora.com/v1-api-reference/api/debit-memos/put_debitmemo.md): Notes: - This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. - You can update a debit memo only if you have the user permission. See Billing Roles for more information. Updates the basic and finance information about a debit memo. Currently, Zuora supports updating tax-exclusive memo items, but does not support updating tax-inclusive memo items. If the amount of a memo item is updated, the tax will be recalculated in the following conditions: - The memo is created from a product rate plan charge and you use Avalara to calculate the tax. - The memo is created from an invoice and you use Avalara or Zuora Tax to calculate the tax. The Edit credit and debit memos tutorial demonstrates how to use this operation to add and delete memo items. ### Cancel a debit memo - [PUT /v1/debit-memos/{debitMemoKey}/cancel](https://developer.zuora.com/v1-api-reference/api/debit-memos/put_canceldebitmemo.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Cancels a debit memo. Only debit memos with the Draft status can be cancelled. You can cancel a debit memo only if you have the user permission. See Billing Roles for more information. ### Collect a posted debit memo - [POST /v1/debit-memos/{debitMemoKey}/collect](https://developer.zuora.com/v1-api-reference/api/debit-memos/post_debitmemocollect.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. This API operation provides an easy way to let the client-side to collect an existing posted debit memo. It supports the following steps: 1. Apply unapplied credit memos to the posted debit memo by Oldest-First-Largest-First rule if there are more than one unapplied credit memos. 2. Apply unapplied payments to the posted debit memo by Oldest-First-Largest-First rule if there are more than one unapplied payments. 3. Process payment to the posted debit memo if there is an open-balance on it. Restrictions Since this API will do lots of works, and some of them are resource consuming, we need to restrict the usage of this API by the following conditions: 1. If the target debit memo gets more than 10 debit memo items, the request will be rejected. 2. If CreditMemo is specified in applicationOrder, when there are more than 25 credit memos will be used to apply to the debit memo, the request will be rejected. 3. If CreditMemo is specified in applicationOrder, when there are more than 100 credit memo items will be used to apply to the debit memo, the request will be rejected. 4. If UnappliedPayment is specified in applicationOrder, when there are more than 25 payments will be used to apply to the debit memo, the request will be rejected. ### Email a debit memo - [POST /v1/debit-memos/{debitMemoKey}/emails](https://developer.zuora.com/v1-api-reference/api/debit-memos/post_emaildebitmemo.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Sends a posted debit memo to the specified email addresses manually. ### Notes - You must activate the Email Debit Memo | Manually email Debit Memo notification before emailing debit memos. To include the debit memo PDF in the email, select the Include Debit Memo PDF check box in the Edit notification dialog from the Zuora UI. See Create and Edit Notifications for more information. - Zuora sends the email messages based on the email template you set. You can set the email template to use in the Delivery Options panel of the Edit notification dialog from the Zuora UI. By default, the Manual Email for Debit Memo Default Template template is used. See Create and Edit Email Templates for more information. - The debit memos are sent only to the work email addresses or personal email addresses of the Bill To contact if the following conditions are all met: * The useEmailTemplateSetting field is set to false. * The email addresses are not specified in the emailAddresses field. ### Upload a file for a debit memo - [POST /v1/debit-memos/{debitMemoKey}/files](https://developer.zuora.com/v1-api-reference/api/debit-memos/post_uploadfilefordebitmemo.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Uploads an externally generated PDF file for a debit memo that is in Draft or Posted status. To use this operation, you must enable the Modify Debit Memo permission. See Billing Permissions for more information. This operation has the following restrictions: - Only the PDF file format is supported. - The maximum size of the PDF file to upload is 4 MB. - A maximum of 50 PDF files can be uploaded for one debit memo. ### List all files of a debit memo - [GET /v1/debit-memos/{debitMemoKey}/files](https://developer.zuora.com/v1-api-reference/api/debit-memos/get_debitmemofiles.md): Retrieves the information about all PDF files of a specified debit memo. Debit Memo PDF files are returned in reverse chronological order by the value of the versionNumber field. Note: This API only retrieves the PDF files that have been generated. If the latest PDF file is being generated, it will not be included in the response. ### List debit memo items - [GET /v1/debit-memos/{debitMemoKey}/items](https://developer.zuora.com/v1-api-reference/api/debit-memos/get_debitmemoitems.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about all items of a debit memo. A debit memo item is a single line item in a debit memo. ### Filtering You can use query parameters to restrict the data returned in the response. Each query parameter corresponds to one field in the response body. If the value of a filterable field is string, you can set the corresponding query parameter to null when filtering. Then, you can get the response data with this field value being null. Examples: - /v1/debit-memos/402890245c7ca371015c7cb40b28001f/items?amount=100 - /v1/debit-memos/402890245c7ca371015c7cb40b28001f/items?amount=100&sort=createdDate ### Retrieve a debit memo item - [GET /v1/debit-memos/{debitMemoKey}/items/{dmitemid}](https://developer.zuora.com/v1-api-reference/api/debit-memos/get_debitmemoitem.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves information about a specific item of a debit memo. A debit memo item is a single line item in a debit memo. ### Generate a debit memo PDF file - [POST /v1/debit-memos/{debitMemoKey}/pdfs](https://developer.zuora.com/v1-api-reference/api/debit-memos/post_debitmemopdf.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Creates a PDF file for a specified debit memo. To access the generated PDF file, you can download it by clicking View PDF on the detailed debit memo page through the Zuora UI. This REST API operation can be used only if you have the billing document file generation feature and the Billing user permission "Regenerate PDF" enabled. ### Post a debit memo - [PUT /v1/debit-memos/{debitMemoKey}/post](https://developer.zuora.com/v1-api-reference/api/debit-memos/put_postdebitmemo.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Posts a debit memo to activate it. You can post debit memos only if you have the Billing permissions. ### Create taxation items for a debit memo - [POST /v1/debit-memos/{debitMemoKey}/taxation-items](https://developer.zuora.com/v1-api-reference/api/debit-memos/post_dm_taxationitems.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Creates taxation items for a debit memo. ### Unpost a debit memo - [PUT /v1/debit-memos/{debitMemoKey}/unpost](https://developer.zuora.com/v1-api-reference/api/debit-memos/put_unpostdebitmemo.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Unposts a debit memo that is in Posted status. If any credit memo or payment has been applied to a debit memo, you are not allowed to unpost the debit memo. After a debit memo is unposted, its status becomes Draft. You can unpost debit memos only if you have the Billing permissions. You can prevent an unpost operation by configuring the 'Do not allow unposting invoices and memos if their revenue is already recognized in a closed accounting period' accounting rule. The default value of this rule is set to 'disabled.' For more information, see Configure Accounting Rules. ### Create a debit memo from an invoice - [POST /v1/debit-memos/invoice/{invoiceKey}](https://developer.zuora.com/v1-api-reference/api/debit-memos/post_debitmemofrominvoice.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Creates an ad-hoc debit memo from an invoice. You can create a debit memo from an invoice only if you have the user permission. See Billing Roles for more information. ### Write off a debit memo - [PUT /v1/debit-memos/{debitMemoKey}/write-off](https://developer.zuora.com/v1-api-reference/api/debit-memos/put_writeoffdebitmemo.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Writes off a debit memo. By writing off a debit memo, a credit memo is automatically created and applied to the debit memo. The generated credit memo items and credit memo taxation items are applied to the corresponding debit memo items and debit memo taxation items respectively. Note: * This API operation is available only if you have enabled the enhanced write-off permission for your tenant. Contact Zuora Global Support to enable this permission. * The total amount must be equal to the amount entered at the invoice item level. * If the non revenue impact value is set to Yes, then the non revenue write off accounting code must be specified. ## E-Invoicing With the E-Invoicing 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. ### List e-invoicing service providers - [GET /v1/einvoice/service-providers](https://developer.zuora.com/v1-api-reference/api/e-invoicing/get_einvoicingserviceproviders.md): Lists information about e-invoicing service providers. Note: This operation is available only if you have the E-Invoicing feature in Early Adopter phase enabled. ### Create an e-invoicing service provider - [POST /v1/einvoice/service-providers](https://developer.zuora.com/v1-api-reference/api/e-invoicing/post_einvoicingserviceprovider.md): Creates an e-invoicing service provider. Note: This operation is available only if you have the E-Invoicing feature in Early Adopter phase enabled. ### Delete an e-invoicing service provider - [DELETE /v1/einvoice/service-providers/{key}](https://developer.zuora.com/v1-api-reference/api/e-invoicing/delete_einvoicingserviceprovider.md): Deletes an e-invoicing service privider. Note: This operation is available only if you have the E-Invoicing feature in Early Adopter phase enabled. ### Retrieve an e-invoicing service provider - [GET /v1/einvoice/service-providers/{key}](https://developer.zuora.com/v1-api-reference/api/e-invoicing/get_einvoicingserviceprovider.md): Retrieves information about an e-invoicing service privider. Note: This operation is available only if you have the E-Invoicing feature in Early Adopter phase enabled. ### Update an e-invoicing service provider - [PUT /v1/einvoice/service-providers/{key}](https://developer.zuora.com/v1-api-reference/api/e-invoicing/put_updateeinvoicingserviceprovider.md): Updates information about an e-invoicing service privider. Note: This operation is available only if you have the E-Invoicing feature in Early Adopter phase enabled. ### List e-invoicing business regions - [GET /v1/einvoice/business-regions](https://developer.zuora.com/v1-api-reference/api/e-invoicing/get_einvoicingbusinessregions.md): Lists information about e-invoicing business regions. Note: This operation is available only if you have the E-Invoicing feature in Early Adopter phase enabled. ### Create an e-invoicing business region - [POST /v1/einvoice/business-regions](https://developer.zuora.com/v1-api-reference/api/e-invoicing/post_createeinvoicingbusinessregion.md): Creates an e-invoicing business region. You must create business regions to store the business detail information as a seller. If you have multiple GSTINs for different states, you can create multiple business region objects for India. The business region objects can be looked up according to the country and state, and its related fields can be mapped accordingly within the e-invoice file template. Note: This operation is available only if you have the E-Invoicing feature in Early Adopter phase enabled. ### Delete an e-invoicing business region - [DELETE /v1/einvoice/business-regions/{key}](https://developer.zuora.com/v1-api-reference/api/e-invoicing/delete_einvoicingbusinessregion.md): Deletes an e-invoicing business region by key. The key can be the unique ID or number of an e-invoicing business region. Note: This operation is available only if you have the E-Invoicing feature in Early Adopter phase enabled. ### Retrieve an e-invoicing business region - [GET /v1/einvoice/business-regions/{key}](https://developer.zuora.com/v1-api-reference/api/e-invoicing/get_einvoicingbusinessregion.md): Retrieves information about an e-invoicing business region. You can search for an e-invoicing business region by key. The key can be the unique ID or number of an e-invoicing business region. Note: This operation is available only if you have the E-Invoicing feature in Early Adopter phase enabled. ### Update an e-invoicing business region - [PUT /v1/einvoice/business-regions/{key}](https://developer.zuora.com/v1-api-reference/api/e-invoicing/put_updateeinvoicingbusinessregion.md): Updates an e-invoicing business region by key. The key can be the unique ID or number of an e-invoicing business region. Note: This operation is available only if you have the E-Invoicing feature in Early Adopter phase enabled. ### List mandates for downloading files - [GET /v1/e-invoice/mandates](https://developer.zuora.com/v1-api-reference/api/e-invoicing/geteinvoicemandates.md): Fetches mandates for downloading files based on the country code, category, and process type selection. This API operation returns the the list of file formats in which the document can be downloaded. Note: This operation is available only if you have the E-Invoicing feature for Avalara in Early Availabiltiy phase enabled. ### Retrieve a mandate for downloading a file - [GET /v1/invoices/{invoiceKey}/e-invoice/mandate](https://developer.zuora.com/v1-api-reference/api/e-invoicing/geteinvoicemandateoninvoice.md): Fetches mandates for downloading e-invoice based on the country code, category, and process type selection. Note: This operation is available only if you have the E-Invoicing feature for Avalara in Early Availabiltiy phase enabled. ### Retrieve a mandate for downloading a credit memo - [GET /v1/credit-memos/{creditMemoKey}/e-invoice/mandate](https://developer.zuora.com/v1-api-reference/api/e-invoicing/geteinvoicecreditmemomandate.md): Fetches mandates for downloading a Credit Memo file based on the country code, category, and process type selection. Note: This operation is available only if you have the E-Invoicing feature for Avalara in Early Availabiltiy phase enabled. ### Retrieve a mandate for downloading a debit memo - [GET /v1/debit-memos/{debitMemoKey}/e-invoice/mandate](https://developer.zuora.com/v1-api-reference/api/e-invoicing/geteinvoicedebitmemomandate.md): Fetches mandates for downloading a Debit Memo file based on the country code, category, and process type selection. Note: This operation is available only if you have the E-Invoicing feature for Avalara in Early Availabiltiy phase enabled. ### Download a file in the specified file format - [GET /v1/invoices/{invoiceKey}/e-invoice/download](https://developer.zuora.com/v1-api-reference/api/e-invoicing/downloadeinvoiceofspecifiedformat.md): Downloads the e-invoice based on the selected file format. The system supports XML, UBL, PNG, or QR codes formats that each country requires or supports. ### Download a credit memo in the specified file format - [GET /v1/credit-memos/{creditMemoKey}/e-invoice/download](https://developer.zuora.com/v1-api-reference/api/e-invoicing/downloadcreditmemoeinvoice.md): Downloads the credit memo based on the specified file format. The system supports XML, UBL, PNG, or QR codes formats that each country requires or supports. ### Download a debit memo in the specified file format - [GET /v1/debit-memos/{debitMemoKey}/e-invoice/download](https://developer.zuora.com/v1-api-reference/api/e-invoicing/downloaddebitmemoeinvoice.md): Downloads the debit memo based on the specified file format. The system supports XML, UBL, PNG, or QR codes formats that each country requires or supports. ### Cancel the e-invoice file for an invoice - [PUT /v1/invoices/{invoiceKey}/e-invoice/cancel](https://developer.zuora.com/v1-api-reference/api/e-invoicing/canceleinvoicebyinvoicekey.md): Cancels the E-Invoice for the given billing document ### List e-invoice file templates - [GET /v1/einvoice/templates](https://developer.zuora.com/v1-api-reference/api/e-invoicing/get_einvoicefiletemplates.md): Lists information about e-invoice file templates. You can query e-invoice file templates by conditions. For example, if your service provider is Sovos, you can use the following example URL to retrieve information about a list of e-invoice file templates for invoices in India: /v1/einvoice/templates?country=IN&documentType=Invoice&provider=Sovos Note: This operation is available only if you have the E-Invoicing feature in Early Adopter phase enabled. ### Create an e-invoice file template - [POST /v1/einvoice/templates](https://developer.zuora.com/v1-api-reference/api/e-invoicing/post_createeinvoicefiletemplate.md): Creates an e-invoice file templates for your billing documents, including invoices, credit memos, and debit memos. Zuora provides default e-invoice file templates, so you can just customize them as needed. For example, some country specific fields like HSN (Harmonized System of Nomenclature) might be stored on product rate plan charges. Note: This operation is available only if you have the E-Invoicing feature in Early Adopter phase enabled. ### Delete an e-invoice file template - [DELETE /v1/einvoice/templates/{key}](https://developer.zuora.com/v1-api-reference/api/e-invoicing/delete_einvoicefiletemplate.md): Deletes an e-invoice file template by key. The key can be the unique ID or number of an e-invoice file template. Note: This operation is available only if you have the E-Invoicing feature in Early Adopter phase enabled. ### Retrieve an e-invoice file template - [GET /v1/einvoice/templates/{key}](https://developer.zuora.com/v1-api-reference/api/e-invoicing/get_einvoicefiletemplate.md): Retrieves information about an e-invoice file template. Note: This operation is available only if you have the E-Invoicing feature in Early Adopter phase enabled. ### Update an e-invoice file template - [PUT /v1/einvoice/templates/{key}](https://developer.zuora.com/v1-api-reference/api/e-invoicing/put_einvoicefiletemplate.md): Updates information about an e-invoice file template. Note: This operation is available only if you have the E-Invoicing feature in Early Adopter phase enabled. ### Sync the e-Invoice status of an invoice - [PUT /v1/invoices/{invoiceKey}/e-invoice/sync-status](https://developer.zuora.com/v1-api-reference/api/e-invoicing/updateinvoiceinvokesyncstatus.md): Initiates a background polling process to retrieve the latest notification response from the configured e-Invoicing provider and update the e-Invoice status of the e-Invoice. Note: This API can only be invoked when the current e-Invoice status is one of: Processing, ApprovedByAuthority, RetrieveTimeout, or Failed. If the status is different, the request will be rejected. ### Sync the e-Invoice status of a debit memo - [PUT /v1/debit-memos/{debitMemoKey}/e-invoice/sync-status](https://developer.zuora.com/v1-api-reference/api/e-invoicing/updatedebitmemoinvokesyncstatus.md): Initiates a background polling process to retrieve the latest notification response from the configured e-Invoicing provider and update the e-Invoice status of the debit memo. Note: This API can only be invoked when the current e-Invoice status is one of: Processing, ApprovedByAuthority, RetrieveTimeout, or Failed. If the status is different, the request will be rejected. ### Sync the e-Invoice status of a credit memo - [PUT /v1/credit-memos/{creditMemoKey}/e-invoice/sync-status](https://developer.zuora.com/v1-api-reference/api/e-invoicing/updatecreditmemoinvokesyncstatus.md): Initiates a background polling process to retrieve the latest notification response from the configured e-Invoicing provider and update the e-Invoice status of the credit memo. Note: This API can only be invoked when the current e-Invoice status is one of: Processing, ApprovedByAuthority, RetrieveTimeout, or Failed. If the status is different, the request will be rejected. ### Generate an e-invoice file for an invoice - [PUT /v1/invoices/{invoiceKey}/einvoice/generate](https://developer.zuora.com/v1-api-reference/api/e-invoicing/put_generationeinvoicegenerationforinvoices.md): Generates an e-invoice file for an invoice. If the invoice status is Failed during e-invoice generation, you can use Regenerate E-Invoice. Once you fix the errors and trigger the regeneration, the system will resubmit the document to the e-invoicing service provider, and its status will update to Processing. Note: - E-invoicing with Sovos and E-invoicing with PEPPOL Extract are generally available. - E-invoicing with Avalara is in the Early Availability phase. We are actively soliciting feedback from a small set of early availability users before releasing this feature as generally available. If you want to join this early availability program, submit a request at Zuora Global Support. The Regenerate E-Invoice action is available in the Generated status for the PEPPOL service provider. ### Generate an e-invoice file for a credit memo - [PUT /v1/credit-memos/{creditMemoKey}/e-invoice/generate](https://developer.zuora.com/v1-api-reference/api/e-invoicing/put_generateeinvoicefileforcreditmemo.md): Generates an e-invoice file for a credit memo. If the Credit Memo status is Failed during e-invoice generation, you can use Regenerate E-Invoice. Once you fix the errors and trigger the regeneration, the system will resubmit the document to the e-invoicing service provider, and its status will update to Processing. Note: - E-invoicing with Sovos and E-invoicing with PEPPOL Extract are generally available. - E-invoicing with Avalara is in the Early Availability phase. We are actively soliciting feedback from a small set of early availability users before releasing this feature as generally available. If you want to join this early availability program, submit a request at Zuora Global Support. The Regenerate E-Invoice action is available in the Generated status for the PEPPOL service provider. ### Generate an e-invoice file for a debit memo - [PUT /v1/debit-memos/{debitMemoKey}/e-invoice/generate](https://developer.zuora.com/v1-api-reference/api/e-invoicing/put_generateeinvoicefilefordebitmemo.md): Generates an e-invoice file for a debit memo. If the Credit Memo status is Failed during e-invoice generation, you can use Regenerate E-Invoice. Once you fix the errors and trigger the regeneration, the system will resubmit the document to the e-invoicing service provider, and its status will update to Processing. Note: - E-invoicing with Sovos and E-invoicing with PEPPOL Extract are generally available. - E-invoicing with Avalara is in the Early Availability phase. We are actively soliciting feedback from a small set of early availability users before releasing this feature as generally available. If you want to join this early availability program, submit a request at Zuora Global Support. The Regenerate E-Invoice action is available in the Generated status for the PEPPOL service provider. ## Invoice Schedules Use invoice schedules to trigger invoice generation processes. For more information about invoice schedules, see Billing Schedule overview. ### Create an invoice schedule - [POST /v1/invoice-schedules](https://developer.zuora.com/v1-api-reference/api/invoice-schedules/post_createinvoiceschedule.md): Creates an invoice schedule. ### Limitations This API operation has the following limitations: * You can create at most 50 invoice schedule items in one request. * You can associate at most 10 orders with an invoice schedule in one request. * You can associate at most 300 subscriptions with an invoice schedule in one request, including those contained in orders and separate subscriptions. Note: This operation is available only if you have the Billing Schedule feature enabled. ### Delete an invoice schedule - [DELETE /v1/invoice-schedules/{scheduleKey}](https://developer.zuora.com/v1-api-reference/api/invoice-schedules/delete_invoiceschedule.md): Deletes an invoice schedule in Pending status. The status of the invoice schedule to be deleted must be Pending. Note: This operation is available only if you have the Billing Schedule feature enabled. ### Retrieve an invoice schedule - [GET /v1/invoice-schedules/{scheduleKey}](https://developer.zuora.com/v1-api-reference/api/invoice-schedules/get_invoiceschedule.md): Retrieves detailed information about an invoice schedule. Note: This operation is available only if you have the Billing Schedule feature enabled. ### Update an invoice schedule - [PUT /v1/invoice-schedules/{scheduleKey}](https://developer.zuora.com/v1-api-reference/api/invoice-schedules/put_updateinvoiceschedule.md): Updates a pending invoice schedule. You can use this API operation to update invoice schedules in the following aspects: - Update notes and pending invoice schedule items - Update orders associated with invoice schedules - Remove or add invoice schedule items For more samples, see Edit invoice schedules ### Restrictions and limitations When updating invoice schedules through the REST API, keep the following restrictions and limitations in mind: - You can only update invoice schedule items in Pending status. - You can only add orders or specific subscriptions to pending invoice schedules, and remove orders or specific subscriptions from pending invoice schedules. - For the invoice schedule items that you want to update, you must include the new values for these items in the request. - For the invoice schedule items that you want to keep unchanged, you must include all the existing information about these items in the request. Otherwise, the existing invoice schedule items that you do not include in the request are deleted. - For the orders that you want to keep unchanged for an invoice schedule, you must include all the existing order numbers associated with the invoice schedule in the request. Otherwise, the existing orders that you do not include in the request are removed. Note: This operation is available only if you have the Billing Schedule feature enabled. ### Execute an invoice schedule - [POST /v1/invoice-schedules/{scheduleKey}/execute](https://developer.zuora.com/v1-api-reference/api/invoice-schedules/post_executeinvoiceschedule.md): Executes an invoice schedule immediately. During the execution, a bill run is created and generates an invoice or a credit memo asynchronously. When you use this API operation to execute an invoice schedule item, you have the flexibility to decide whether to specify a specific item ID. - If you specify the unique ID of an invoice schedule item to be executed in the request, the corresponding invoice schedule item is executed. - If you do not specify the ID of any invoice schedule item in the request, the subscription end date is used as the target date to determine the next pending schedule item to be executed. A paused invoice schedule and charges inside cannot be automatically executed by Zuora Scheduler or by this "Execute an invoice schedule" API operation. In this case, you can do one of the following: - Use the Generate billing documents by account ID API operation - Create a bill run with the target date greater than the next run date of the invoice schedule through UI or API For more samples, see Execute invoice schedules. Note: This operation is available only if you have the Billing Schedule feature enabled. ### Pause an invoice schedule - [PUT /v1/invoice-schedules/{scheduleKey}/pause](https://developer.zuora.com/v1-api-reference/api/invoice-schedules/put_pauseinvoiceschedule.md): Pauses an invoice schedule immediately. A paused invoice schedule and charges inside cannot be automatically executed by Zuora Scheduler or by the Execute an invoice schedule API operation. In this case, you can do one of the following: - Use the Generate billing documents by account ID API operation - Create a bill run with the target date greater than the next run date of the invoice schedule through UI or API Note: This operation is available only if you have the Billing Schedule feature enabled. ### Resume an invoice schedule - [PUT /v1/invoice-schedules/{scheduleKey}/resume](https://developer.zuora.com/v1-api-reference/api/invoice-schedules/put_resumeinvoiceschedule.md): Resumes an invoice schedule in Paused status immediately. After an invoice schedule is resumed, it can continue to be automatically executed by Zuora Scheduler or by the Execute an invoice schedule API operation. Note: This operation is available only if you have the Billing Schedule feature enabled. ### Detach charges from an invoice schedule - [PUT /v1/invoice-schedules/{scheduleKey}/detach](https://developer.zuora.com/v1-api-reference/api/invoice-schedules/detachchargesfrominvoiceschedule.md): Detaches charges from an invoice schedule. The invoice schedules you want to detach charges from must be in Fully Processed or Partially Processed status. Invoice schedules do not bill detached charges. ### Attach charges to an invoice schedule - [PUT /v1/invoice-schedules/{scheduleKey}/attach](https://developer.zuora.com/v1-api-reference/api/invoice-schedules/attachchargestoinvoiceschedule.md): Attaches charges to an invoice schedule. The invoice schedules you want to attach charges to must be in Fully Processed or Partially Processed status. You can attach charges only if they were previously detached from the same invoice schedule. Invoice schedules will automatically bill re-attached charges in the upcoming planned invoice schedule items. ## Taxation Items 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 Z-Tax or a third-party tax engine such as Avalara or Connect tax engine. Changes that you make with this object affect the product charges in your product catalog, but not the charges in existing subscriptions. ### CRUD: Create a taxation item - [POST /v1/object/taxation-item](https://developer.zuora.com/v1-api-reference/api/taxation-items/object_posttaxationitem.md): Creates a Taxation Item object. ### Delete a taxation item - [DELETE /v1/taxation-items/{id}](https://developer.zuora.com/v1-api-reference/api/taxation-items/delete_taxationitem.md): Deletes a specific taxation item by ID. ### Retrieve a taxation item - [GET /v1/taxation-items/{id}](https://developer.zuora.com/v1-api-reference/api/taxation-items/get_taxationitem.md): Retrieves the information about a specific taxation item by ID. ### Update a taxation item - [PUT /v1/taxation-items/{id}](https://developer.zuora.com/v1-api-reference/api/taxation-items/put_taxationitem.md): Updates a specific taxation item by ID. ## Sequence Sets 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 Create Billing Document Sequence Sets for more information. ### List sequence sets - [GET /v1/sequence-sets](https://developer.zuora.com/v1-api-reference/api/sequence-sets/get_sequencesets.md): Retrieves information about all sequence sets configured for billing documents, payments, and refunds. Billing documents include invoices, credit memos, and debit memos. You can use query parameters to restrict the data returned in the response. Note: The Credit and Debit Memos feature is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. ### Create sequence sets - [POST /v1/sequence-sets](https://developer.zuora.com/v1-api-reference/api/sequence-sets/post_sequencesets.md): Creates sequence sets, allowing distinct numbering sequences for billing documents, payments, and refunds. Billing documents include invoices, credit memos, and debit memos. You can create a maximum of 100 sequence sets in one single request. A sequence set comprises a set of custom prefixes and starting numbers that are used for billing documents to generate, and payments and refunds to create. See Prefix and Numbering Configuration for Billing Documents for more information about limitations. Note: The Credit and Debit Memos feature is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. ### Delete a sequence set - [DELETE /v1/sequence-sets/{id}](https://developer.zuora.com/v1-api-reference/api/sequence-sets/delete_sequenceset.md): Deletes a specific sequence set configured for billing documents, payments, and refunds. Billing documents include invoices, credit memos, and debit memos. Note: The Credit and Debit Memos feature is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. ### Retrieve a sequence set - [GET /v1/sequence-sets/{id}](https://developer.zuora.com/v1-api-reference/api/sequence-sets/get_sequenceset.md): Retrieves information about a specific sequence set configured for billing documents, payments, and refunds. Billing documents include invoices, credit memos, and debit memos Note: The Credit and Debit Memos feature is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. ### Update a sequence set - [PUT /v1/sequence-sets/{id}](https://developer.zuora.com/v1-api-reference/api/sequence-sets/put_sequenceset.md): Updates a specific sequence set configured for billing documents, payments, and refunds. Billing documents include invoices, credit memos, and debit memos. Note: The Credit and Debit Memos feature is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. ## Operations Use operations to generate invoices and credit memos, collect payments for posted invoices, and generate previews of future invoice items for customer accounts. ### Generate a billing preview - [POST /v1/operations/billing-preview](https://developer.zuora.com/v1-api-reference/api/operations/post_billingpreview.md): Generates a preview of future invoice items for one customer account. Use the BillingPreview call to calculate how much a single customer will be invoiced from the most recent invoice to a specific end of term date in the future. Additionally, you can use the BillingPreview service to access real-time data on an individual customer's usage consumption. The BillingPreview call only calculates taxes for charges in the subscription if you use Zuora Tax and the product rate plan charge associated with the invoice item uses the tax inclusive mode; otherwise, this call does not calculate taxes. If you have the Invoice Settlement feature enabled, you can also generate a preview of future credit memo items for one customer account. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. ### Invoice and collect - [POST /v1/operations/invoice-collect](https://developer.zuora.com/v1-api-reference/api/operations/post_transactioninvoicepayment.md): Generates and posts invoices and credit memos and collects payments for posted invoices. Credit memos are only available if you have the Invoice Settlement feature enabled and negative charges exist. Credit memos will not be applied to invoices. If draft invoices and credit memos exist when you run this operation, this operation will post the invoices and credit memos. Note that draft credit memos created from an invoice or a product rate plan charge will not be posted. You can use this operation to generate invoices and collect payments on the posted invoices, or else simply collect payment on a specified existing invoice. The customer's default payment method is used, and the full amount due is collected. The operation depends on the parameters you specify. - To generate one or more new invoices for that customer and collect payment on the generated and other unpaid invoice(s), leave the invoiceId field empty. - To collect payment on an existing invoice, specify the invoice ID. The operation is atomic; if any part is unsuccessful, the entire operation is rolled back. When an error occurs, gateway reason codes and error messages are returned the error response of this operation. The following items are some gateway response code examples. - Orbital: 05 Do Not Honor; 14 Invalid Credit Card Number - Vantiv: 301 Invalid Account Number; 304 Lost/Stolen Card - CyberSource2: 202 Expired card; 231 Invalid account number For more reason code information, see the corresponding payment gateway documentation. ### Notes Timeouts may occur when using this method on an account that has an extremely high number of subscriptions. ### Retrieve an operation job - [GET /v1/operations/jobs/{jobId}](https://developer.zuora.com/v1-api-reference/api/operations/get_operationjob.md): Retrieves information about a specific operation job. Currently, you can only use this API operation to retrieve the status information about invoice deletion and reversal operation jobs. ### Export bulk PDF files - [POST /v1/operations/bulk-pdf](https://developer.zuora.com/v1-api-reference/api/operations/create_bulkpdftozipgeneration.md): The background job that compresses large number of PDF(s) into ZIP files. For answers to frequently asked questions regarding exporting bulk PDF files, see Export Bulk PDF Files FAQs. Note: Do not include multiple objectIds with the same PDF file names in a single bulk PDF upload request. ### Retrieve information of a bulk PDF file generation job - [GET /v1/operations/bulk-pdf/{jobId}](https://developer.zuora.com/v1-api-reference/api/operations/get_bulkpdftozipgeneration.md): Retrieves information about the job which includes its status, message, and downloadable ZIP file URL link. ## Summary Statements 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 Account Summary Statements for more information. ### Create a summary statement run - [POST /v1/summary-statement-runs](https://developer.zuora.com/v1-api-reference/api/summary-statements/createsummarystatementrun.md): Allows you to initiate the generation of a summary statement run. You can specify parameters such as the run type (AdHoc or scheduled) and the target account categories (single or multiple accounts). ## Bill Run 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 Bill runs. ### Create a bill run - [POST /v1/bill-runs](https://developer.zuora.com/v1-api-reference/api/bill-run/post_createbillrun.md): Creates an ad-hoc bill run or a scheduled bill run. Support the following: - Create ad-hoc or scheduled bill runs by batch - Create ad-hoc or scheduled bill runs by account - Create a bill run by subscription - Create ad-hoc or scheduled bill runs by custom filter combining the Account, Subscription, and Rate Plan objects. To use this operation, you must have the Create Bill Runs billing permission. Notes When using this operation to create bill runs, keep the following notes in mind: - When creating bill runs by batch, you must specify the batches field and do not specify billRunFilters field. When creating bill runs by account, subscription, or custom filter, you must specify the billRunFilters field and do not specify the batches field. - When creating bill runs by account, only one single account is allowed. All subscription under the account are picked up. - When creating a bill run by subscription, all subscriptions must belong to the same account. At most 50 subscriptions are allowed. - If more than 500 bill runs created through this operation are in Pending status, you cannot use this operation to create any more bill runs. ### Delete a bill run - [DELETE /v1/bill-runs/{billRunId}](https://developer.zuora.com/v1-api-reference/api/bill-run/delete_deletebillrun.md): Deletes a bill run. You can only delete bill runs in Canceled or Error status. ### Retrieve a bill run - [GET /v1/bill-runs/{billRunId}](https://developer.zuora.com/v1-api-reference/api/bill-run/get_billrun.md): Retrieves the information about a specific bill run. ### Cancel a bill run - [PUT /v1/bill-runs/{billRunId}/cancel](https://developer.zuora.com/v1-api-reference/api/bill-run/put_cancelbillrun.md): Cancels a bill run in Draft status. When cancelling a scheduled bill run, keep the following information in mind: - If you set cancelOnce to true, only the current bill run is cancelled. The other future scheduled bill runs will be automatically executed based on the schedule. - If you set cancelOnce to false, all future recurring bill runs are cancelled. ### Post a bill run - [PUT /v1/bill-runs/{billRunId}/post](https://developer.zuora.com/v1-api-reference/api/bill-run/put_postbillrun.md): Posts a bill run asynchronously. To post a bill run, the current bill run must be in Completed status. When a bill run is being posted, its status is changed to PostInProgress. After all invoices for this bill run are posted, its status is changed to Posted. ### Email billing documents generated from a bill run - [POST /v1/bill-runs/{billRunKey}/emails](https://developer.zuora.com/v1-api-reference/api/bill-run/post_emailbillingdocumentsfrombillrun.md): Manually emails all the billing documents that are generated from a specified bill run to your customers. Bill runs can generate invoices and credit memos based on your invoice and credit memo generation rule. Credit memos are only available if you have the Invoice Settlement feature enabled. Using this API operation, the billing documents are sent to the email addresses specified in the To Email field of the email templates. The email template used for each billing document is set in the Delivery Options panel of the Edit notification dialog from the Zuora UI. See Edit Email Templates for more information about how to edit the To Email field in the email template. ### Notes - Even though no field is required in the Request body, you still need to specify {} in the request. Otherwise, an error will be returned. - You can only email posted billing documents. - You must activate the following notifications before emailing invoices and credit memos: - Manual Email For Invoice | Manual Email For Invoice - Email Credit Memo | Manually email Credit Memo - To include the invoice PDF in the email, select the Include Invoice PDF check box in the Edit notification dialog from the Zuora UI. To include the credit memo PDF in the email, select the Include Credit Memo PDF check box in the Edit notification dialog from the Zuora UI. See Create and Edit Notifications for more information. - Zuora sends the email messages based on the email template you set. You can set the email template to use in the Delivery Options panel of the Edit notification dialog from the Zuora UI. By default, the following templates are used for billing documents: - Invoices: Invoice Posted Default Email Template - Credit memos: Manual Email for Credit Memo Default Template See Create and Edit Email Templates for more information. ## Billing Preview Run 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 Invoice Settlement feature enabled. ### Create a billing preview run - [POST /v1/billing-preview-runs](https://developer.zuora.com/v1-api-reference/api/billing-preview-run/post_billingpreviewrun.md): Creates a billing preview run for single and multiple customer accounts. The maximum supported preview duration is 20 years, calculated from the current date to the target date. You can run up to 20 billing preview runs in batches concurrently. A single batch of customer accounts can only have one billing preview run at a time. So you can have up to 20 batches running at the same time. If you create a billing preview run for all customer batches, you cannot create another billing preview run until this preview run is completed. Note: The preview results for each billing preview run will be stored in the system for 180 days; after that they will be purged. ### Retrieve a billing preview run - [GET /v1/billing-preview-runs/{billingPreviewRunId}](https://developer.zuora.com/v1-api-reference/api/billing-preview-run/get_billingpreviewrun.md): Retrieves a preview of future invoice items for multiple customer accounts through a billing preview run. If you have the Invoice Settlement feature enabled, you can also retrieve a preview of future credit memo items. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. A billing preview run asynchronously generates a downloadable CSV file containing a preview of invoice item data and credit memo item data for a batch of customer accounts. Note that if you set storageOption to Database, no CSV file is generate; instead, you can have a record in the billing preview result. You can use data source to query Billing Preview Run Result. ## Payment Methods Payment methods represents payment method details associated with a customer account. ### Create a payment method - [POST /v1/payment-methods](https://developer.zuora.com/v1-api-reference/api/payment-methods/post_paymentmethods.md): You can use this operation to create either a payment method associated with a specific customer account, or an orphan payment method that is not associated with any customer account. To view the applicable fields for each payment method type, select the payment method type from the type list. The following types of the payment methods are supported: * CreditCard - Credit card payment method. * CreditCardReferenceTransaction - Credit Card Reference Transaction. See [Supported payment methods](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/L_Payment_Methods/Supported_Payment_Methods) for payment gateways that support this type of payment method. * ACH - ACH payment method. * SEPA - Single Euro Payments Area. * Betalingsservice - Direct Debit DK. * Autogiro - Direct Debit SE. * Bacs - Direct Debit UK. * Becs - Direct Entry AU. * Becsnz - Direct Debit NZ. * PAD - Pre-Authorized Debit. * PayPalCP - PayPal Commerce Platform payment method. Use this type if you are using a [PayPal Commerce Platform Gateway](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/M_Payment_Gateways/Supported_Payment_Gateways/PayPal_Commerce_Platform_Gateway) instance. * PayPalEC - PayPal Express Checkout payment method. Use this type if you are using a [PayPal Payflow Pro Gateway](https://knowledgecenter.zuora.com/CB_Billing/M_Payment_Gateways/Supported_Payment_Gateways/PayPal_Payflow_Pro%2C_Website_Payments_Payflow_Edition%2C_Website_Pro_Payment_Gateway) instance. * PayPalNativeEC - PayPal Native Express Checkout payment method. Use this type if you are using a [PayPal Express Checkout Gateway](https://knowledgecenter.zuora.com/CB_Billing/M_Payment_Gateways/Supported_Payment_Gateways/PayPal_Express_Checkout_Gateway) instance. * PayPalAdaptive - PayPal Adaptive payment method. Use this type if you are using a [PayPal Adaptive Payment Gateway](https://knowledgecenter.zuora.com/CB_Billing/M_Payment_Gateways/Supported_Payment_Gateways/PayPal_Adaptive_Payments_Gateway) instance. * AdyenApplePay - Apple Pay on Adyen Integration v2.0. See [Set up Adyen Apple Pay](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/L_Payment_Methods/Payment_Method_Types/Apple_Pay_on_Web/Set_up_Adyen_Apple_Pay) for details. * AdyenGooglePay - Google Pay on Adyen Integration v2.0. See [Set up Adyen Google Pay](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/L_Payment_Methods/Payment_Method_Types/Set_up_Adyen_Google_Pay) for details. * GooglePay - Google Pay on Chase Paymentech Orbital gateway integration. See [Set up Google Pay on Chase](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/L_Payment_Methods/Payment_Method_Types/Set_up_Google_Pay_on_Chase) for details. * AmazonPay - Amazon Pay integration. The fields marked as required must be specified when creating non-tokenized payment methods. For more information about the required fields for the tokenization of payment methods, see Create tokenized payment methods with existing tokens or account information. ### Create an Apple Pay payment method - [POST /v1/payment-methods/decryption](https://developer.zuora.com/v1-api-reference/api/payment-methods/post_paymentmethodsdecryption.md): The decryption API endpoint can conditionally perform 4 tasks in one atomic call: * Decrypt Apple Pay Payment token * Create Credit Card Payment Method in Zuora with decrypted Apple Pay information * Create a stored credential profile within the Apple Pay payment method * Process Payment on a specified Invoice (optional) ### Delete a payment method - [DELETE /v1/payment-methods/{payment-method-id}](https://developer.zuora.com/v1-api-reference/api/payment-methods/delete_paymentmethods.md): Deletes a credit card payment method. If the specified payment method is the account's default payment method, the request will fail. In that case, you must first designate a different payment method for that customer to be the default. ### Retrieve a payment method - [GET /v1/payment-methods/{payment-method-id}](https://developer.zuora.com/v1-api-reference/api/payment-methods/get_paymentmethod.md): Use this operation to get the detailed information of an electronic payment method. To retrieve information of both electronic and non-electronic payment methods, use the Object Query operation. Note: This operation also supports retrieving the custom payment method created through the Open Payment Method service. ### Update a payment method - [PUT /v1/payment-methods/{payment-method-id}](https://developer.zuora.com/v1-api-reference/api/payment-methods/put_paymentmethod.md): This operation allows you to update an existing payment method. The following fields in the request body can be updated for any payment method types: - maxConsecutivePaymentFailures - paymentRetryWindow - useDefaultRetryRule The following fields in the request body can be updated for any payment method types except for Credit Card Reference Transaction payment methods: - authGateway - accountHolderInfo - gatewayOptions - ipAddress - Custom fields The following fields in the request body can be updated only for Credit Card payment methods: - expirationMonth - expirationYear - securityCode The following field in the request body can be updated for Credit Card, Credit Card Reference Transaction, ACH, and Bank Transfer payment methods: - mandateInfo ### Verify a payment method - [PUT /v1/payment-methods/{payment-method-id}/verify](https://developer.zuora.com/v1-api-reference/api/payment-methods/put_verifypaymentmethods.md): Sends an authorization request to the corresponding payment gateway to verify the payment method, even though no changes are made for the payment method. Supported payment methods are Credit Cards and Paypal. Zuora now supports performing a standalone zero dollar verification or one dollar authorization for credit cards. It also supports a billing agreement status check on PayPal payment methods. If a payment method is created by Hosted Payment Pages and is not assigned to any billing account, the payment method cannot be verified through this operation. ### Scrub a payment method - [PUT /v1/payment-methods/{payment-method-id}/scrub](https://developer.zuora.com/v1-api-reference/api/payment-methods/put_scrubpaymentmethods.md): This operation enables you to replace all sensitive data in a payment method, related payment method snapshot table, and four related log tables with dummy values that will be stored in Zuora databases. This operation will scrub the sensitive data and soft-delete the specified payment method at the same time. If you want to delete or anonymize personal data in Zuora, you must scrub the payment method before anonymizing the associated account and contact. See Delete or anonymize personal data for more information. Note: In order to use this operation, you must ensure that the Scrub Sensitive Data of Specific Payment Method payments permission is enabled in your user role. Contact your tenant administrator if you want to enable this permission. See Scrub Payment Methods for more information. ### Retrieve the balance of a bank account - [GET /v1/payment-methods/{payment-method-id}/balance](https://developer.zuora.com/v1-api-reference/api/payment-methods/getbankaccountbalance.md): Zuora supports Plaid's Auth and Balance products for ACH transactions. Auth authenticates account details before sending requests to the gateway, while Balance checks the real-time account balance before transactions. Use this API operation to implement the integration with Plaid Balance manually. Before you use this API operation, ensure that the support for Plaid Auth and Balance is enabled. For more information, see Enable the support for Plaid account validation solution. ### List stored credential profiles of a payment method - [GET /v1/payment-methods/{payment-method-id}/profiles](https://developer.zuora.com/v1-api-reference/api/payment-methods/get_storedcredentialprofiles.md): Retrieves the stored credential profiles within a payment method. ### Create a stored credential profile - [POST /v1/payment-methods/{payment-method-id}/profiles](https://developer.zuora.com/v1-api-reference/api/payment-methods/post_createstoredcredentialprofile.md): Creates a stored credential profile within a payment method. The stored credential profile represents a consent agreement that you have established with a customer. When you use the payment method in a transaction, Zuora may include information from the stored credential profile to inform the payment processor that the transaction is related to your pre-existing consent agreement with the customer. ### Cancel a stored credential profile - [POST /v1/payment-methods/{payment-method-id}/profiles/{profile-number}/cancel](https://developer.zuora.com/v1-api-reference/api/payment-methods/post_cancelstoredcredentialprofile.md): Cancels a stored credential profile within a payment method. Cancelling the stored credential profile indicates that the stored credentials are no longer valid, per a customer request. You cannot reactivate the stored credential profile after you have cancelled it. ### Expire a stored credential profile - [POST /v1/payment-methods/{payment-method-id}/profiles/{profile-number}/expire](https://developer.zuora.com/v1-api-reference/api/payment-methods/post_expirestoredcredentialprofile.md): Expires a stored credential profile within a payment method. Expiring the stored credential profile indicates that the stored credentials are no longer valid, per an expiration policy in the stored credential transaction framework. You cannot reactivate the stored credential profile after you have expired it. ### List registered Apple Pay domains - [GET /v1/payment-methods/apple-pay/domains](https://developer.zuora.com/v1-api-reference/api/payment-methods/get_listapplepaydomains.md): Use this operation to retrieve details of your domains that are already registered with Apple for Apple Pay button integration implemented through Zuora's JavaScript SDK. You can use domainName as the query parameter to restrict domains returned in the response. Specify a domain name and the registered domains containing the specified domain name will be returned. For more information about Zuora's JavaScript SDK for Apple Pay integration, see Set up Apple Pay through the JavaScript SDK approach. ### Register an Apple Pay domain - [POST /v1/payment-methods/apple-pay/domains](https://developer.zuora.com/v1-api-reference/api/payment-methods/post_registerapplepaydomain.md): Before adding Apple Pay to your checkout flow by integrating with the JavaScript SDK provided by Zuora, your domains that will show the Apple Pay button must be registered with Apple. Use this operation to register a domain. For more information about Zuora's JavaScript SDK for Apple Pay integration, see Set up Apple Pay through the JavaScript SDK approach. ### Unregister an Apple Pay domain - [DELETE /v1/payment-methods/apple-pay/domains/{id}](https://developer.zuora.com/v1-api-reference/api/payment-methods/delete_unregisterapplepaydomain.md): Use this operation to unregister a domain with Apple for Apple Pay button integration implemented through Zuora's JavaScript SDK. For more information about Zuora's JavaScript SDK for Apple Pay integration, see Set up Apple Pay through the JavaScript SDK approach. ### Create a payment session - [POST /web-payments/sessions](https://developer.zuora.com/v1-api-reference/api/payment-methods/post_createpaymentsession.md): Use this operation to create a payment session on your server side. The response contains a token for the payment session data. In addition to the required accountId and currency fields, you can specify the following fields to define the payment flow mode as one of the following: - Create and save a payment method: - processPayment: false - storePaymentMethod: true - amount - Process a one-time payment without saving the payment method: - processPayment: true - storePaymentMethod: false - amount or invoices + amount - Process the first payment and save the payment method for subsequent recurring payments: - processPayment: true - storePaymentMethod: true - amount or invoices + amount For more information, see the following articles: - Payment Form Implementation Guide - Set up a payment method through JavaScript SDK integration - Set up Alipay payment methods with Zuora JavaScript SDK ## Custom Payment Method Types 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. ### Create a draft custom payment method type - [POST /open-payment-method-types](https://developer.zuora.com/v1-api-reference/api/custom-payment-method-types/post_createdraftopenpaymentmethodtype.md): Creates a draft version of a custom payment method type. Revision number 1 is assigned to this version. You can update your draft version through the Update a custom payment method type operation. You must publish your draft version through the Publish a custom payment method type operation before your custom payment method type goes live. ### Publish a custom payment method type - [PUT /open-payment-method-types/publish/{paymentMethodTypeName}](https://developer.zuora.com/v1-api-reference/api/custom-payment-method-types/put_publishopenpaymentmethodtype.md): Publish the latest draft revision of a specific custom payment method type. ### Update a custom payment method type - [PUT /open-payment-method-types/{paymentMethodTypeName}](https://developer.zuora.com/v1-api-reference/api/custom-payment-method-types/put_updateopenpaymentmethodtype.md): Update the latest draft version of your custom payment method type. If the latest draft version has been published, the revision number is increased by 1 after the draft version is updated. You must publish your latest revision again through the Publish a custom payment method type operation before your updated custom payment method type goes live. Note: In the request body, provide all the fields that define this custom payment method type including fields to be updated and the unchanged fields. ### Retrieve a specific draft revision of a custom payment method type - [GET /open-payment-method-types/{paymentMethodTypeName}/draft/{revisionNumber}](https://developer.zuora.com/v1-api-reference/api/custom-payment-method-types/get_openpaymentmethodtyperevision.md): Retrieves a specific draft revision of a custom payment method type. ### Retrieve a published custom payment method type - [GET /open-payment-method-types/{paymentMethodTypeName}/published](https://developer.zuora.com/v1-api-reference/api/custom-payment-method-types/get_openpaymentmethodtypepublish.md): Retrieves a published custom payment method type. ## Payment Method Updater 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 Payment Method Updater. ### List Payment Method Updater instances - [GET /v1/payment-method-updaters](https://developer.zuora.com/v1-api-reference/api/payment-method-updater/get_paymentmethodupdaterinstances.md): Retrieves the detailed information of all Payment Method Updater (PMU) instances on your tenant, except for American Express (AMEX). ### Create a Payment Method Updater batch asynchronously - [POST /v1/payment-method-updaters/batches](https://developer.zuora.com/v1-api-reference/api/payment-method-updater/post_paymentmethodupdaterbatch.md): Creates a Payment Method Updater (PMU) batch asynchronously. PMU for American Express (AMEX) is not supported. ## Payment Method Snapshots 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. ### CRUD: Retrieve a payment method snapshot - [GET /v1/object/payment-method-snapshot/{id}](https://developer.zuora.com/v1-api-reference/api/payment-method-snapshots/object_getpaymentmethodsnapshot.md): This REST API reference describes how to retrieve a Payment Method Snapshot. A Payment Method Snapshot is a copy of the particular Payment Method used in a transaction. If the Payment Method is deleted, the Payment Method Snapshot continues to retain the data used in each of the past transactions. ### Notes The following Payment Method fields are not available in Payment Method Snapshots: * Active * AchAddress1 * AchAddress2 * CreatedById * CreatedDate * UpdatedById * UpdatedDate The Payment Method Snapshot field PaymentMethodId is not available in Payment Methods. ## Payment Method Transaction Logs 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. ### CRUD: Retrieve a payment method transaction log - [GET /v1/object/payment-method-transaction-log/{id}](https://developer.zuora.com/v1-api-reference/api/payment-method-transaction-logs/object_getpaymentmethodtransactionlog.md): Retrieves a Payment Method Transaction Log object. ## Hosted Pages 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 Hosted Payment Pages. ### List hosted pages - [GET /v1/hostedpages](https://developer.zuora.com/v1-api-reference/api/hosted-pages/get_hostedpages.md): Returns the Payment Pages configuration metadata, specifically, page ID, page version, payment method type. The following are the version-specific and general REST requests for Payment Pages: * The request for Payment Pages 2.0 configuration information: GET /hostedpages?version=2 * The request for all versions of Payment Pages configuration information: GET /hostedpages ### Notes If you do not have the corresponding tenant setting enabled, such as specifying the request version parameter to 2 but disabliing Payment Pages 2.0, you will receive an error. ## RSA Signatures 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." ### Generate an RSA signature - [POST /v1/rsa-signatures](https://developer.zuora.com/v1-api-reference/api/rsa-signatures/post_rsasignatures.md): The REST API used in Payment Pages 2.0 are CORS (Cross-Origin Resource Sharing) enabled and therefore requires a digital signature. The POST rsa_signatures call generates and returns the required digital signature and token for a Payment Pages 2.0 form. You need to pass the generated signature to your client for it to access Payment Pages 2.0. This REST service should be used only when you implement Payment Pages 2.0. Note: To avoid potential credit card fraud attacks, you should secure your Payment Pages from being accessed by fraudulent users before you issue client-side digital signatures and tokens. See Manage Token Issuance for more information. Troubleshooting tip: After you use this operation to generate an RSA signature, if signature returns null but token is successfully returned, please limit the number of the fields in your request to make sure that the maximum length supported by the RSA signature algorithm is not exceeded. The calculation of the request length is determined by the number of the parameters, and the length of each of the parameter name and its value. ### Decrypt an RSA signature - [POST /v1/rsa-signatures/decrypt](https://developer.zuora.com/v1-api-reference/api/rsa-signatures/post_decryptrsasignatures.md): The REST API used in Payment Pages 2.0 are CORS (Cross-Origin Resource Sharing) enabled and therefore requires a digital signature. You use rsa_signatures to generate the required digital signature and token for a Payment Pages 2.0 form, and then you use the decrypt REST service to decrypt the signature to validate the signature and key. This REST service should be used only when you implement Payment Pages 2.0. ## Payment Authorization 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. ### Create authorization - [POST /v1/payment-methods/{payment-method-id}/authorize](https://developer.zuora.com/v1-api-reference/api/payment-authorization/post_createauthorization.md): Enables you to authorize the availability of funds for a transaction but delay the capture of funds until a later time. Subsequently, use Create a payment or Create an order to capture the authorized funds, or use Cancel authorization to cancel the authorization. For gateway integrations that support this operation, see Delayed Capture. ### Cancel authorization - [POST /v1/payment-methods/{payment-method-id}/voidAuthorize](https://developer.zuora.com/v1-api-reference/api/payment-authorization/post_cancelauthorization.md): Allows you to cancel an authorization. For gateway integrations that support this operation, see Delayed Capture. ## Payment Gateways 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 Payment Gateways. ### List all payment gateways - [GET /v1/paymentgateways](https://developer.zuora.com/v1-api-reference/api/payment-gateways/get_paymentgateways.md): Retrieves the basic information about all the payment gateways. ### Trigger a pre-debit notification - [POST /v1/payment-gateways/pre-debit-notification](https://developer.zuora.com/v1-api-reference/api/payment-gateways/triggerpredebitnotification.md): To support processing recurring UPI payments through Adyen Integration v2.0, a pre-debit notification for each posted invoice must be sent to the UPI users before collecting the recurring payments. Use this operation to send pre-debit notification requests to the gateway for invoices that meet the requirements. See Implement UPI on Adyen Integration v2.0 for more information. Before using this operation, ensure the following prerequisites are met: - Support for UPI transactions on Adyen has been enabled. This is a feature that can be requested through the Specialized Payment Connections service at an additional cost. - Ensure the conditions for triggering pre-debit notification requests are met. ## Payment Gateway Reconciliation 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/) ### Reverse a payment - [POST /v1/gateway-settlement/payments/{payment-key}/chargeback](https://developer.zuora.com/v1-api-reference/api/payment-gateway-reconciliation/post_reversepayment.md): If the Asynchronous Payment Statuses feature is not enabled, this API operation sets the Gateway State field of the payment to Settled, creates a refund for the amount specified in the request, and returns the Refund object as response. If the Asynchronous Payment Statuses feature is enabled, for ACH and Bank Transfer payments that are reversed before they are settled, this API operation sets the Payment Status field to Processed, sets the Gateway State field of the payment to Settled, creates an external refund for the amount specified in the request, and returns the Refund object as response. If the reason code "Payment Reversal" is active in the Reason Codes list, the reason code of the external refund is set to "Payment Reversal". Otherwise, the default reason code in the list is used. ### Reject a payment - [POST /v1/gateway-settlement/payments/{payment-key}/reject](https://developer.zuora.com/v1-api-reference/api/payment-gateway-reconciliation/post_rejectpayment.md): If the Asynchronous Payment Statuses feature is not enabled, this API operation sets the Gateway State field of the payment to FailedToSettle, creates a refund for the payment amount, and returns the Refund object as response. If the Asynchronous Payment Statuses feature is enabled, for ACH and Bank Transfer payments, this API operation sets the Payment Status field to Error and the Gateway State field to FailedToSettle, and unapply the payment if it is already applied. If the reason code "Payment Rejection" is active in the Reason Codes list, the reason code of the external refund is set to "Payment Rejection". Otherwise, the default reason code in the list is used. ### Settle a payment - [POST /v1/gateway-settlement/payments/{payment-key}/settle](https://developer.zuora.com/v1-api-reference/api/payment-gateway-reconciliation/post_settlepayment.md): If the Asynchronous Payment Statuses feature is not enabled, this API operation sets the Gateway State field of the payment to Settled and returns the Payment object as response. If the Asynchronous Payment Statuses feature is enabled, for ACH and Bank Transfer payments, this API operation sets the Payment Status field to Processed and the Gateway State field to Settled. ### Reconcile a refund - [POST /v1/refunds/{refund-key}/reconcile](https://developer.zuora.com/v1-api-reference/api/payment-gateway-reconciliation/post_reconcilerefund.md): Reconciles a refund when receiving the gateway reconciliation request or event. ## Payments Use payments to process payments, for example, automate recurring payments, manage overpayments, and create refunds. For more information about payments, see Payments. ### List payments - [GET /v1/payments](https://developer.zuora.com/v1-api-reference/api/payments/get_retrieveallpayments.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about all payments from all your customer accounts. ### Filtering You can use query parameters to restrict the data returned in the response. Each query parameter corresponds to one field in the response body. The unappliedAmount or any other query parameter does not support the less than() operators. If the value of a filterable field is string, you can set the corresponding query parameter to null when filtering. Then, you can get the response data with this field value being null. Examples: - /v1/payments?status=Processed - /v1/payments?currency=USD&status=Processed - /v1/payments?status=Processed&type=External&sort=+number ### Create a payment - [POST /v1/payments](https://developer.zuora.com/v1-api-reference/api/payments/post_createpayment.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Creates a payment in the following scenarios: - A full or partial payment on an invoice or a debit memo - A full or partial payment on several invoices and debit memos - An unapplied payment in the following situations: - You do not know which customer account the payment belongs to. - You know which customer account the payment belongs to, but you do not know which invoice the payment is applied to. - You receive a payment from your customer that exceeds the balance on the invoice. - You receive a payment from your customer before the invoice has been created. - You intend to create a payment without any invoices or debit memos. - A standalone payment. If you only need to create and process an electronic payment in Zuora through a Zuora gateway integration but settle the payment outside of Zuora, you can create a standalone payment. For a standalone payment, you can specify a currency different from the payment currency in the customer account settings. When Standalone Payment is not enabled, the currency of the standalone payment can be different from the payment currency defined in the customer account settings if you have the Multiple Currencies feature enabled. If you do not know to which customer account the payment belongs, you can create a payment without specifying a customer account. When you create a payment, the total number of invoice items and debit memo items that the payment will apply to should be less than or equal to 15,000. For more information, see Create Payments and Create Payments Without Specifying Customer Accounts. ### Update a payment - [PUT /v1/payments/{paymentKey}](https://developer.zuora.com/v1-api-reference/api/payments/put_updatepayment.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Updates a payment. ### Delete a payment - [DELETE /v1/payments/{paymentKey}](https://developer.zuora.com/v1-api-reference/api/payments/delete_payment.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Deletes a payment. Only payments with the Cancelled status can be deleted. If you have the Invoice Settlement feature enabled, overpayments applied to credit balance cannot be deleted. ### Retrieve a payment - [GET /v1/payments/{paymentKey}](https://developer.zuora.com/v1-api-reference/api/payments/get_payment.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about one specific payment. ### Apply a payment - [PUT /v1/payments/{paymentKey}/apply](https://developer.zuora.com/v1-api-reference/api/payments/put_applypayment.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Applies an unapplied payment to invoices and debit memos. When you apply a payment, the total number of invoice items and debit memo items that the payment will apply to must be less than or equal to 15,000. If the limit is hit, you can follow the instructions: - If you want to apply one payment to multiple invoices or debit memos, decrease the number of invoices or debit memos in the request. - If you want to apply one payment to a single invoice or debit memo with a large volume of items, you have to specify invoice items in the request. The maximum number of invoice items that you can specify in the request is 1,000. For more information, see Apply Unapplied Payments to Invoices and Debit Memos. ### Cancel a payment - [PUT /v1/payments/{paymentKey}/cancel](https://developer.zuora.com/v1-api-reference/api/payments/put_cancelpayment.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Cancels a payment. If you have the Invoice Settlement feature enabled, overpayments applied to credit balance cannot be cancelled. ### List all parts of a payment - [GET /v1/payments/{paymentKey}/parts](https://developer.zuora.com/v1-api-reference/api/payments/get_paymentparts.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about all parts of a payment. A payment can consist of an unapplied part, and several parts applied to invoices and debit memos. You can use this operation to get all the applied and unapplied portions of a payment. Note that a fully refunded payment does not contain any payment part. ### Retrieve a payment part - [GET /v1/payments/{paymentKey}/parts/{partid}](https://developer.zuora.com/v1-api-reference/api/payments/get_paymentpart.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about a specific payment part. A payment can consist of an unapplied part, and several parts applied to invoices and debit memos. A fully refunded payment does not contain any payment part. ### List all payment part items - [GET /v1/payments/{paymentKey}/parts/{partid}/item-parts](https://developer.zuora.com/v1-api-reference/api/payments/get_paymentitemparts.md): Note: This operation is only available if you have the Invoice Item Settlement feature enabled. Invoice Item Settlement must be used together with other Invoice Settlement features (Unapplied Payments, and Credit and Debit memos). If you wish to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about all items of a payment part. A payment part item is a single line item in a payment part. A payment part can consist of several different types of items. ### Retrieve a payment part item - [GET /v1/payments/{paymentKey}/parts/{partid}/item-parts/{itempartid}](https://developer.zuora.com/v1-api-reference/api/payments/get_paymentitempart.md): Note: This operation is only available if you have the Invoice Item Settlement feature enabled. Invoice Item Settlement must be used together with other Invoice Settlement features (Unapplied Payments, and Credit and Debit memos). If you wish to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about a specific payment part item. A payment part item is a single line item in a payment part. A payment part can consist of several different types of items. ### Refund a payment - [POST /v1/payments/{paymentKey}/refunds](https://developer.zuora.com/v1-api-reference/api/payments/post_refundpayment.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Refunds a full or partial unapplied payment to your customers. To refund applied payments, you must unapply the applied payments from the invoices or debit memos, and then refund the unapplied payments to customers. For more information on the payment refund use case, see Payment schedules use cases in the Knowledge Center. For more information, see Refund Payments. ### Refund a payment with auto-unapplying - [POST /v1/payments/{paymentKey}/refunds/unapply](https://developer.zuora.com/v1-api-reference/api/payments/post_refundpaymentwithautounapply.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Refunds a full or partial unapplied payment to your customers, without the need to unapply the payment first, followed by processing the refund. To refund applied payments, you can now leverage this API to unapply and refund the payment simultaneously. For more information on the payment refund use case, see Payment schedules use cases in the Knowledge Center. For more information, see Refund a payment with auto-unapplying. ### Transfer a payment - [PUT /v1/payments/{paymentKey}/transfer](https://developer.zuora.com/v1-api-reference/api/payments/put_transferpayment.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Transfers an unapplied payment. For more information, see Transfer Unapplied Payments. ### Unapply a payment - [PUT /v1/payments/{paymentKey}/unapply](https://developer.zuora.com/v1-api-reference/api/payments/put_unapplypayment.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Unapplies an applied payment from invoices and debit memos. When you unapply a payment, the total number of invoice items and debit memo items that the payment will unapply from must be less than or equal to 15,000. If the limit is hit, you can follow the instructions: - If you want to unapply one payment without specifying invoices or debit memos, you have to specify the invoices or debit memos in the request. - If you want to unapply one payment from multiple specified invoices or debit memos, decrease the number of invoices or debit memos in the request. - If you want to unapply one payment from a single invoice or debit memo with a large volume of items, you have to specify invoice items in the request. The maximum number of invoice items that you can specify in the request is 1,000. For more information, see Unapply Payments from Invoices and Debit Memos. ## Payment Transaction Logs Use payment transaction logs to export logs of all transactions from Zuora to the Gateway for Payments. ### CRUD: Retrieve a payment transaction log - [GET /v1/object/payment-transaction-log/{id}](https://developer.zuora.com/v1-api-reference/api/payment-transaction-logs/object_getpaymenttransactionlog.md): Retrieves information about a specific payment transaction log. ## Payment Runs Use payment runs to collect payments using electronic payment methods, for example, credit cards and ACH. For more information about payment runs, see Payment Runs. ### List payment runs - [GET /v1/payment-runs](https://developer.zuora.com/v1-api-reference/api/payment-runs/get_paymentruns.md): Retrieves the information about all payment runs. You can define filterable fields to restrict the data returned in the response. ### Filtering You can use query parameters to restrict the data returned in the response. Each query parameter corresponds to one field in the response body. If the value of a filterable field is string, you can set the corresponding query parameter to null when filtering. Then, you can get the response data with this field value being null. Examples: - /v1/payment-runs?status=Processed - /v1/payment-runs?targetDate=2017-10-10&status=Pending - /v1/payment-runs?status=Completed&sort=+updatedDate ### Create a payment run - [POST /v1/payment-runs](https://developer.zuora.com/v1-api-reference/api/payment-runs/post_paymentrun.md): Creates a payment run. You can create a payment run to be executed immediately after it is created, or a scheduled payment run to be executed in future. To filter the payments to be collected for a payment run, you can use either of the following methods but not both: - Use the accountId, batch, billCycleDay, currency, paymentGatewayId, and billingRunId fields to define the billing documents to be collected. - Use the data field to specify the records of accounts and billing documents to be collected, in a more flexible manner. See Create custom payment runs through Zuora REST API for more information. If no filter criteria are specified in the request body, the payment run collects payments for all accounts. ### Delete a payment run - [DELETE /v1/payment-runs/{paymentRunKey}](https://developer.zuora.com/v1-api-reference/api/payment-runs/delete_paymentrun.md): Deletes a payment run. Only payment runs with the Canceled or Error status can be deleted. ### Retrieve a payment run - [GET /v1/payment-runs/{paymentRunKey}](https://developer.zuora.com/v1-api-reference/api/payment-runs/get_paymentrun.md): Retrives the information about a specific payment run. ### Update a payment run - [PUT /v1/payment-runs/{paymentRunKey}](https://developer.zuora.com/v1-api-reference/api/payment-runs/put_paymentrun.md): Updates the information about an unexecuted payment run. Only pending payment runs can be updated. If none of the accountId, batch, billCycleDay, currency, paymentGatewayId, and billingRunId fields is specified in the request body, the corresponding payment run collects payments for all accounts. ### Retrieve payment run data - [GET /v1/payment-runs/{paymentRunKey}/data](https://developer.zuora.com/v1-api-reference/api/payment-runs/get_paymentrundata.md): Retrieves payment run data and the processing result with details, if the data field was specified in the Create payment run operation. ### Retrieve a payment run summary - [GET /v1/payment-runs/{paymentRunKey}/summary](https://developer.zuora.com/v1-api-reference/api/payment-runs/get_paymentrunsummary.md): Retrives the summary of a payment run. ## Payment Schedules 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 Payment Schedules. ### Retry failed payment schedule items - [POST /v1/payment-schedule-items/retry-payment](https://developer.zuora.com/v1-api-reference/api/payment-schedules/post_retrypaymentscheduleitem.md): Retries failed payment schedule items. The payment method and payment gateway of the failed payment can be updated to new values before the retry. Note that you can retry a payment schedule item only when the payment schedule item is either in the Error or Pending status. Note: - To manage and access this feature through the self-service interface, see Manage Features in the Knowledge Center. - This operation is only available if you have Invoice Settlement enabled. ### Cancel a payment schedule item - [PUT /v1/payment-schedule-items/{item-id}/cancel](https://developer.zuora.com/v1-api-reference/api/payment-schedules/put_cancelpaymentscheduleitem.md): Cancels a payment schedule item by ID. Note: - The Payment Schedules feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Manage Features in the Knowledge Center. - This operation is only available if you have Invoice Settlement enabled. ### Skip a payment schedule item - [PUT /v1/payment-schedule-items/{item-id}/skip](https://developer.zuora.com/v1-api-reference/api/payment-schedules/put_skippaymentscheduleitem.md): Skips a payment schedule item by ID. The skipped payment schedule item will turn to the canceled status, and a new item will be scheduled on the next recurring date after the last existing scheduled date. Note: - Only payment schedule items in recurring payment schedules can be skipped, and the item must be in the pending status. - The Payment Schedules feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Manage Features in the Knowledge Center. - This operation is only available if you have Invoice Settlement enabled. ### Retrieve a payment schedule item - [GET /v1/payment-schedule-items/{psi-id}](https://developer.zuora.com/v1-api-reference/api/payment-schedules/get_paymentscheduleitem.md): Retrieves a payment schedule item by ID. Note: - The Payment Schedules feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Manage Features in the Knowledge Center. - This operation is only available if you have Invoice Settlement enabled. ### Update a payment schedule item - [PUT /v1/payment-schedule-items/{psi-id}](https://developer.zuora.com/v1-api-reference/api/payment-schedules/put_paymentscheduleitem.md): Updates a payment schedule item by ID. Note: - The Payment Schedules feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manag](https://knowledgecenter.zuora.com/Zuora_Payments/Payments_Settings/Manage_Features). - This operation is only available if you have Invoice Settlement enabled. - To link or unlink multiple payments with the item, specify the linkPayments and unlinkPayments field in the request body. - When the Multi-currency and Standalone Payments features are not enabled, you can create and update a payment schedule and payment schedule item in a currency other than the account currency. - The maximum number of payments that are allowed to be linked to a payment schedule item is 10. - When unlinking and linking payments with the payment schedule item in one request, Zuora will first unlink the linked payments, and then link new payments to the item. ### Delete a payment schedule item - [DELETE /v1/payment-schedule-items/{psi-id}](https://developer.zuora.com/v1-api-reference/api/payment-schedules/deletepaymentscheduleitem.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Deletes a payment schedule item. You can delete a payment schedule item with the Canceled status. ### List payment schedules by customer account - [GET /v1/payment-schedules](https://developer.zuora.com/v1-api-reference/api/payment-schedules/get_paymentschedules.md): Retrieves payment schedules of a customer account. Note: - The Payment Schedules feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Manage Features in the Knowledge Center. - This operation is only available if you have Invoice Settlement enabled. ### Create a payment schedule - [POST /v1/payment-schedules](https://developer.zuora.com/v1-api-reference/api/payment-schedules/post_paymentschedule.md): Creates a payment schedule. You can create either recurring payment schedules or custom payment schedules. Note: - This operation is only available if you have Invoice Settlement enabled. - You can choose to use payment schedules to process payments associated with billing documents or unapplied payments. If Standalone Payment is enabled, you can also use payment schedules to process standalone payments. - If multiple billing documents are associated to a payment schedule, when collecting the payment schedule item, the payment belongs to the payment schedule item will be applied to billing documents based on the due date of the billing document, in the ascending order. - When the Multi-currency and Standalone Payments features are not enabled, you can create and update a payment schedule and payment schedule item in a currency other than the account currency. - This operation is version controlled. If you set Zuora-Version to 329.0, when creating custom payment schedules associated with billing documents, you need to specify the billing document for each payment schedule item; If Zuora-Version is set to 330.0 or a later available version, when creating custom payment schedules associated with billing documents, you only need to specify the billing documents at the payment schedule level. The default version number is 329.0. However, we recommend that you specify the version to 330.0 or a later version. ### Create multiple payment schedules at once - [POST /v1/payment-schedules/batch](https://developer.zuora.com/v1-api-reference/api/payment-schedules/post_paymentschedules.md): Creates multiple payment schedules at once. You can create both recurring payment schedules and custom payment schedules in one request. The maximum number of payment schedules that can be created by a single request is 50. The maximum number of payment schedule items that each payment schedule can contain is 1000, i.e., you must specify less than 1000 items for a custom payment schedule, and the occurrences field must be less than 1000 for a recurring payment schedule. Note: - This operation is only available if you have Invoice Settlement enabled. - If multiple billing documents are associated to a payment schedule, when collecting the payment schedule item, the payment belongs to the payment schedule item will be applied to billing documents based on the due date of the billing document, in the ascending order. - If Standalone Payment is enabled, you can choose to use payment schedules to process payments associated with billing documents, standalone payments, or unapplied payments. If Standalone Payment is not enabled, you can only use payment schedules to process unapplied payments or payments associated with billing documents. - This operation is version controlled. If you set Zuora-Version to 329.0, when creating custom payment schedules associated with billing documents, you need to specify the billing document for each payment schedule item; If Zuora-Version is set to 330.0, when creating custom payment schedules associated with billing documents, you only need to specify the billing documents at the payment schedule level. The default version number is 329.0. However, we recommend that you specify the version to 330.0. 329.0 will be deprecated soon. ### Retrieve payment schedule statistic of a date - [GET /v1/payment-schedules/statistics/{yyyy-mm-dd}](https://developer.zuora.com/v1-api-reference/api/payment-schedules/get_paymentschedulestatistic.md): Retrieves the payment schedule statistic of a specific date. Note: - The Payment Schedules feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Manage Features in the Knowledge Center. ### Retrieve a payment schedule - [GET /v1/payment-schedules/{paymentScheduleKey}](https://developer.zuora.com/v1-api-reference/api/payment-schedules/get_paymentschedule.md): Retrieves a payment schedule by payment schedule key. Note: - The Payment Schedules feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Manage Features in the Knowledge Center. - This operation is only available if you have Invoice Settlement enabled. ### Update a payment schedule - [PUT /v1/payment-schedules/{paymentScheduleKey}](https://developer.zuora.com/v1-api-reference/api/payment-schedules/put_paymentschedule.md): Updates a payment schedule. For custom payment schedules, only the custom fields on the payment schedules can be udpated. Use the Update a payment schedule item operation to update payment schedule items of custom payment schedule. Note the following rules for the periodStartDate, period, and occurrences: - If periodStartDate is specified, all pending payment schedule items will be rescheduled using this new periodStartDate. If period is changed, we recommend passing in periodStartDate. Otherwise, the system would use the original start date if there is no processed or canceled items, or the last processed or canceled 'scheduleDate + 1 period' as the new periodStartDate. - If only occurrences is updated, the new item will start with the last processed or canceled 'scheduleDate + 1 period'. Note: - The Payment Schedules feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Manage Features in the Knowledge Center. - This operation is only available if you have Invoice Settlement enabled. - When the Multi-currency and Standalone Payments features are not enabled, you can create and update a payment schedule and payment schedule item in a currency other than the account currency. ### Delete a payment schedule - [DELETE /v1/payment-schedules/{paymentScheduleKey}](https://developer.zuora.com/v1-api-reference/api/payment-schedules/deletepaymentschedule.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Deletes a payment schedule. You can delete a payment schedule with the Canceled status. ### Cancel a payment schedule - [PUT /v1/payment-schedules/{paymentScheduleKey}/cancel](https://developer.zuora.com/v1-api-reference/api/payment-schedules/put_cancelpaymentschedule.md): Cancels a payment schedule. Note: - All pending payment schedule items will be canceled, effective from cancelDate. - The Payment Schedules feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Manage Features in the Knowledge Center. - This operation is only available if you have Invoice Settlement enabled. - For more information on the payment schedule cancellation use case, see Payment schedules use cases in the Knowledge Center. ### Add payment schedule items to a custom payment schedule - [POST /v1/payment-schedules/{paymentScheduleKey}/items](https://developer.zuora.com/v1-api-reference/api/payment-schedules/post_additemstocustompaymentschedule.md): Adds payment schedule items to a custom payment schedule. You cannot use this operation to add payment schedule items to recurring payment schedules. Note: - The Payment Schedules feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Manage Features in the Knowledge Center. - This operation is only available if you have Invoice Settlement enabled. - When the Multi-currency and Standalone Payments features are not enabled, you can create and update a payment schedule and payment schedule item in a currency other than the account currency. ### Preview the result of payment schedule updates - [PUT /v1/payment-schedules/{paymentScheduleKey}/preview](https://developer.zuora.com/v1-api-reference/api/payment-schedules/put_paymentscheduleupdatepreview.md): Preview the result of a payment schedule update. This operation only provides a preview. No changes will be made to the database. For custom payment schedules, only the custom fields on the payment schedules can be udpated. Use the Update a payment schedule item operation to update payment schedule items of custom payment schedule. Note the following rules for the periodStartDate, period, and occurrences: - If periodStartDate is specified, all pending payment schedule items will be rescheduled using this new periodStartDate. If period is changed, we recommend passing in periodStartDate. Otherwise, the system would use the original start date if there is no processed or canceled items, or the last processed or canceled 'scheduleDate + 1 period' as the new periodStartDate. - If only occurrences is updated, the new item will start with the last processed or canceled 'scheduleDate + 1 period'. Note: - The Payment Schedules feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. To manage and access this feature through the self-service interface, see Manage Features in the Knowledge Center. ## Refunds 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. ### List refunds - [GET /v1/refunds](https://developer.zuora.com/v1-api-reference/api/refunds/get_refunds.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about all refunds. Two types of refunds are available, electronic refunds and external refunds. ### Filtering You can use query parameters to restrict the data returned in the response. Each query parameter corresponds to one field in the response body. If the value of a filterable field is string, you can set the corresponding query parameter to null when filtering. Then, you can get the response data with this field value being null. Examples: - /v1/refunds?status=Processed - /v1/refunds?amount=4&status=Processed - /v1/refunds?status=Processed&type=External&sort=+number ### Update a refund - [PUT /v1/refunds/{refundKey}](https://developer.zuora.com/v1-api-reference/api/refunds/put_updaterefund.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Updates the basic and finance information about a refund. ### Delete a refund - [DELETE /v1/refunds/{refundKey}](https://developer.zuora.com/v1-api-reference/api/refunds/delete_refund.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Deletes a refund. You can delete a refund with the Canceled status. Note that refunds applied to credit balance cannot be deleted. ### Retrieve a refund - [GET /v1/refunds/{refundKey}](https://developer.zuora.com/v1-api-reference/api/refunds/get_refund.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about a specific refund. ### Cancel a refund - [PUT /v1/refunds/{refundKey}/cancel](https://developer.zuora.com/v1-api-reference/api/refunds/put_cancelrefund.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Cancels a refund. If you have the Invoice Settlement feature enabled, refunds applied to credit balance cannot be cancelled. ### List all parts of a refund - [GET /v1/refunds/{refundKey}/parts](https://developer.zuora.com/v1-api-reference/api/refunds/get_refundparts.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about all parts of a refund. ### Retrieve a refund part - [GET /v1/refunds/{refundKey}/parts/{refundpartid}](https://developer.zuora.com/v1-api-reference/api/refunds/get_refundpart.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about a specific refund part. ### List all refund part items - [GET /v1/refunds/{refundKey}/parts/{refundpartid}/item-parts](https://developer.zuora.com/v1-api-reference/api/refunds/get_refunditemparts.md): Note: This operation is only available if you have the Invoice Item Settlement feature enabled. Invoice Item Settlement must be used together with other Invoice Settlement features (Unapplied Payments, and Credit and Debit memos). If you wish to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about all items of a refund part. A refund part item is a single line item in a refund part. A refund part can consist of several different types of items. ### Retrieve a refund part item - [GET /v1/refunds/{refundKey}/parts/{refundpartid}/item-parts/{itempartid}](https://developer.zuora.com/v1-api-reference/api/refunds/get_refunditempart.md): Note: This operation is only available if you have the Invoice Item Settlement feature enabled. Invoice Item Settlement must be used together with other Invoice Settlement features (Unapplied Payments, and Credit and Debit memos). If you wish to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about a specific refund part item. A refund part item is a single line item in a refund part. A refund part can consist of several different types of items. ## Payment Profiles 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 Payment Profiles. ### Create or update payment profiles in bulk - [PUT /v1/payment-profile](https://developer.zuora.com/v1-api-reference/api/payment-profiles/upsertpaymentprofiles.md): Bulk creates payment profiles or updates payment profiles if they already exist. You can create or update a maximum of 50 payment profiles in a single call. ## Configurable Payment Retry 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). ### List the active retry cycles for an invoice - [GET /api/v1/payments/active_invoice_cycle_information/{invoice_id}](https://developer.zuora.com/v1-api-reference/api/configurable-payment-retry/getactiveinvoicecycle.md): Gets information of active retry cycles that have not been completed for an invoice in Configurable Payment Retry. ### List the active retry cycles for a debit memo - [GET /api/v1/payments/active_debit_memo_cycle_information/{debit_memo_id}](https://developer.zuora.com/v1-api-reference/api/configurable-payment-retry/getactivedebitmemocycle.md): Gets information of active retry cycles that have not been completed for a debit memo in Configurable Payment Retry. ### List the active retry cycles for an account - [GET /api/v1/payments/active_account_cycle_information/{account_id}](https://developer.zuora.com/v1-api-reference/api/configurable-payment-retry/getactiveaccountcycle.md): Gets information of active retry cycles that have not been completed for an account in Configurable Payment Retry. ### List the retry cycle history for an invoice - [GET /api/v1/payments/invoice_cycle_history/{invoice_id}](https://developer.zuora.com/v1-api-reference/api/configurable-payment-retry/getinvoicecyclehistory.md): Gets information of all retry cycles for an invoice in Configurable Payment Retry. ### List the retry cycle history for a debit memo. - [GET /api/v1/payments/debit_memo_cycle_history/{debit_memo_id}](https://developer.zuora.com/v1-api-reference/api/configurable-payment-retry/getdebitmemocyclehistory.md): Gets information of all retry cycles for a debit memo in Configurable Payment Retry. ### List the retry cycle history for an account - [GET /api/v1/payments/account_cycle_history/{account_id}](https://developer.zuora.com/v1-api-reference/api/configurable-payment-retry/getaccountcyclehistory.md): Gets information of all retry cycles for an account in Configurable Payment Retry. ### Execute the invoice payment - [PUT /api/v1/payments/execute_invoice_payment/{invoice_id}](https://developer.zuora.com/v1-api-reference/api/configurable-payment-retry/putexecuteinvoicepayment.md): For all active retry cycles associated with an invoice, schedules the next payment retry attempt to occur in the next hourly payment processor run. ### Execute the debit memo payment - [PUT /api/v1/payments/execute_debit_memo_payment/{debit_memo_id}](https://developer.zuora.com/v1-api-reference/api/configurable-payment-retry/putexecutedebitmemopayment.md): For all active retry cycles associated with a debit memo, schedules the next payment retry attempt to occur in the next hourly payment processor run. ### Execute the account payments - [PUT /api/v1/payments/execute_account_payments/{account_id}](https://developer.zuora.com/v1-api-reference/api/configurable-payment-retry/putexecuteaccountpayments.md): For all active retry cycles associated with an account, schedules the next payment retry attempt to occur in the next hourly payment processor run. ### Execute payments - [POST /api/v1/payments/execute_payments](https://developer.zuora.com/v1-api-reference/api/configurable-payment-retry/postexecutepayments.md): For all active retry cycles associated with the invoice, debit memo, and/or account IDs provided, schedules the next payment retry attempt to occur in the next hourly payment processor run. ### Remove an invoice from retry cycle - [PUT /api/v1/payments/remove_invoice_from_retry_cycle/{invoice_id}](https://developer.zuora.com/v1-api-reference/api/configurable-payment-retry/putremoveinovicefromcycle.md): Stops any active retry cycles associated with the invoice provided. ### Remove a debit memo from retry cycle - [PUT /api/v1/payments/remove_debit_memo_from_retry_cycle/{debit_memo_id}](https://developer.zuora.com/v1-api-reference/api/configurable-payment-retry/putremovedebitmemofromcycle.md): Stops any active retry cycles associated with the debit memo provided. ### Remove an account from retry cycle - [PUT /api/v1/payments/remove_account_from_retry_cycle/{account_id}](https://developer.zuora.com/v1-api-reference/api/configurable-payment-retry/putremoveaccountfromcycle.md): Stops any active retry cycles associated with the account provided. ### Submit a payment to retry cycle - [POST /api/v1/payments/submit_failed_payment](https://developer.zuora.com/v1-api-reference/api/configurable-payment-retry/postsubmitpaymenttocycle.md): This API request submits a failed payment to the Configurable Payment Retry retry cycle. The request adds the failed payment to the existing CPR retry cycle. If no CPR retry cycle exists, this request creates a new one and adds the failed payment. ### List the baseline metrics - [GET /api/v1/metrics/baseline](https://developer.zuora.com/v1-api-reference/api/configurable-payment-retry/getbaselinemetrics.md): Gets baseline metrics for Configurable Payment Retry, including Retry Success Rate and trend, Document Success Rate and trend, and Average Days Outstanding and trend. See Response Schema for detailed descriptions of the metrics. ### List the amount recovered metrics - [GET /api/v1/metrics/amount_recovered](https://developer.zuora.com/v1-api-reference/api/configurable-payment-retry/getamountrecovered.md): Gets the Amount Recovered metrics, including the total amount recovered and the amount recovered over the last 30 days broken down by currency. ### List the document success rate metrics by customer group - [GET /api/v1/metrics/customer_group_over_time](https://developer.zuora.com/v1-api-reference/api/configurable-payment-retry/getdocumentsuccessratebycustomergroup.md): Gets the Document Success Rate timeseries for each customer group over the past 6 months. The data of the current month will not be included. For example, if it is April 15th today, the data for April will not be included. Data for March and earlier will be shown. ### List the customer group metrics - [GET /api/v1/metrics/customer_group](https://developer.zuora.com/v1-api-reference/api/configurable-payment-retry/getcustomergroupmetrics.md): Gets the following metrics for each customer group that is in the active status: - Document Success Rate and trend - Retry Success Rate - Average Attempts ## Object Queries 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. ### List accounts - [GET /object-query/accounts](https://developer.zuora.com/v1-api-reference/api/object-queries/queryaccounts.md): Lists accounts. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve an account - [GET /object-query/accounts/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryaccountbykey.md): Retrieve the details of a specific Account object. ### List amendments - [GET /object-query/amendments](https://developer.zuora.com/v1-api-reference/api/object-queries/queryamendments.md): Lists amendments. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve an amendment - [GET /object-query/amendments/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryamendmentbykey.md): Retrieve the details of a specific Amendment object. ### List bill runs - [GET /object-query/billing-runs](https://developer.zuora.com/v1-api-reference/api/object-queries/querybillingruns.md): Lists bill runs. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a bill run - [GET /object-query/billing-runs/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/querybillingrunbykey.md): Retrieve the details of a specific Bill Run object. ### List contacts - [GET /object-query/contacts](https://developer.zuora.com/v1-api-reference/api/object-queries/querycontacts.md): Lists contacts. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a contact - [GET /object-query/contacts/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/querycontactbykey.md): Retrieve the details of a specific Contact object. ### List credit memos - [GET /object-query/credit-memos](https://developer.zuora.com/v1-api-reference/api/object-queries/querycreditmemos.md): Lists credit memos. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a credit memo - [GET /object-query/credit-memos/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/querycreditmemobykey.md): Retrieve the details of a specific Credit Memo object. ### List credit memo applications - [GET /object-query/credit-memo-applications](https://developer.zuora.com/v1-api-reference/api/object-queries/querycreditmemoapplications.md): Lists credit memo applications. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a credit memo application - [GET /object-query/credit-memo-applications/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/querycreditmemoapplicationbykey.md): Retrieve the details of a specific Credit Memo Application object. ### List credit memo items - [GET /object-query/credit-memo-items](https://developer.zuora.com/v1-api-reference/api/object-queries/querycreditmemoitems.md): Lists credit memo items. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a credit memo item - [GET /object-query/credit-memo-items/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/querycreditmemoitembykey.md): Retrieve the details of a specific Credit Memo Item object. ### List daily consumption summaries - [GET /object-query/daily-consumption-summaries](https://developer.zuora.com/v1-api-reference/api/object-queries/querydailyconsumptionsummaries.md): Lists daily consumption summaries. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a daily consumption summary - [GET /object-query/daily-consumption-summaries/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/querydailyconsumptionsummarybykey.md): Retrieve the details of a specific Daily Consumption Summary object. ### List debit memos - [GET /object-query/debit-memos](https://developer.zuora.com/v1-api-reference/api/object-queries/querydebitmemos.md): Lists debit memos. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a debit memo - [GET /object-query/debit-memos/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/querydebitmemobykey.md): Retrieve the details of a specific Debit Memo object. ### List debit memo items - [GET /object-query/debit-memo-items](https://developer.zuora.com/v1-api-reference/api/object-queries/querydebitmemoitems.md): Lists debit memo items. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a debit memo item - [GET /object-query/debit-memo-items/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/querydebitmemoitembykey.md): Retrieve the details of a specific Debit Memo Item object. ### List delivery adjustments - [GET /object-query/delivery-adjustments](https://developer.zuora.com/v1-api-reference/api/object-queries/querydeliveryadjustments.md): Lists Delivery Adjustment objects. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a delivery adjustment - [GET /object-query/delivery-adjustments/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/querydeliveryadjustmentbykey.md): Retrieves a Delivery Adjustment object. You can use the query parameters to filter, expand, and sort the returned results. ### List fulfillments - [GET /object-query/fulfillments](https://developer.zuora.com/v1-api-reference/api/object-queries/queryfulfillments.md): Lists Fulfillment objects. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a fulfillment - [GET /object-query/fulfillments/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryfulfillmentbykey.md): Retrieves a Fulfillment object. You can use the query parameters to filter, expand, and sort the returned results. ### List invoices - [GET /object-query/invoices](https://developer.zuora.com/v1-api-reference/api/object-queries/queryinvoices.md): Lists invoices. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve an invoice - [GET /object-query/invoices/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryinvoicebykey.md): Retrieve the details of a specific Invoice object. ### List invoice items - [GET /object-query/invoice-items](https://developer.zuora.com/v1-api-reference/api/object-queries/queryinvoiceitems.md): Lists invoice items. You can use the query parameters to filter, expand, and sort the returned results. Note: You must specify a filter[] query parameter to query invoice items. ### Retrieve an invoice item - [GET /object-query/invoice-items/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryinvoiceitembykey.md): Retrieve the details of a specific Invoice Item object. ### List invoice schedules - [GET /object-query/invoice-schedules](https://developer.zuora.com/v1-api-reference/api/object-queries/queryinvoiceschedules.md): Lists invoice schedules. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve an invoice schedule - [GET /object-query/invoice-schedules/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryinvoiceschedulebykey.md): Retrieves the details of a specific Invoice Schedule object. ### List order actions - [GET /object-query/order-actions](https://developer.zuora.com/v1-api-reference/api/object-queries/queryorderactions.md): Lists order actions. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve an order action - [GET /object-query/order-actions/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryorderactionbykey.md): Retrieve the details of a specific Order Action object. ### List order line items - [GET /object-query/order-line-items](https://developer.zuora.com/v1-api-reference/api/object-queries/queryorderlineitems.md): Lists order line items. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve an order line item - [GET /object-query/order-line-items/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryorderlineitembykey.md): Retrieve the details of a specific Order Line Item object. ### List orders - [GET /object-query/orders](https://developer.zuora.com/v1-api-reference/api/object-queries/queryorders.md): Lists orders. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve an order - [GET /object-query/orders/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryordersbykey.md): Retrieve the details of a specific Order object. ### List payments - [GET /object-query/payments](https://developer.zuora.com/v1-api-reference/api/object-queries/querypayments.md): Lists payments. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a payment - [GET /object-query/payments/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/querypaymentbykey.md): Retrieve the details of a specific Payment object. ### List payment applications - [GET /object-query/payment-applications](https://developer.zuora.com/v1-api-reference/api/object-queries/querypaymentapplications.md): Lists payment applications. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a payment application - [GET /object-query/payment-applications/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/querypaymentapplicationbykey.md): Retrieve the details of a specific Payment Application object. ### List payment methods - [GET /object-query/payment-methods](https://developer.zuora.com/v1-api-reference/api/object-queries/querypaymentmethods.md): Lists payment methods. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a payment method - [GET /object-query/payment-methods/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/querypaymentmethodbykey.md): Retrieve the details of a specific Payment Method object. ### List payment method snapshots - [GET /object-query/payment-method-snapshots](https://developer.zuora.com/v1-api-reference/api/object-queries/querypaymentmethodsnapshots.md): Lists payment method snapshots. You can use the query parameters to filter, expand, and sort the returned results. Note: You must specify a filter[] query parameter to query payment method snapshots. ### Retrieve a payment method snapshot - [GET /object-query/payment-method-snapshots/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/querypaymentmethodsnapshotbykey.md): Retrieve the details of a specific Payment Method Snapshot object. ### List payment runs - [GET /object-query/payment-runs](https://developer.zuora.com/v1-api-reference/api/object-queries/querypaymentruns.md): Lists payment runs. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a payment run - [GET /object-query/payment-runs/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/querypaymentrunbykey.md): Retrieve the details of a specific Payment Run object. ### List payment schedules - [GET /object-query/payment-schedules](https://developer.zuora.com/v1-api-reference/api/object-queries/querypaymentschedules.md): Lists payment schedules. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a payment schedule - [GET /object-query/payment-schedules/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/querypaymentschedulebykey.md): Retrieve the details of a specific Payment Schedule object. ### List payment schedule items - [GET /object-query/payment-schedule-items](https://developer.zuora.com/v1-api-reference/api/object-queries/querypaymentscheduleitems.md): Lists Payment Schedule Item objects. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a payment schedule item - [GET /object-query/payment-schedule-items/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/querypaymentscheduleitembykey.md): Retrieve the details of a specific Payment Schedule Item object. ### List prepaid balances - [GET /object-query/prepaid-balances](https://developer.zuora.com/v1-api-reference/api/object-queries/queryprepaidbalances.md): Lists Prepaid Balance objects. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a prepaid balance - [GET /object-query/prepaid-balances/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryprepaidbalancebykey.md): Retrieve the details of a specific Prepaid Balance object. ### List prepaid balance funds - [GET /object-query/prepaid-balance-funds](https://developer.zuora.com/v1-api-reference/api/object-queries/queryprepaidbalancefunds.md): Lists prepaid balance funds. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a prepaid balance fund - [GET /object-query/prepaid-balance-funds/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryprepaidbalancefundbykey.md): Retrieve the details of a specific Prepaid Balance Fund object. ### List prepaid balance transactions - [GET /object-query/prepaid-balance-transactions](https://developer.zuora.com/v1-api-reference/api/object-queries/queryprepaidbalancetransactions.md): Lists prepaid balance transactions. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a prepaid balance transaction - [GET /object-query/prepaid-balance-transactions/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryprepaidbalancetransactionbykey.md): Retrieve the details of a Prepaid Balance Transaction object. ### List processed usage records - [GET /object-query/processed-usages](https://developer.zuora.com/v1-api-reference/api/object-queries/queryprocessedusages.md): Lists Processed Usage Record objects. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a processed usage record - [GET /object-query/processed-usages/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryprocessedusagebykey.md): Retrieve the details of a specific Processed Usage Record object. ### List products - [GET /object-query/products](https://developer.zuora.com/v1-api-reference/api/object-queries/queryproducts.md): Lists Product objects. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a product - [GET /object-query/products/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryproductbykey.md): Retrieve the details of a specific Product object. ### List product rate plans - [GET /object-query/product-rate-plans](https://developer.zuora.com/v1-api-reference/api/object-queries/queryproductrateplans.md): Lists Product Rate Plan objects. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a product rate plan - [GET /object-query/product-rate-plans/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryproductrateplanbykey.md): Retrieve the details of a specific Product Rate Plan object. ### List product rate plan charges - [GET /object-query/product-rate-plan-charges](https://developer.zuora.com/v1-api-reference/api/object-queries/queryproductrateplancharges.md): Lists Product Rate Plan Charge objects. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a product rate plan charge - [GET /object-query/product-rate-plan-charges/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryproductrateplanchargebykey.md): Retrieve the details of a specific Product Rate Plan Charge object. ### List product rate plan charge tiers - [GET /object-query/product-rate-plan-charge-tiers](https://developer.zuora.com/v1-api-reference/api/object-queries/queryproductrateplanchargetiers.md): Lists Product Rate Plan Charge Tier objects. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a product rate plan charge tier - [GET /object-query/product-rate-plan-charge-tiers/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryproductrateplanchargetierbykey.md): Retrieve the details of a specific Product Rate Plan Charge Tier object. ### List ramps - [GET /object-query/ramps](https://developer.zuora.com/v1-api-reference/api/object-queries/queryramps.md): Lists Ramp objects. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a ramp - [GET /object-query/ramps/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryrampbykey.md): Retrieve a Ramp object. You can use the query parameters to filter, expand, and sort the returned results. ### List rate plans - [GET /object-query/rate-plans](https://developer.zuora.com/v1-api-reference/api/object-queries/queryrateplans.md): Lists Rate Plan objects. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a rate plan - [GET /object-query/rate-plans/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryrateplanbykey.md): Retrieve the details of a specific Rate Plan object. ### List rate plan charges - [GET /object-query/rate-plan-charges](https://developer.zuora.com/v1-api-reference/api/object-queries/queryrateplancharges.md): Lists Rate Plan Charge objects. You can use the query parameters to filter, expand, and sort the returned results. Note: You must specify a filter[] query parameter to query rate plan charges. ### Retrieve a rate plan charge - [GET /object-query/rate-plan-charges/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryrateplanchargebykey.md): Retrieve the details of a specific Rate Plan Charge object. ### List rate plan charge tiers - [GET /object-query/rate-plan-charge-tiers](https://developer.zuora.com/v1-api-reference/api/object-queries/queryrateplanchargetiers.md): Lists Rate Plan Charge Tier objects. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a rate plan charge tier - [GET /object-query/rate-plan-charge-tiers/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryrateplanchargetierbykey.md): Retrieve the details of a specific Rate Plan Charge Tier object. ### List rating results - [GET /object-query/rating-results](https://developer.zuora.com/v1-api-reference/api/object-queries/queryratingresults.md): Lists Rating Result objects. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a rating result - [GET /object-query/rating-results/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryratingresultbykey.md): Retrieve the details of a specific Rating Result object. ### List refunds - [GET /object-query/refunds](https://developer.zuora.com/v1-api-reference/api/object-queries/queryrefunds.md): Lists Refund objects. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a refund - [GET /object-query/refunds/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryrefundbykey.md): Retrieve the details of a specific Refund object. ### List refund applications - [GET /object-query/refund-applications](https://developer.zuora.com/v1-api-reference/api/object-queries/queryrefundapplications.md): Lists Refund Application objects. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a refund application - [GET /object-query/refund-applications/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryrefundapplicationbykey.md): Retrieve the details of a specific Refund Application object. ### List refund application items - [GET /object-query/refund-application-items](https://developer.zuora.com/v1-api-reference/api/object-queries/queryrefundapplicationitems.md): Lists Refund Application Item objects. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a refund application item - [GET /object-query/refund-application-items/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryrefundapplicationitembykey.md): Retrieve the details of a specific Refund Application Item object. ### List summary statement runs - [GET /object-query/summarystatementruns](https://developer.zuora.com/v1-api-reference/api/object-queries/getsummarystatementruns.md): Lists statement runs. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a summary statement run - [GET /object-query/summarystatementruns/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/getsummarystatementrun.md): Retrieves a statement run by using the statement run ID or number. ### List summary statements - [GET /object-query/summarystatements](https://developer.zuora.com/v1-api-reference/api/object-queries/getsummarystatements.md): Lists summary statements. ### Retrieve a summary statement - [GET /object-query/summarystatements/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/getsummarystatement.md): Retrieves a statement based on the specified summary statement key. ### List subscriptions - [GET /object-query/subscriptions](https://developer.zuora.com/v1-api-reference/api/object-queries/querysubscriptions.md): Lists Subscription objects. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a subscription - [GET /object-query/subscriptions/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/querysubscriptionbykey.md): Retrieve the details of a specific Subscription object. ### List taxation items - [GET /object-query/taxation-items](https://developer.zuora.com/v1-api-reference/api/object-queries/querytaxationitems.md): Lists Taxation Item objects. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a taxation item - [GET /object-query/taxation-items/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/querytaxationitembykey.md): Retrieve the details of a specific Taxation Item object. ### List usage records - [GET /object-query/usages](https://developer.zuora.com/v1-api-reference/api/object-queries/queryusages.md): Lists Usage Record objects. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a usage record - [GET /object-query/usages/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryusagebykey.md): Retrieve the details of a specific Usage Record object. ### List validity period summaries - [GET /object-query/validity-period-summaries](https://developer.zuora.com/v1-api-reference/api/object-queries/queryvalidityperiodsummarys.md): Lists Validity Period Summary objects. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a validity period summary - [GET /object-query/validity-period-summaries/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryvalidityperiodsummarybykey.md): Retrieve the details of a specific Validity Period Summary object. ### List custom object records - [GET /object-query/{custom-object-name}](https://developer.zuora.com/v1-api-reference/api/object-queries/querycustomobjects.md): Lists custom object records. You can use the query parameters to filter, expand, and sort the returned results. The name of a custom object is in the {namespace}__{objectname}s format, for example, default__cars. Note: Sorting queried custom objects by ID is not supported. ### Retrieve a custom object record - [GET /object-query/{custom-object-name}/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/querycustomobjectbykey.md): Retrieve the details of a specific custom object record. The name of a custom object is in the {namespace}__{objectname}s format, for example, default__cars. ### List contact snapshots - [GET /object-query/contact-snapshots](https://developer.zuora.com/v1-api-reference/api/object-queries/querycontactsnapshots.md): Lists contact snapshots. You can use the query parameters to filter, expand, and sort the returned results. ### Retrieve a contact snapshot - [GET /object-query/contact-snapshots/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/querycontactsnapshotbykey.md): Retrieves detailed information about a specific contact snapshot by its unique ID. ### List rating details - [GET /object-query/rating-details](https://developer.zuora.com/v1-api-reference/api/object-queries/queryratingdetails.md): Lists rating details. Use query parameters to paginate and filter results. ### Retrieve a rating detail - [GET /object-query/rating-details/{key}](https://developer.zuora.com/v1-api-reference/api/object-queries/queryratingdetailbykey.md): Retrieves a single rating detail by ID. ## Accounting Codes 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. ### List all accounting codes - [GET /v1/accounting-codes](https://developer.zuora.com/v1-api-reference/api/accounting-codes/get_allaccountingcodes.md): This reference describes how to query all accounting codes in your chart of accounts through the REST API. ### Create an accounting code - [POST /v1/accounting-codes](https://developer.zuora.com/v1-api-reference/api/accounting-codes/post_accountingcode.md): This reference describes how to create a new accounting code through the REST API. The accounting code will be active as soon as it has been created. ### Prerequisites If you have Zuora Finance enabled on your tenant, you must have the Configure Accounting Codes permission. ### Delete an accounting code - [DELETE /v1/accounting-codes/{ac-id}](https://developer.zuora.com/v1-api-reference/api/accounting-codes/delete_accountingcode.md): This reference describes how to delete an accounting code through the REST API. ### Prerequisites If you have Zuora Finance enabled on your tenant, then you must have the Delete Unused Accounting Code permission. ### Limitations You can only delete accounting codes that have never been associated with any transactions. An accounting code must be deactivated before you can delete it. ### Retrieve an accounting code - [GET /v1/accounting-codes/{ac-id}](https://developer.zuora.com/v1-api-reference/api/accounting-codes/get_accountingcode.md): This reference describes how to query an accounting code through the REST API. ### Update an accounting code - [PUT /v1/accounting-codes/{ac-id}](https://developer.zuora.com/v1-api-reference/api/accounting-codes/put_accountingcode.md): This reference describes how to update an existing accounting code through the REST API. ### Prerequisites If you have Zuora Finance enabled on your tenant, you must have the Manage Accounting Code permission. ### Limitations You can only update accounting codes that are not already associated with any transactions. ### Activate an accounting code - [PUT /v1/accounting-codes/{ac-id}/activate](https://developer.zuora.com/v1-api-reference/api/accounting-codes/put_activateaccountingcode.md): This reference describes how to activate an accounting code through the REST API. Prerequisites ------------- If you have Zuora Finance enabled on your tenant, you must have the Manage Accounting Code permission. ### Deactivate an accounting code - [PUT /v1/accounting-codes/{ac-id}/deactivate](https://developer.zuora.com/v1-api-reference/api/accounting-codes/put_deactivateaccountingcode.md): This reference describes how to deactivate an accounting code through the REST API. ### Prerequisites If you have Zuora Finance enabled on your tenant, you must have the Manage Accounting Code permission. ### Limitations You can only deactivate accounting codes that are not associated with any transactions. You cannot disable accounting codes of type AccountsReceivable. ## Accounting Periods 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. ### List all accounting periods - [GET /v1/accounting-periods](https://developer.zuora.com/v1-api-reference/api/accounting-periods/get_allaccountingperiods.md): Retrieves all accounting periods on your tenant. ### Create an accounting period - [POST /v1/accounting-periods](https://developer.zuora.com/v1-api-reference/api/accounting-periods/post_accountingperiod.md): Creates an accounting period. Prerequisites ------------- * You must have Zuora Finance enabled on your tenant. * You must have the Create Accounting Period user permission. Limitations ----------- * When creating the first accounting period on your tenant, the start date must be equal to or earlier than the date of the earliest transaction on the tenant. * Start and end dates of accounting periods must be contiguous. For example, if one accounting period ends on January 31, the next period must start on February 1. * If you have the Revenue Recognition Package and have enabled the "Monthly recognition over time" revenue recognition model, the accounting period start date and end date must be on the first day and last day of the month, respectively. Note that the start and end dates do not necessarily have to be in the same month. ### Delete an accounting period - [DELETE /v1/accounting-periods/{ap-id}](https://developer.zuora.com/v1-api-reference/api/accounting-periods/delete_accountingperiod.md): Deletes an accounting period. ### Prerequisites * You must have Zuora Finance enabled on your tenant. * You must have the Delete Accounting Period user permission. See Finance Roles. ### Limitations The accounting period to be deleted: * Must be the most recent accounting period. * Must be an open accounting period. * Must have no revenue distributed into it. * Must not have any active journal entries. * Must not be the open-ended accounting period. * Must not be in the process of running a trial balance. ### Retrieve an accounting period - [GET /v1/accounting-periods/{ap-id}](https://developer.zuora.com/v1-api-reference/api/accounting-periods/get_accountingperiod.md): Retrieves an accounting period. Prerequisites: You must have Zuora Finance enabled on your tenant. ### Update an accounting period - [PUT /v1/accounting-periods/{ap-id}](https://developer.zuora.com/v1-api-reference/api/accounting-periods/put_updateaccountingperiod.md): Updates an accounting period. Prerequisites ------------- * You must have Zuora Finance enabled on your tenant. * You must have the Create Accounting Period user permission. See Finance Roles. Limitations ----------- * You can update the start date of only the earliest accounting period on your tenant. You cannot update the start date of later periods. * If you update the earliest accounting period, the start date must be equal to or earlier than the date of the earliest transaction on the tenant. * Start and end dates of accounting periods must be contiguous. For example, if one accounting period ends on January 31, the next period must start on February 1. * If you have the Revenue Recognition Package and have enabled the "Monthly recognition over time" revenue recognition model, the accounting period start date and end date must be on the first day and last day of the month, respectively. Note that the start and end dates do not necessarily have to be in the same month. * You cannot update the start date or end date of an accounting period if: * Any revenue has been distributed into the period. * The period has any active journal entries. ### Close an accounting period - [PUT /v1/accounting-periods/{ap-id}/close](https://developer.zuora.com/v1-api-reference/api/accounting-periods/put_closeaccountingperiod.md): Close an accounting period by accounting period ID. Prerequisites ------------- You must have Zuora Finance enabled on your tenant. You must have the Manage Close Process and Run Trial Balance user permissions. Limitations ----------- * The accounting period cannot already be closed. * The accounting period cannot be in the process of running a trial balance. * All earlier accounting periods must be closed. * There must be no required action items for the accounting period. See Reconcile Transactions Before Closing an Accounting Period for more information. Notes ----- When you close an accounting period in Zuora, a trial balance is automatically run for that period. A successful response means only that the accounting period is now closed, but does not mean that the trial balance has successfully completed. ### Set an accounting period to pending close - [PUT /v1/accounting-periods/{ap-id}/pending-close](https://developer.zuora.com/v1-api-reference/api/accounting-periods/put_pendingcloseaccountingperiod.md): Sets an accounting period to pending close. Prerequisites ------------- * You must have Zuora Finance enabled on your tenant. * You must have the Manage Close Process and Run Trial Balance user permissions. Limitations ----------- * The accounting period cannot be closed or pending close. * The accounting period cannot be in the process of running a trial balance. * All earlier accounting periods must be closed. Notes ----- When you set an accounting period to pending close in Zuora, a trial balance is automatically run for that period. A response of { "success": true } means only that the accounting period status is now pending close, but does not mean that the trial balance has successfully completed. You can use the Get Accounting Period REST API call to view details about the outcome of the trial balance. ### Reopen an accounting period - [PUT /v1/accounting-periods/{ap-id}/reopen](https://developer.zuora.com/v1-api-reference/api/accounting-periods/put_reopenaccountingperiod.md): Re-opens an accounting period. Prerequisites ------------- * You must have Zuora Finance enabled on your tenant. * You must have the Manage Close Process and Run Trial Balance user permissions. Limitations ----------- * The accounting period must be closed or pending close. * You can only re-open an accounting period that is immediately previous to an open period. ### Run trial balance - [PUT /v1/accounting-periods/{ap-id}/run-trial-balance](https://developer.zuora.com/v1-api-reference/api/accounting-periods/put_runtrialbalance.md): Runs the trial balance for an accounting period. Prerequisites ------------- * You must have Zuora Finance enabled on your tenant. * You must have the Manage Close Process and Run Trial Balance user permissions. See Finance Roles. Limitations ----------- * The accounting period must be open. * The accounting period cannot already be in the process of running a trial balance. Notes ----- The trial balance is run asynchronously. A response of { "success": true } means only that the trial balance has started processing, but does not mean that the trial balance has successfully completed. You can use the Get Accounting Period REST API call to view details about the outcome of the trial balance. ## Summary Journal Entries 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 Summary Journal Entries Introduction ### Create a summary journal entry - [POST /v1/journal-entries](https://developer.zuora.com/v1-api-reference/api/summary-journal-entries/post_summaryjournalentry.md): This REST API reference describes how to manually create a summary journal entry. Request and response field descriptions and sample code are provided. ### Requirements 1.The sum of debits must equal the sum of credits in the summary journal entry. 2.The following applies only if you use foreign currency conversion: * If you have configured Aggregate transactions with different currencies during a Journal Run to "Yes", the value of the currency field must be the same as your tenant's home currency. That is, you must create journal entries using your home currency. * All journal entries in an accounting period must either all be aggregated or all be unaggregated. You cannot have a mix of aggregated and unaggregated journal entries in the same accounting period. ### List all summary journal entries in a journal run - [GET /v1/journal-entries/journal-runs/{jr-number}](https://developer.zuora.com/v1-api-reference/api/summary-journal-entries/get_allsummaryjournalentries.md): This REST API reference describes how to retrieve information about all summary journal entries in a journal run. ### Delete a summary journal entry - [DELETE /v1/journal-entries/{je-number}](https://developer.zuora.com/v1-api-reference/api/summary-journal-entries/delete_summaryjournalentry.md): This reference describes how to delete a summary journal entry using the REST API. You must have the "Delete Cancelled Journal Entry" user permission enabled to delete summary journal entries. A summary journal entry must be canceled before it can be deleted. ### Retrieve a summary journal entry - [GET /v1/journal-entries/{je-number}](https://developer.zuora.com/v1-api-reference/api/summary-journal-entries/get_summaryjournalentry.md): This REST API reference describes how to get information about a summary journal entry by its journal entry number. ### Update a summary journal entry - [PUT /v1/journal-entries/{je-number}/basic-information](https://developer.zuora.com/v1-api-reference/api/summary-journal-entries/put_basicsummaryjournalentry.md): This REST API reference describes how to update the basic information of a summary journal entry. Request and response field descriptions and sample code are provided. ### Cancel a summary journal entry - [PUT /v1/journal-entries/{je-number}/cancel](https://developer.zuora.com/v1-api-reference/api/summary-journal-entries/put_summaryjournalentry.md): This reference describes how to cancel a summary journal entry using the REST API. You must have the "Cancel Journal Entry" user permission enabled to cancel summary journal entries. A summary journal entry cannot be canceled if its Transferred to Accounting status is "Yes" or "Processing". ## Journal Runs 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 Journal Runs. ### Create a journal run - [POST /v1/journal-runs](https://developer.zuora.com/v1-api-reference/api/journal-runs/post_journalrun.md): This REST API reference describes how to create a journal run. Request and response field descriptions and sample code are provided. ### Delete a journal run - [DELETE /v1/journal-runs/{jr-number}](https://developer.zuora.com/v1-api-reference/api/journal-runs/delete_journalrun.md): This reference describes how to delete a journal run using the REST API. You can only delete journal runs that have already been canceled. You must have the "Delete Cancelled Journal Run" Zuora Finance user permission enabled to delete journal runs. ### Retrieve a journal run - [GET /v1/journal-runs/{jr-number}](https://developer.zuora.com/v1-api-reference/api/journal-runs/get_journalrun.md): This REST API reference describes how to get information about a journal run. Request and response field descriptions and sample code are provided. ### Cancel a journal run - [PUT /v1/journal-runs/{jr-number}/cancel](https://developer.zuora.com/v1-api-reference/api/journal-runs/put_journalrun.md): This reference describes how to cancel a journal run using the REST API. The summary journal entries in the journal run are canceled asynchronously. See the "Example" section below for details. You must have the "Cancel Journal Run" Zuora Finance user permission enabled to cancel journal runs. ### Notes When you cancel a journal run, the summary journal entries associated with that journal run are canceled asynchronously. A response of { "success": true } means only that the specified journal run has a status of "Pending", "Error", or "Completed" and therefore can be canceled, but does not mean that the whole journal run was successfully canceled. For example, let's say you want to cancel journal run JR-00000075. The journal run status is "Completed" and it contains ten journal entries. One of the journal entries has its Transferred to Accounting status set to "Yes", meaning that the entry cannot be canceled. The workflow might go as follows: 1. You make an API call to cancel the journal run. 2. The journal run status is "Completed", so you receive a response of { "success": true }. 3. Zuora begins asynchronously canceling journal entries associated with the journal run. The journal entry whose Transferred to Accounting status is "Yes" fails to be canceled. The cancelation process continues, and the other journal entries are successfully canceled. 4. The journal run status remains as "Completed". The status does not change to "Canceled" because the journal run still contains a journey entry that is not canceled. ## Mass Updater Use mass updater to perform mass actions more easily. For more information about mass updater, see Mass Updater. ### Perform a mass action - [POST /v1/bulk](https://developer.zuora.com/v1-api-reference/api/mass-updater/post_massupdater.md): Describes how to perform a mass action through the REST API. Using this API method, you send a multipart/form-data request containing a .csv file with data about the mass action you want to perform. Zuora returns a key and then asynchronously processes the mass action. You can use the key to get details about the result of the mass action. If you want to use this operation to perform the Mass Payment Upload (MPU) mass action, see Mass Payment Upload for more information. ### List all results of a mass action - [GET /v1/bulk/{bulk-key}](https://developer.zuora.com/v1-api-reference/api/mass-updater/get_massupdater.md): Describes how to get information about the result of a mass action through the REST API. ### Stop a mass action - [PUT /v1/bulk/{bulk-key}/stop](https://developer.zuora.com/v1-api-reference/api/mass-updater/put_massupdater.md): Describes how to stop a mass action through the REST API. You can stop a mass action when its status is Pending or Processing. After you have stopped a mass action, you can get the mass action result to see details of the mass action. - If you stop a mass action when its status is Pending, no response file is generated because no records have been processed. - If you stop a mass action when its status is Processing, a response file is generated. You can check the response file to see which records have been processed and which have not. In the response file, the Success column has the value Y (successful) or N (failed) for processed records, and a blank value for unprocessed records. Records that have already been processed when a mass action is stopped are not rolled back. ## Notifications 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) ### Create a notification definition - [POST /notifications/notification-definitions](https://developer.zuora.com/v1-api-reference/api/notifications/post_create_notification_definition.md): Creates a notification definition. If a filter rule is specified, it will be evaluated to see if the notification definition is qualified to handle the incoming events during runtime. If the notification is qualified, it will send the email and invoke the callout if it has an email template or a callout. This operation supports creating notification definitions for all event types: - To create a notification definition for a standard event, you must specify the eventCategory field. For more information about standard event category codes, see Standard event category code for events and notifications. - To create a notification definition for a Zuora custom event, custom event, or custom scheduled event, you must specify the eventTypeName field. For more information, see Zuora custom events, Custom event triggers, and Custom scheduled events. You must specify either eventCategory or eventTypeName, but not both at the same time. ### List notification definitions - [GET /notifications/notification-definitions](https://developer.zuora.com/v1-api-reference/api/notifications/get_query_notification_definitions.md): Queries notification definitions with the specified filters. ### Retrieve a notification definition - [GET /notifications/notification-definitions/{id}](https://developer.zuora.com/v1-api-reference/api/notifications/get_get_notification_definition.md): Queries the notification definition of the given ID. ### Update a notification definition - [PUT /notifications/notification-definitions/{id}](https://developer.zuora.com/v1-api-reference/api/notifications/put_update_notification_definition.md): Updates a notification definition. ### Delete a notification definition - [DELETE /notifications/notification-definitions/{id}](https://developer.zuora.com/v1-api-reference/api/notifications/delete_delete_notification_definition.md): Deletes a notification definition. ### Create or update email templates - [POST /notifications/email-templates/import](https://developer.zuora.com/v1-api-reference/api/notifications/post_createorupdateemailtemplates.md): Creates email templates for standard or custom events if you do not specify email template IDs, or updates existing email templates if you specify valid email template IDs. For each email template when you are creating email templates, whether the template is created for a standard event, a custom event, or a custom scheduled event is dependent on whether you specify the eventCategory or eventTypeName field. - If you specify the eventCategory field, the email template is created based on a standard event. See Standard Event Categories for all standard event category codes. - If you specify the eventTypeName field, the email template is created based on the corresponding custom event or custom scheduled event. See Custom event triggers for more information about custom events, and Custom scheduled events for more information about custom scheduled events. The maximum number of email templates that you can create or update by one call is 1,000. ### Create an email template - [POST /notifications/email-templates](https://developer.zuora.com/v1-api-reference/api/notifications/post_create_email_template.md): Creates an email template. This operation supports creating the email template for all event types. - If you specify the eventCategory field, the email template is created based on a standard event. See Standard Event Categories for all standard event category codes. - If you specify the eventTypeName field, the email template is created based on the corresponding custom event or custom scheduled event. See Custom event triggers for more information about custom events, and Custom scheduled events for more information about custom scheduled events. ### List email templates - [GET /notifications/email-templates](https://developer.zuora.com/v1-api-reference/api/notifications/get_query_email_templates.md): Queries email templates. This operation supports querying email templates for all event types. ### Retrieve an email template - [GET /notifications/email-templates/{id}](https://developer.zuora.com/v1-api-reference/api/notifications/get_get_email_template.md): Queries the email template based on the specified ID. This operation supports retrieving the email template for all event types. ### Update an email template - [PUT /notifications/email-templates/{id}](https://developer.zuora.com/v1-api-reference/api/notifications/put_update_email_template.md): Updates an email template. This operation supports updating the email template for all event types. ### Delete an email template - [DELETE /notifications/email-templates/{id}](https://developer.zuora.com/v1-api-reference/api/notifications/delete_delete_email_template.md): Deletes an email template. This operation supports deleting an email template for all event types. ### Create or update callout templates - [POST /notifications/callout-templates/import](https://developer.zuora.com/v1-api-reference/api/notifications/createorupdatecallouttemplates.md): Creates callout templates for standard or custom events if you do not specify callout template IDs, or updates existing callout templates if you specify valid callout template IDs. For each callout template when you are creating callout templates, whether the template is created for a standard event, a custom event, or a custom scheduled event is dependent on whether you specify the eventCategory or eventTypeName field. - If you specify the eventCategory field, the callout template is created based on a standard event. See Standard event category code for events and notifications for all standard event category codes. - If you specify the eventTypeName field, the callout template is created based on the corresponding custom event, Zuora custom event, or custom scheduled event. See Custom event triggers for more information about custom events, and Custom scheduled events for more information about custom scheduled events. The maximum number of callout templates that you can create or update by one call is 1,000. ### Create a callout template - [POST /notifications/callout-templates](https://developer.zuora.com/v1-api-reference/api/notifications/createcallouttemplate.md): Creates a callout template. This operation supports creating the callout template for all event types: - To create a callout template for a standard event, you must specify the eventCategory field. For more information about standard event category codes, see Standard event category code for events and notifications. - To create a callout template for a Zuora custom event, custom event, or custom scheduled event, you must specify the eventTypeName field. For more information, see Zuora custom events, Custom event triggers, and Custom scheduled events. You must specify either eventCategory or eventTypeName, but not both at the same time. ### List callout templates - [GET /notifications/callout-templates](https://developer.zuora.com/v1-api-reference/api/notifications/getcallouttemplates.md): Queries callout templates. This operation supports querying callout templates for all event types. ### Retrieve a callout template - [GET /notifications/callout-templates/{id}](https://developer.zuora.com/v1-api-reference/api/notifications/getcallouttemplte.md): Queries the callout template based on the specified ID. This operation supports retrieving the callout template for all event types. ### Update a callout template - [PUT /notifications/callout-templates/{id}](https://developer.zuora.com/v1-api-reference/api/notifications/updatecallouttemplate.md): Updates a callout template. This operation supports updating the callout template for all event types. ### Delete a callout template - [DELETE /notifications/callout-templates/{id}](https://developer.zuora.com/v1-api-reference/api/notifications/deletecallouttemplate.md): Deletes a callout template. This operation supports deleting a callout template for all event types. ### Create or update reusable blocks - [POST /notifications/reusable-blocks/import](https://developer.zuora.com/v1-api-reference/api/notifications/createorupdatereusableblocks.md): Creates reusable blocks if you do not specify block IDs, or updates existing reusable blocks if you specify valid block IDs. All fields must be provided for each reusable block you want to update. The maximum number of reusable blocks that you can create or update by one call is 1,000. ### Create a reusable block - [POST /notifications/reusable-blocks](https://developer.zuora.com/v1-api-reference/api/notifications/createreusableblock.md): Creates a reusable block for email templates, such as email headers or footers. ### List reusable blocks - [GET /notifications/reusable-blocks](https://developer.zuora.com/v1-api-reference/api/notifications/getreusableblocks.md): Queries reusable blocks. ### Retrieve a reusable block - [GET /notifications/reusable-blocks/{blockKey}](https://developer.zuora.com/v1-api-reference/api/notifications/getreusableblock.md): Queries the reusable block based on the specified ID or name. ### Update a reusable block - [PUT /notifications/reusable-blocks/{blockKey}](https://developer.zuora.com/v1-api-reference/api/notifications/updatereusableblock.md): Updates a reusable block. ### Delete a reusable block - [DELETE /notifications/reusable-blocks/{blockKey}](https://developer.zuora.com/v1-api-reference/api/notifications/deletereusableblock.md): Deletes a reusable block. ### Delete notification histories for an account - [DELETE /notifications/history](https://developer.zuora.com/v1-api-reference/api/notifications/delete_delete_notification_history_for_account.md): Delete all notification histories for the given account. All email and callout notifications for this account will be deleted upon successful operation. ### Retrieve a notification history deletion task - [GET /notifications/history/tasks/{id}](https://developer.zuora.com/v1-api-reference/api/notifications/get_get_notification_history_deletion_task.md): Get the notification history deletion task by ID. ### Resend callout notifications - [POST /notifications/callout-histories/resend](https://developer.zuora.com/v1-api-reference/api/notifications/post_resendcalloutnotifications.md): Resends callout notifications if your customers did not receive previous callout notifications. Details about the status codes and response contents of this operation are as follows: | Scenario | Status code | Response content | |----------------------------------------|-----------------|-------------------------------------------------------------| | Success for all notifications | 202 Accepted | (blank) | | Success for at least one notification | 202 Accepted | Error code and error message of each failed notification | | Failure for all notifications | 400 Bad Request | Error code and error message of each failed notification | ### Resend email notifications - [POST /notifications/email-histories/resend](https://developer.zuora.com/v1-api-reference/api/notifications/post_resendemailnotifications.md): Resends email notifications if your customers did not receive previous email notifications. Details about the status codes and response contents of this operation are as follows: | Scenario | Status code | Response content | |----------------------------------------|-----------------|-------------------------------------------------------------| | Success for all notifications | 202 Accepted | (blank) | | Success for at least one notification | 202 Accepted | Error code and error message of each failed notification | | Failure for all notifications | 400 Bad Request | Error code and error message of each failed notification | ### List callout notification histories - [GET /v1/notification-history/callout](https://developer.zuora.com/v1-api-reference/api/notifications/get_callouthistory.md): Describes how to get a notification history for callouts. ### List email notification histories - [GET /v1/notification-history/email](https://developer.zuora.com/v1-api-reference/api/notifications/get_emailhistory.md): Describes how to get a notification history for notification emails. ### Notes Request parameters and their values may be appended with a "?" following the HTTPS GET request. Additional request parameter are separated by "&". For example: GET https://rest.zuora.com/v1/notification-history/email?startTime=2015-01-12T00:00:00&endTime=2015-01-15T00:00:00&failedOnly=false&eventCategory=1000&pageSize=1 ## Custom Event Triggers 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. ### Create an event trigger - [POST /events/event-triggers](https://developer.zuora.com/v1-api-reference/api/custom-event-triggers/post_eventtrigger.md): When you create an event trigger, you must specify the base object and define the trigger condition. ### Specify the base object Use baseObject field to specify which object to define a trigger on. You can define an event trigger on any of the following objects: * Account * AccountingCode * AccountingPeriod * Amendment * BillingRun * Contact * CreditBalanceAdjustment * CreditMemo * CreditMemoApplication * CreditMemoApplicationItem * CreditMemoItem * CreditMemoPart * DebitMemo * DebitMemoItem * DeliveryAdjustment * Feature * Fulfillment * Fund * Invoice * InvoiceAdjustment * InvoiceItem * InvoiceItemAdjustment * JournalEntry * JournalEntryItem * Order * OrderAction * OrderLineItem * Payment * PaymentApplication * PaymentMethod * PaymentPart * PaymentSchedule * PaymentScheduleItem * Product * ProductFeature * ProductRatePlan * ProductRatePlanCharge * ProductRatePlanChargeTier * RatePlan * RatePlanCharge * RatePlanChargeTier * RatingResult * Refund * RefundApplication * RefundPart * RevenueEvent * RevenueEventItem * RevenueSchedule * RevenueScheduleItem * Subscription * SubscriptionChargeDeliverySchedule * SubscriptionChargePriceInterval * SubscriptionChargePriceIntervalTier * SubscriptionOffer * SubscriptionProductFeature * TaxationItem * UpdaterDetail * Usage * ValidityPeriodSummary In addition to the above Zuora standard objects, you can also use custom objects as base objects for custom events. #### Tenant level base objects and tenant level event triggers Zuora identifies the following base objects and custom objects as the tenant level base objects: * AccountingCode * AccountingPeriod * BillingRun * Feature * JournalEntry * JournalEntryItem * Product * ProductFeature * ProductRatePlan * ProductRatePlanCharge * ProductRatePlanChargeTier Event triggers defined on tenant level base objects are tenant level event triggers. Notifications associated with tenant level events are system notifications. Note: Tenant level event triggers and system notifications are only available in the default profile. ### Define the trigger condition The condition field is a JEXL expression that specifies when to trigger events. The expression can contain fields from the object that the trigger is defined on. Note: The condition cannot contain fields from data source objects that are joined to the object that the trigger is defined on. For example, the following condition causes an event to be triggered whenever an invoice is posted with an amount greater than 1000: changeType == 'UPDATE' && Invoice.Status == 'Posted' && Invoice.Status_old != 'Posted' && Invoice.Amount > 1000.0 Where: * changeType is a keyword that specifies the type of change that occurred to the Invoice object. For all objects, the supported values of changeType are INSERT, UPDATE, and DELETE. * Invoice.Status is the value of the Invoice object's Status field after the change occurred. * Invoice.Status_old is the value of the Invoice object's Status field before the change occurred. In the above example, the value of baseObject is Invoice. #### Limitations This event trigger has the following limitations: * Base object values for Zuora standard objects are case sensitive. For example, PaymentMethod is correct, and Paymentmethod or paymentmethod is incorrect. * Base object values for custom objects must be lowercase. For example, default__vehicle. * The INSERT change type is not supported on RatePlan base objects. * The INSERT change type is not supported on SubscriptionProductFeature base objects. * When creating custom events, you cannot match fields of the RatePlanCharge object against constant values for the condition field. For example, the following condition will cause errors: RatePlanCharge.ShippingProcessStatus__c == 'Shipping Confirmed', where Shipping Confirmed is a constant value. * Fields on objects are case-sensitive. For example, PaymentMethod.createdbyid can result in errors. The correct format is PaymentMethod.CreatedById. * A condition cannot contain fields from data source objects that are joined to the base object. * Do not create duplicate events because they will be either merged or deleted. Zuora considers events that have the same trigger condition as duplicate events, regardless of event type names. See Custom Events for more information. ### List event triggers - [GET /events/event-triggers](https://developer.zuora.com/v1-api-reference/api/custom-event-triggers/get_eventtriggers.md) ### Retrieve an event trigger - [GET /events/event-triggers/{id}](https://developer.zuora.com/v1-api-reference/api/custom-event-triggers/get_eventtrigger.md) ### Update an event trigger - [PUT /events/event-triggers/{id}](https://developer.zuora.com/v1-api-reference/api/custom-event-triggers/put_eventtrigger.md) ### Delete an event trigger - [DELETE /events/event-triggers/{id}](https://developer.zuora.com/v1-api-reference/api/custom-event-triggers/delete_eventtrigger.md) ## Custom Scheduled Events 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 Custom Scheduled Events. ### Create a scheduled event - [POST /events/scheduled-events](https://developer.zuora.com/v1-api-reference/api/custom-scheduled-events/post_scheduledevent.md): To create a custom scheduled event, you must specify the base object, the base field and the scheduled time. ### List all scheduled events - [GET /events/scheduled-events](https://developer.zuora.com/v1-api-reference/api/custom-scheduled-events/get_scheduledevents.md) ### Retrieve a scheduled event by ID - [GET /events/scheduled-events/{id}](https://developer.zuora.com/v1-api-reference/api/custom-scheduled-events/get_scheduledeventbyid.md) ### Update a scheduled event by ID - [PUT /events/scheduled-events/{id}](https://developer.zuora.com/v1-api-reference/api/custom-scheduled-events/update_scheduledeventbyid.md) ### Delete a scheduled event by ID - [DELETE /events/scheduled-events/{id}](https://developer.zuora.com/v1-api-reference/api/custom-scheduled-events/delete_scheduledeventbyid.md) ## Custom Object Definitions 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 Custom Objects API error code for details. ### Create custom object definitions - [POST /objects/definitions/default](https://developer.zuora.com/v1-api-reference/api/custom-object-definitions/post_customobjectdefinitions.md): You can post custom object definitions with the request body schema described below. This operation also allows you to use the List custom object definitions response schema as its request schema. If you want to copy all the existing custom objects from an old tenant to a new tenant, you can make a List custom object definitions call in your old tenant and then use its response directly as the request of this operation in the new tenant to import all the custom objects from the old tenant. The label field is the UI label of the custom object. The object field contains the API Name of the custom object. ### Limitations This custom object definition has the following limitations: * The maximum number of characters for the Custom Object API Name (object) is 64. * The maximum number of characters for the Custom Object Label (label) is 64. * The maximum number of characters for the Custom Object Description 250. * The maximum number of custom fields in an custom object is 50. * The maximum number of characters for the custom field API name is 64. * The maximum number of characters for the custom field label (label) is 64. * The maximum number of characters for the custom field Description is 250. * The maximum number of picklist or multiselect options is 250. * The maximum length of characters for the Text field is 255. * The maximum length of characters for the Long Text field is from 256 to 8,192. * The maximum number of digits to the left of the decimal point for the Number field is 13, and to the right is 9. ### List custom object definitions - [GET /objects/definitions/default](https://developer.zuora.com/v1-api-reference/api/custom-object-definitions/get_allcustomobjectdefinitionsinnamespace.md): Get all custom objects definitions for a given tenant. If you want to copy all the existing custom objects from an old tenant to a new tenant, you can call this operation in your old tenant and then use its response directly as the request of the Create custom object definitions call in the new tenant to import all the custom objects from the old tenant. ### Update a custom object definition - [POST /objects/migrations](https://developer.zuora.com/v1-api-reference/api/custom-object-definitions/post_updatecustomobjectdefinition.md): Updates a custom object definition by posting migration resource to initiate the migration of definitions. ### Limitations Updating custom field definition has the following limitations: * You can only have one action per update request. * You cannot delete fields from custom objects that contain records. * You can only add required fields to custom objects with no records. * You can change optional fields to required only on the custom objects with no records. ### Note The bulk deletion of custom fields on standard and custom objects is temporarily unavailable as we refine the Custom Field feature. You can still delete custom fields individually during this refinement process. If you want to delete multiple custom fields, ensure that you send each deletion request only after receiving the response for the previous request. The bulk deletion capability will be restored once the refinement is complete. ### Retrieve a custom object definition - [GET /objects/definitions/default/{object}](https://developer.zuora.com/v1-api-reference/api/custom-object-definitions/get_customobjectdefinitionbytype.md): Retrieves the custom object definition by type for the given tenant. ### Delete a custom object definition - [DELETE /objects/definitions/default/{object}](https://developer.zuora.com/v1-api-reference/api/custom-object-definitions/delete_customobjectdefinitionbytype.md): Deletes the custom object definition for the provided type. Note: A custom object definition can only be deleted if no record of this custom object type exists. ## Custom Object Records 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 Custom Objects API error code for details. ### Create custom object records - [POST /objects/records/default/{object}](https://developer.zuora.com/v1-api-reference/api/custom-object-records/post_customobjectrecords.md): Creates custom object records with the given type. Upon creating records of a custom object type, the 200 response contains a list of records that have been successfully processed and stored. ### Limitations This call has the following limitations: * The maximum number of records that you can create by one call is 1,000. * The storage of empty strings in records is not supported. * Null values must be formatted as the following example: { "records": [ { "fieldName__c": null } ] } * When creating or updating custom object records with relationship-type fields, Zuora verifies the related objects against the transactional databases, which are updated in near real-time. The record creation or modification fails upon unsuccessful verifications. If the related objects are newly created in your tenant, it might need some time for the transactional database synchronization. ### List records for a custom object - [GET /objects/records/default/{object}](https://developer.zuora.com/v1-api-reference/api/custom-object-records/get_allrecordsforcustomobjecttype.md): Lists all object records of the given type. You can also use the q query parameter to filter the output records. ### Custom Objects read consistency Custom Objects support eventually consistency. When you read custom object records, the response might not reflect the result of a recently completed operation and might include some stale data. The operations include creating, updating, and deleting custom object records. If you repeat your read request after a short time, the response should return the latest data. For example, if you create five records and perform a query that these five records satisfy the query conditions, there might be a delay before these records can be returned in the query result. ### Retrieve a custom object record - [GET /objects/records/default/{object}/{id}](https://developer.zuora.com/v1-api-reference/api/custom-object-records/get_customobjectrecordbyid.md): Retrieves a record of a given type by ID. ### Update a custom object record - [PUT /objects/records/default/{object}/{id}](https://developer.zuora.com/v1-api-reference/api/custom-object-records/put_customobjectrecord.md): Updates a record of the given type and ID. ### Limitations * The storage of empty strings in records is not supported. * Null values must be formatted as the following example: { "records": [ { "fieldName__c": null } ] } * When creating or updating custom object records with relationship-type fields, Zuora verifies the related objects against the transactional databases, which are updated in near real-time. The record creation or modification fails upon unsuccessful verifications. If the related objects are newly created in your tenant, it might need some time for the transactional database synchronization. ### Partially update a custom object record - [PATCH /objects/records/default/{object}/{id}](https://developer.zuora.com/v1-api-reference/api/custom-object-records/patch_partialupdatecustomobjectrecord.md): Updates one or many fields of a custom object record. Patch update uses JSON Merge Patch as specified in RFC 7386. ### Limitations * The storage of empty strings in records is not supported. * Null values must be formatted as the following example: { "records": [ { "fieldName__c": null } ] } * When creating or updating custom object records with relationship-type fields, Zuora verifies the related objects against the transactional databases, which are updated in near real-time. The record creation or modification fails upon unsuccessful verifications. If the related objects are newly created in your tenant, it might need some time for the transactional database synchronization. ### Delete a custom object record - [DELETE /objects/records/default/{object}/{id}](https://developer.zuora.com/v1-api-reference/api/custom-object-records/delete_customobjectrecordbyid.md): Deletes a custom object record of the given type and ID. Note that 200 response will be returned under either of the following conditions: * The record is identified and successfully deleted * The record could not be found Note that the record is deleted immediately and, therefore, will not be retained upon successful deletion. ### Update or delete custom object records - [POST /objects/batch/default/{object}](https://developer.zuora.com/v1-api-reference/api/custom-object-records/post_customobjectrecordsbatchupdateordelete.md): Makes a batch update or delete of custom object records. ### Limitations This call has the following limitations: * The maximum number of records that you can update by one call is 1,000. * The maximum number of records that you can delete by one call is 1,000. * The storage of empty strings in records is not supported. * Null values must be formatted as the following example: { "action": { "type": "update", "records": { "64edb2a5-2796-4e95-9559-846f8636a01b": { "fieldName__c": null } } } } * When creating or updating custom object records with relationship-type fields, Zuora verifies the related objects against the transactional databases, which are updated in near real-time. The record creation or modification fails upon unsuccessful verifications. If the related objects are newly created in your tenant, it might need some time for the transactional database synchronization. ## Custom Object Jobs 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 Custom Objects API error code for details. ### Submit a custom object bulk job - [POST /objects/jobs](https://developer.zuora.com/v1-api-reference/api/custom-object-jobs/post_customobjectbulkjob.md): Submits a bulk job request for a bulk operation on the specified custom object records. A succcessful call returns a newly created bulk job. The job ID can be used to poll the job status or upload the CSV file if it is a create or update job. ### Limits This custom object bulk jobs have the following limits: * The concurrent bulk job limit per tenant is 5. Bulk jobs in accepted, pending, or in_progress status are counted towards the concurrent bulk job limit. * The bulk job execuation order is not guaranteed, which means the bulk job that you submit ealier may be executed later. * Only the users that have the "Delete Custom Objects" permission can create a delete bulk job. Only the users that have the "Edit Custom Objects" permission can create a create or update bulk job. See Platform Permissions for more information. ### List all custom object bulk jobs - [GET /objects/jobs](https://developer.zuora.com/v1-api-reference/api/custom-object-jobs/get_allcustomobjectbulkjobs.md): Lists all custom object bulk jobs submitted by your tenant. ### Retrieve a custom object bulk job - [GET /objects/jobs/{id}](https://developer.zuora.com/v1-api-reference/api/custom-object-jobs/get_customobjectbulkjob.md): Retrieves the custom object bulk job details by job ID. Only the users that have the "View Custom Objects" permission can retrieve custom object bulk jobs. See Platform Permissions for more information. ### Upload a file for a custom object bulk job - [POST /objects/jobs/{id}/files](https://developer.zuora.com/v1-api-reference/api/custom-object-jobs/post_uploadfileforcustomobjectbulkjob.md): Uploads a .csv file for a custom object bulk job to create or update custom object records. The job must be in pending status. Only one file is allowed per job. Each file supports only one type of operation, with an id column required for update operations. The job will start once the upload is finished. Only the users that have the "Edit Custom Objects" permission can upload files to custom object bulk jobs. See Platform Permissions for more information. ### List all errors for a custom object bulk job - [GET /objects/jobs/{id}/errors](https://developer.zuora.com/v1-api-reference/api/custom-object-jobs/get_customobjectbulkjoberrors.md): Lists all errors for a custom object bulk job. ### Cancel a custom object bulk job - [PATCH /objects/jobs/{id}/cancel](https://developer.zuora.com/v1-api-reference/api/custom-object-jobs/patch_customobjectbulkjob.md): Cancel a custom object bulk job. Note that you can cancel a custom object bulk job only if the job status is accepted or pending. ## API Health 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 APIs dashboard. ### List API volume summary records - [GET /system-health/api-requests/volume-summary](https://developer.zuora.com/v1-api-reference/api/api-health/get_systemhealthapivolumesummary.md): Returns volume summary of API usage that generated by your Zuora tenant within a specified time range. You can filter the summary by API path name and http method. ### List API failure records - [GET /system-health/api-requests/failures](https://developer.zuora.com/v1-api-reference/api/api-health/getsystemhealthapifailurerecords.md): Returns failure records of API usage that are generated by your Zuora tenant within a specified time range. You can filter the failure records by one or multiple of the following fields: - API path name - HTTP method - Response code - Request ID - Track ID ### List API usage detail records - [GET /system-health/api-requests/details](https://developer.zuora.com/v1-api-reference/api/api-health/getsystemhealthapiperformancerecords.md): Returns records of API usage that are generated by your Zuora tenant within a specified time range. You can filter the records by one or multiple of the following fields: - API path name - HTTP method - Response code - Request ID - Track ID ## Bill Run Health 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 Bill Run dashboard. ### List billing document volume summary records - [GET /system-health/billing-documents/volume-summary](https://developer.zuora.com/v1-api-reference/api/bill-run-health/get_systemhealthbillingdocvolumesummary.md): Returns a summary of billing documents generated within a specified time range, including invoices and credit memos, and the total number of accounts that failed to process. ## Electronic Payments Health 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 Electronic Payments dashboard. ### List payment volume summary records - [GET /system-health/payments/volume-summary](https://developer.zuora.com/v1-api-reference/api/electronic-payments-health/get_systemhealthpaymentvolumesummary.md): Returns a summary of electronic payments handled by your Zuora tenant within a specified time range. You can filter the summary by payment gateway type and payment method type. ### List payment system health records - [GET /system-health/payments/details](https://developer.zuora.com/v1-api-reference/api/electronic-payments-health/getsystemhealthpaymentrecords.md): Returns System Health Electronic Payments records that are generated by your Zuora tenant within a specified time range. You can filter the failure records by one or multiple of the following fields: - payment gateway type - payment method type - payment status - payment gateway response code - currency ## Tax 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 Tax Health Dashboard. ### List tax system health records - [GET /system-health/tax/details](https://developer.zuora.com/v1-api-reference/api/tax-health/getsystemhealthtaxrecords.md): Returns System Health Electronic records that are generated by your Zuora tenant within a specified time range. You can filter the failure records by one or multiple of the following fields: - vendorName - eventType - status ## Workflows 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 Workflow. ### Delete a workflow version - [DELETE /workflows/versions/{version_id}](https://developer.zuora.com/v1-api-reference/api/workflows/delete_workflowversion.md): Delete a workflow version based on the version id. ### User Access Permission You must be assigned the Workflow Manage Access permission to run this operation. ### List workflows - [GET /workflows](https://developer.zuora.com/v1-api-reference/api/workflows/get_workflows.md): Retrieves a list of workflow definitions available in your Zuora tenant. ### User Access Permission You must be assigned the Workflow View Access permission to run this operation. ### Import a workflow - [POST /workflows/import](https://developer.zuora.com/v1-api-reference/api/workflows/post_workflowimport.md): Create a new workflow definition and its first version using the exported JSON document of an existing workflow version. ### User Access Permission You must be assigned the Workflow Manage Access permission to run this operation. ### Retrieve workflow task usage - [GET /workflows/metrics.json](https://developer.zuora.com/v1-api-reference/api/workflows/get_workflowsusages.md): Gets workflow task usage sorted by day within a specified time frame. ### User Access Permission You must be assigned the Workflow View Access permission to run this operation. ### List workflow tasks - [GET /workflows/tasks](https://developer.zuora.com/v1-api-reference/api/workflows/get_workflowstasks.md): Retrieves a list of workflow tasks available in your Zuora tenant. ### User Access Permission You must be assigned the Workflow View Access permission to run this operation. ### Update workflow tasks - [PUT /workflows/tasks/batch_update](https://developer.zuora.com/v1-api-reference/api/workflows/put_workflowstasksupdate.md): Updates a group of workflow tasks. ### User Access Permission You must be assigned the Workflow Manage Access permission to run this operation. ### Retrieve a workflow task - [GET /workflows/tasks/{task_id}](https://developer.zuora.com/v1-api-reference/api/workflows/get_workflowstask.md): Retrieves a specific workflow task by its ID. ### User Access Permission You must be assigned the Workflow View Access permission to run this operation. ### Rerun a workflow task - [POST /workflows/tasks/{task_id}/rerun](https://developer.zuora.com/v1-api-reference/api/workflows/post_workflowstaskrerun.md): Reruns a specific workflow task by its ID. ### User Access Permission You must be assigned the Workflow Run Access permission to run this operation. ### Retrieve a workflow run - [GET /workflows/workflow_runs/{workflow_run_id}](https://developer.zuora.com/v1-api-reference/api/workflows/get_workflow_run.md): Retrieves information about a specific workflow run by its ID. ### User Access Permission You must be assigned the Workflow View Access permission to run this operation. ### Delete a workflow - [DELETE /workflows/{workflow_id}](https://developer.zuora.com/v1-api-reference/api/workflows/delete_workflow.md): Deletes a specific workflow by its ID. ### User Access Permission You must be assigned the Workflow Manage Access permission to run this operation. ### Retrieve a workflow - [GET /workflows/{workflow_id}](https://developer.zuora.com/v1-api-reference/api/workflows/get_workflow.md): Retrieves information about a specific workflow by its ID. ### User Access Permission You must be assigned the Workflow View Access permission to run this operation. ### Update a workflow - [PATCH /workflows/{workflow_id}](https://developer.zuora.com/v1-api-reference/api/workflows/patch_updateworkflow.md): Updates a specific workflow by its ID, which allows you to configure the settings of a workflow via API. ### User Access Permission You must be assigned the Workflow Manage Access permission to run this operation. ### Export a workflow version - [GET /workflows/{workflow_id}/export](https://developer.zuora.com/v1-api-reference/api/workflows/get_workflowexport.md): Exports a workflow version into a JSON file. This file can be used to create a copy of this workflow version. ### User Access Permission You must be assigned the Workflow View Access permission to run this operation. ### Run a workflow - [POST /workflows/{workflow_id}/run](https://developer.zuora.com/v1-api-reference/api/workflows/post_run_workflow.md): Run a specified workflow. In the request body, you can include parameters that you want to pass to the workflow. For the parameters to be recognized and picked up by tasks in the workflow, you need to define the parameters first. Note: To run a workflow, do not use the following reserved words in the request body of the parameters. - controller - action - id - user_email - user_token - format ### User Access Permission You must be assigned the Workflow Run Access permission to run this operation. To learn about how to define parameters, see Configure the settings of a workflow. ### List all versions of a workflow definition - [GET /workflows/{workflow_id}/versions](https://developer.zuora.com/v1-api-reference/api/workflows/get_workflowversions.md): Return a list of all workflow versions under a workflow definition ### User Access Permission You must be assigned the Workflow View Access permission to run this operation. ### Import a workflow version - [POST /workflows/{workflow_id}/versions/import](https://developer.zuora.com/v1-api-reference/api/workflows/post_workflowversionsimport.md): Create a new workflow version under a workflow definition using the exported JSON document of an existing workflow version. ### User Access Permission You must be assigned the Workflow Manage Access permission to run this operation. ### Stop a workflow run - [PUT /workflows/workflow_runs/{workflow_run_id}/stop](https://developer.zuora.com/v1-api-reference/api/workflows/put_stopworkflowrun.md): Stop a specific workflow run by its ID. ### User Access Permission You must be assigned the Workflow View Access permission to run this operation. ## Data Queries 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). ### List data query jobs - [GET /query/jobs](https://developer.zuora.com/v1-api-reference/api/data-queries/get_dataqueryjobs.md): Returns a list of data query jobs that have been created in your Zuora tenant. You can filter the list by status. If you are an administrator, you can retrieve all the query jobs in your tenant. Otherwise, you can only retrieve your own query jobs. ### Submit a data query - [POST /query/jobs](https://developer.zuora.com/v1-api-reference/api/data-queries/post_dataqueryjob.md): Submits a data query to be executed by Zuora, creating a new query job. Use the Retrieve a data query job endpoint to monitor the job status and access the results once complete. Note: The request must include the Content-Type: application/json header. If this header is missing, the request will fail with the following error: {"code":415,"message":"HTTP 415 Unsupported Media Type"} ### Cancel a data query job - [DELETE /query/jobs/{job-id}](https://developer.zuora.com/v1-api-reference/api/data-queries/delete_dataqueryjob.md): Cancels a data query job, which prevents Zuora from performing the query. This operation is only applicable if the status of the query job is accepted or in_progress. ### Retrieve a data query job - [GET /query/jobs/{job-id}](https://developer.zuora.com/v1-api-reference/api/data-queries/get_dataqueryjob.md): Retrieves a data query job. You can use this operation to track the status of the query job and obtain the URL of the query results. If you are an administrator, you can retrieve every query job in your tenant. If you are a non-admin user and try to retrieve a query job that you are not the owner of, you will get a 403 response indicating that you are forbidden from viewing this job. As a non-admin user, you can only retrieve your own query job. ## Aggregate Queries The Aggregate Query API (AQuA) is a REST API that executes multiple Export ZOQL or ZOQL 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 best practices for bulk data extraction with AQuA. - 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 Aggregate Query. ### Submit an aggregate query job - [POST /v1/batch-query](https://developer.zuora.com/v1-api-reference/api/aggregate-queries/post_batchqueryjob.md): Submits an AQuA job that contains an aggregated list of ZOQL and Export ZOQL queries. ### Retrieve the last completed aggregate query job - [GET /v1/batch-query/jobs/partner/{partner}/project/{project}](https://developer.zuora.com/v1-api-reference/api/aggregate-queries/get_lastbatchqueryjob.md): Returns the details of the last completed job. The completed AQuA jobs that were created 180 days ago are deleted permanently from Zuora, so you cannot query these jobs through API or AQuA job finder. ### Cancel a running aggregate query job - [DELETE /v1/batch-query/jobs/{jobid}](https://developer.zuora.com/v1-api-reference/api/aggregate-queries/delete_batchqueryjob.md): Cancels the current AQuA job, only if the job is not complete. If the job is complete, an error is thrown. ### Retrieve an aggregate query job - [GET /v1/batch-query/jobs/{jobid}](https://developer.zuora.com/v1-api-reference/api/aggregate-queries/get_batchqueryjob.md): Retrieves an aggregate query using the Job ID. Note that the completed AQuA jobs that were created 180 days ago are deleted permanently from Zuora, so you cannot query these jobs through API or AQuA job finder. ## Configuration Templates 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) ### Download a template - [GET /deployment-manager/deployment_artifacts](https://developer.zuora.com/v1-api-reference/api/configuration-templates/get_downloaddeploymenttemplate.md): Download a template for migration in the Deployment manager from the source tenant to the target tenant. ### Compare settings between a source tenant and a target tenant - [POST /deployment-manager/deployment_artifacts/compare](https://developer.zuora.com/v1-api-reference/api/configuration-templates/post_comparetemplate.md): To Compare the configurations from the template downloaded and used in deployment manager for migration which is available in source and target tenant. ### Migrate settings from source tenant to target tenant - [POST /deployment-manager/deployment_artifacts/deploy](https://developer.zuora.com/v1-api-reference/api/configuration-templates/post_migratetenantsettings.md): To migrate the selected configuration of a tenant in Deployment Manager migration while using template from the compare screen. ### List all details of source components - [GET /deployment-manager/deployment_artifacts/retrieve-settings](https://developer.zuora.com/v1-api-reference/api/configuration-templates/get_sourcecomponentdetails.md): When the advanced option is clicked, get the details/metadata of the components, such as settings, notifications, workflow, etc. ### List all templates - [GET /deployment-manager/deployment_templates](https://developer.zuora.com/v1-api-reference/api/configuration-templates/get_templates.md): Retrieves all the templates and their details which are created already. ### Create a deployment template - [POST /deployment-manager/deployment_templates](https://developer.zuora.com/v1-api-reference/api/configuration-templates/post_deploymenttemplate.md): Creates templates based on user preference. There are 2 ways to select components. - Selecting the whole component. - Advanced Options -> which helps user to select specific components to be migrated. It takes the enviroment details from the logged in user automatically, while creating the template. ### Delete a template - [DELETE /deployment-manager/deployment_templates/{id}](https://developer.zuora.com/v1-api-reference/api/configuration-templates/delete_deploymenttemplate.md): Deletes a specific template by passing the ID. ### List all details of a template - [GET /deployment-manager/deployment_templates/{id}](https://developer.zuora.com/v1-api-reference/api/configuration-templates/get_deploymenttemplatedetail.md): Returns the detailed information of a specific template by passing its template ID. ### Sync a deployment template with latest changes - [POST /deployment-manager/deployment_templates/sync](https://developer.zuora.com/v1-api-reference/api/configuration-templates/syncdeploymenttemplate.md): Synchronizes an existing deployment template with the latest changes in the source tenant. ## Metadata 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) ### Compare and deploy a source tenant to a target tenant - [POST /deployment-manager/deployments/tenants](https://developer.zuora.com/v1-api-reference/api/metadata/comparedeploytenant.md): Compare and deploy a source tenant to a target tenant. ### Compare and deploy a template to a tenant - [POST /deployment-manager/deployments/templates](https://developer.zuora.com/v1-api-reference/api/metadata/comparedeploytemplate.md): Compare and deploy a template to a tenant. ### Revert a deployment - [POST /deployment-manager/deployments/{migrationId}/revert](https://developer.zuora.com/v1-api-reference/api/metadata/revertdeployment.md): Revert a deployment. ### Retrieve a deployment log - [GET /deployment-manager/deployments/{migrationId}](https://developer.zuora.com/v1-api-reference/api/metadata/fetchdeploymentlogs.md): Retrieve a deployment log. ### Compare and deploy the product catalog of a tenant to a target tenant - [POST /deployment-manager/deployments/tenant/product_catalog](https://developer.zuora.com/v1-api-reference/api/metadata/comparedeploytenantproductcatalog.md): Compare and deploy the product catalog of a tenant to a target tenant. ### Compare and deploy a template for product catalog to a tenant - [POST /deployment-manager/deployments/template/product_catalog](https://developer.zuora.com/v1-api-reference/api/metadata/comparedeploytemplateproductcatalog.md): Compare and deploy a template for product catalog to a tenant. ## Bulk Data 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 Tutorial for Bulk job API with CSV. For more information, see Process Bulk Job with JSON-lines in Data Loader. ### Create a bulk job - [POST /bulk-data/bulk-jobs](https://developer.zuora.com/v1-api-reference/api/bulk-data/createbulkjob.md): Creates a new bulk job. The job type can be one of Import, Delete, Update, or Cancel. The response includes the job ID and information needed to upload your data file to S3. ### Next Step: Upload the File to S3 After creating a bulk job, you must upload the data file to Amazon S3 using the information returned in the uploadFileInfo object. This includes: - uploadUrl: The S3 endpoint to which the file must be uploaded. - formFields: Key-value pairs to include in a multipart/form-data POST request. - jobId: The ID of the job, used for later submission. You can use the following cURL command to upload the file: curl --request POST \ --url '' \ --header 'Content-Type: multipart/form-data' \ --form 'key=' \ --form 'bucket=' \ --form 'x-amz-algorithm=' \ --form 'x-amz-credential=' \ --form 'x-amz-date=' \ --form 'Policy=' \ --form 'x-amz-signature=' \ --form 'x-amz-security-token=' \ --form 'file=@/path/to/your/file.csv' Note: Always use the exact form field keys returned in the formFields object of the API response. This is a presigned Amazon S3 POST operation and not a Zuora endpoint. After uploading the file, you must call the "Submit a bulk job for processing" operation endpoint to start processing the job. ### Submit a bulk job - [POST /bulk-data/bulk-jobs/{id}/submissions](https://developer.zuora.com/v1-api-reference/api/bulk-data/submitbulkjob.md): Submits a previously created bulk job for processing. This endpoint must be called after the file has been successfully uploaded to the S3 URL using the uploadFileInfo details from the create job response. If the job has not been uploaded properly before calling this endpoint, submission will fail. ### Retrieve the summary of a bulk job - [GET /bulk-data/bulk-jobs/{id}/summary](https://developer.zuora.com/v1-api-reference/api/bulk-data/getbulkjobsummary.md): Get the summary of a specific job by its ID. This operation returns a summary of the specified bulk job. ### Cancel a bulk job - [POST /bulk-data/bulk-jobs/{id}/cancellations](https://developer.zuora.com/v1-api-reference/api/bulk-data/cancelbulkjob.md): Cancels an existing bulk job. Once a job is cancelled, no further processing can be done, and its status will be marked as Cancelled. Note: Cancellation of a job is only allowed before it reaches the In Progress status. Once a job is in progress, it cannot be cancelled but only be aborted. ### Abort a bulk job - [POST /bulk-data/bulk-jobs/{id}/aborts](https://developer.zuora.com/v1-api-reference/api/bulk-data/deleteabortjob.md): Aborts an existing job by sending a POST request to this URI. The request URI identifies the job to abort. When a job is aborted, no more records are processed. ### List download links for a bulk job - [GET /bulk-data/bulk-jobs/{id}/downloads](https://developer.zuora.com/v1-api-reference/api/bulk-data/getdownloadlinksforjob.md): Retrieves the download links for the files associated with a completed job. These files include success rows, error rows, and logs. ### List job summaries for bulk jobs - [GET /bulk-data/bulk-jobs/summaries](https://developer.zuora.com/v1-api-reference/api/bulk-data/getbulkjobsummaries.md): Lists summaries for bulk jobs. You can filter the results using query parameters. ### List mappings for a bulk job - [GET /bulk-data/bulk-jobs/{id}/mappings](https://developer.zuora.com/v1-api-reference/api/bulk-data/getmappingsforjob.md): Retrieves the mappings for an existing bulk job. The mappings define how columns in the source file correspond to fields in the object type template. ## SCIM 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' ``` ### List groups - [GET /scim/v2/Groups](https://developer.zuora.com/v1-api-reference/api/scim/getlistgroups.md): Returns a paginated list of groups, ten groups per page by default. Use the startIndex and count (max 100) query parameters to paginate long lists of groups. It's possible to return a list of specific types of groups using the filter parameter. ### Create a group - [POST /scim/v2/Groups](https://developer.zuora.com/v1-api-reference/api/scim/createanewgroup.md): Creates a new group. Must include the displayName attribute. Users can be added to the group during creation by supplying the user ID values in the members array attribute. ### Bulk create groups - [POST /scim/v2/Groups/bulk](https://developer.zuora.com/v1-api-reference/api/scim/postbulkcreategroups.md): Creates multiple Groups within an organization. Must include the displayName attribute. Users can be added to the group during creation by supplying the user ID values in the members array attribute. ### Bulk update groups - [PATCH /scim/v2/Groups/bulk](https://developer.zuora.com/v1-api-reference/api/scim/patchbulkpatchgroups.md): Updates an existing group resource, allowing individual (or groups of) users to be added or removed from the group with a single operation. Setting the operation attribute of a member object to delete will remove members from a group; add is the default operation for PATCH. ### Bulk delete groups - [POST /scim/v2/Groups/delete](https://developer.zuora.com/v1-api-reference/api/scim/postbulkdeletegroups.md): Permanently removes groups from an organization (members are not deleted, only the group). ### Retrieve a group - [GET /scim/v2/Groups/{id}](https://developer.zuora.com/v1-api-reference/api/scim/getaspecificgroup.md): Retrieves a single group resource. ### Update a group - [PUT /scim/v2/Groups/{id}](https://developer.zuora.com/v1-api-reference/api/scim/updateaspecificgroup.md): Updates an existing group resource, overwriting all values for a group even if an attribute is empty or not provided. PUT will replace all members of a group with those members provided via the members attribute. If an attribute that had been set previously is left blank during a PUT operation, the new value will be blank in accordance with the data type of the attribute and the storage provider. ### Delete a group - [DELETE /scim/v2/Groups/{id}](https://developer.zuora.com/v1-api-reference/api/scim/deleteaspecificgroup.md): Permanently removes a group (members are not deleted, only the group). ### Partially update a group - [PATCH /scim/v2/Groups/{id}](https://developer.zuora.com/v1-api-reference/api/scim/partiallyupdateaspecificgroup.md): Updates an existing group resource, allowing individual (or groups of) users to be added or removed from the group with a single operation. Setting the operation attribute of a member object to delete will remove members from a group; add is the default operation for PATCH. ### List all resource types - [GET /scim/v2/ResourceTypes](https://developer.zuora.com/v1-api-reference/api/scim/gettheressourcetype.md): Retrieves all Resource Types managed by OneId. Resource Types define the resource name, endpoint URL, schemas, and other metadata that indicate where a resource is managed and how it is composed, e.g., "User" or "Group". ### Retrieve a resource type - [GET /scim/v2/ResourceTypes/{id}](https://developer.zuora.com/v1-api-reference/api/scim/getaspecificresourcetype.md): Get related information on a single resource type. Examples: /scim/v2/ResourceTypes/User /scim/v2/ResourceTypes/Group ### List all schemas of resources - [GET /scim/v2/Schemas](https://developer.zuora.com/v1-api-reference/api/scim/getschemaofscim.md): Lists all schemas for all supported resources. A schema is a collection of attribute definitions that describe the contents of an entire or partial resource, e.g., "urn:ietf:params:scim:schemas:core:2.0:User". The attribute definitions specify the name of the attribute, and metadata such as type (e.g., string, binary), cardinality (singular, multi, complex), mutability, and returnability. ### List schemas of a resource - [GET /scim/v2/Schemas/{id}](https://developer.zuora.com/v1-api-reference/api/scim/gettheschemaofspecificscim.md): Gets a specific resource schema by ID. Examples: /scim/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group /scim/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User /scim/v2/Schemas/urn:zuora:scim:schemas:1.0:UserExtension /scim/v2/Schemas/urn:zuora:scim:schemas:1.0:GroupExtension ### Retrieve the service provider configuration - [GET /scim/v2/ServiceProviderConfig](https://developer.zuora.com/v1-api-reference/api/scim/gettheserviceproviderconfig.md): Returns Zuora’s service provider configuration. ### List users - [GET /scim/v2/Users](https://developer.zuora.com/v1-api-reference/api/scim/getlistofusers.md): Returns a paginated list of users, 100 users per page by default. When querying larger instances, reduce the count parameter to 1,000 or less, and use the startIndex parameter to paginate through users. It's possible to return a list of specific types of users with the filter parameter. Examples: /list?filter=userName eq "testuser" /list??filter=status eq "PENDING_ACTIVATION" /list??filter=id eq "91f659cd-6ded-4d92-aa5c-144c3b5455c3" and status eq "PENDING_ACTIVATION" ### Create a user - [POST /scim/v2/Users](https://developer.zuora.com/v1-api-reference/api/scim/createauser.md): Creates a user. Must include the userName attribute and an email address. User will be created as an SSO user by default and a federated ID must be provided for the user. ### Bulk create users - [POST /scim/v2/Users/bulk](https://developer.zuora.com/v1-api-reference/api/scim/bulkcreateusers.md): Creates multiple users within an organization. ### Bulk update users - [PATCH /scim/v2/Users/bulk](https://developer.zuora.com/v1-api-reference/api/scim/bulkupdateusers.md): Updates an existing multiple user resource, overwriting values for specified attributes. ### Delete a list of users - [POST /scim/v2/Users/delete](https://developer.zuora.com/v1-api-reference/api/scim/deletealistofusers.md): Sets multiple users to deactivate. The value of the id should be the user's corresponding user ID. ### Retrieve a user - [GET /scim/v2/Users/{id}](https://developer.zuora.com/v1-api-reference/api/scim/getaspecificuser.md): Retrieves a single user resource. The value of the should be the user's corresponding user ID. ### Update a user - [PUT /scim/v2/Users/{id}](https://developer.zuora.com/v1-api-reference/api/scim/updateaspecificuser.md): Updates an existing user resource, overwriting all values for a user even if an attribute is empty or not provided. If an attribute that had been set previously is left blank during a PUT operation, the new value will be blank in accordance with the data type of the attribute and the storage provider. Deactivated users can be re-enabled by setting the active attribute to true. The value of the should be the user's corresponding user ID. ### Delete a user - [DELETE /scim/v2/Users/{id}](https://developer.zuora.com/v1-api-reference/api/scim/deleteaspecificuser.md): Deactivates a specific user identified by the user ID. ### Partially update a user - [PATCH /scim/v2/Users/{id}](https://developer.zuora.com/v1-api-reference/api/scim/partialupdateaspecificuser.md): Updates an existing user resource, overwriting values for specified attributes. The value of the {id} should be the user's corresponding user ID. Attributes that are not provided in the request will remain unchanged. Updating a value to " " will clear and remove the field from the user's profile. ## Data Labeling 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. ### Submit a data labeling job - [POST /v1/multi-organizations/data-labeling-job](https://developer.zuora.com/v1-api-reference/api/data-labeling/post_datalabelingjob.md): Submits a data labeling job. ### Retrieve a data labeling job - [GET /v1/multi-organizations/data-labeling-job/{job-id}](https://developer.zuora.com/v1-api-reference/api/data-labeling/get_datalabelingjob.md): Retrieves a data labeling job. You can use this operation to track the status of the data labeling job. ## Data Backfill If you are an Order to Revenue user, you can use the data backfill operations to perform, view or stop data backfill tasks. ### Create a booking date backfill job - [POST /v1/uno/data-backfill/bookingdate/jobs](https://developer.zuora.com/v1-api-reference/api/data-backfill/post_createbookingdatebackfilljob.md): Creates a booking date backfill job to update the booking date with your charge's original created-on date. ### List all booking date backfill jobs - [GET /v1/uno/data-backfill/bookingdate/jobs](https://developer.zuora.com/v1-api-reference/api/data-backfill/get_listbookingdatebackfilljobs.md): Use this operation to list all booking date backfill jobs. ### Retrieve a booking date backfill job - [GET /v1/uno/data-backfill/bookingdate/jobs/{jobId}](https://developer.zuora.com/v1-api-reference/api/data-backfill/get_bookingdatebackfilljobbyid.md): Use this operation to retrieve a specific booking date backfill job. ### Stop a booking date backfill job - [PUT /v1/uno/data-backfill/bookingdate/jobs/{jobId}](https://developer.zuora.com/v1-api-reference/api/data-backfill/put_stopbookingdatebackfilljobbyid.md): Use this operation to stop a booking date backfill job. ### Create a data backfill job - [POST /v1/uno/data-backfill/jobs](https://developer.zuora.com/v1-api-reference/api/data-backfill/post_createdatabackfilljob.md): Use this operation to perform the following types of data backfill actions. Also, you need to upload a corresponding file to perform a data backfill action. * Update Product Rate Plan Charge * Update Rate Plan Charge * Update Invoice Item * Update Credit Memo Detail * Update Debit Memo Detail * Update Invoice Item Adjustment For more information, see Perform data backfill. ### Retrieve a data backfill job - [GET /v1/uno/data-backfill/jobs/{jobId}](https://developer.zuora.com/v1-api-reference/api/data-backfill/get_databackfilljobbyid.md): Returns a single Data Backfill job ### Stop a data backfill job - [PUT /v1/uno/data-backfill/jobs/{jobId}](https://developer.zuora.com/v1-api-reference/api/data-backfill/put_stopdatabackfilljobbyid.md): Use this operation to stop a data backfill job. ### List all data backfill jobs - [GET /v1/uno/data-backfill/listjobs](https://developer.zuora.com/v1-api-reference/api/data-backfill/get_listdatabackfilljobs.md) ### Download a data backfill template file - [GET /v1/uno/data-backfill/jobs/{type}/template](https://developer.zuora.com/v1-api-reference/api/data-backfill/get_databackfilltemplate.md): Use this operation to download a data backfill template file of the specific type. ### List all auto backfill jobs - [GET /v1/uno/data-backfill/propagation/jobs](https://developer.zuora.com/v1-api-reference/api/data-backfill/get_listautobackfilljob.md): Use this operation to list all auto backfill jobs. ### Create an auto backfill job - [POST /v1/uno/data-backfill/propagation/jobs](https://developer.zuora.com/v1-api-reference/api/data-backfill/post_createautobackfilljob.md): Creates an autobackfill job to update the rate plan charge and order line item with product rate plan charge. ### Retrieve an auto backfill job - [GET /v1/uno/data-backfill/propagation/jobs/{jobId}](https://developer.zuora.com/v1-api-reference/api/data-backfill/get_autobackfilljobbyid.md): Use this operation to retrieve a specific auto backfill job. ### Stop an auto backfill job - [PUT /v1/uno/data-backfill/propagation/jobs/{jobId}](https://developer.zuora.com/v1-api-reference/api/data-backfill/put_stopautobackfilljobbyid.md): Use this operation to stop an auto backfill job. ## Regenerate If you are an Order to Revenue user, you can use the Regenerate operations to regenerate transactions objects. ### Regenerate booking transactions - [POST /v1/uno-regenerate/booking-transaction](https://developer.zuora.com/v1-api-reference/api/regenerate/post_regeneratebookingtransaction.md): Use this operation to generate booking transactions. This call is useful in the following two use cases: * During customer onboarding, there is a common scenario when customers perform data backfill or data fixes. To synchronize these changes from Billing to Revenue, use this API operation to regenerate booking transaction objects. * Customers choose to experiment with their use cases in the Sandbox environment before implementing them in the Production environment. During this experimentation phase, customers not only interact with data but also use this API operation to regenerate booking transaction objects. ### Regenerate billing transactions - [POST /v1/uno-regenerate/billing-transaction](https://developer.zuora.com/v1-api-reference/api/regenerate/post_regeneratebillingtransaction.md): Use this operation to generate billing transactions. This call is useful in the following two use cases: * During customer onboarding, there is a common scenario when customers perform data backfill or data fixes. To synchronize these changes from Billing to Revenue, use this API operation to regenerate billing transaction objects. * Customers choose to experiment with their use cases in the Sandbox environment before implementing them in the Production environment. During this experimentation phase, customers not only interact with data but also use this API operation to regenerate transaction objects. ### Regenerate revenue recognition events transactions for Delivery Schedule - [POST /v1/uno-regenerate/rev-rec-events](https://developer.zuora.com/v1-api-reference/api/regenerate/post_createrevrecevents.md): Use this operation to generate Delivery Schedule based revenue recognition events transactions. ### Regenerate revenue recognition events transactions for Daily Consumption - [POST /v1/uno-regenerate/rev-rec-events/daily-consumption](https://developer.zuora.com/v1-api-reference/api/regenerate/post_generaterevreceventsfordailyconsumption.md): Use this operation to generate Daily Consumption based revenue recognition events transactions when the Prepaid with Drawdown feature is enabled. ## Test Environments A Test Environment is a dedicated sandbox tenant designed for development, integration, and user acceptance testing of your system configurations and business processes. ### List all test environments - [GET /test-environments](https://developer.zuora.com/v1-api-reference/api/test-environments/getalltestenvironments.md): Use this operation to retrieves a list of all Test Environments. It returns an ArrayResponse containing TestEnvironmentResponse objects, representing the available Test Environments in the system. ### User Access Permission You must be assigned the Refresh Central Sandbox permission to run this operation. ### Retrieve a test environment response - [GET /test-environments/{id}](https://developer.zuora.com/v1-api-reference/api/test-environments/gettestenvironment.md): Use this operation to retrieves a specific Test Environment by its unique identifier. It returns a TestEnvironmentResponse object if the environment is found. If the specified Test Environment does not exist, it returns a 404 error. ### User Access Permission You must be assigned the Refresh Central Sandbox permission to run this operation. ## Test Environment Jobs 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. ### Create a test environment job - [POST /test-environments/{id}/jobs](https://developer.zuora.com/v1-api-reference/api/test-environment-jobs/createtestenvironmentjob.md): Use this operation to create a new job for a specific Test Environment. It handles HTTP POST requests to the /test-environments/{id}/jobs endpoint, accepting a JobRequest object in the request body. Upon successful creation, it returns a JobResponse object and sets the Location header to the polling URL for the created job. ### User Access Permission You must be assigned the Refresh Central Sandbox permission to run this operation. ### List all jobs of a test environment - [GET /test-environments/{id}/jobs](https://developer.zuora.com/v1-api-reference/api/test-environment-jobs/getalljobsoftestenvironment.md): Use this operation to retrieve a list of job responses associated with a specific Test Environment. It handles HTTP GET requests to the /test-environments/{id}/jobs endpoint and returns an ArrayResponse containing JobResponse objects. This method is documented in Swagger, including possible responses for successful retrieval and bad requests. ### User Access Permission You must be assigned the Refresh Central Sandbox permission to run this operation. ### Retrieve a job of a test environment - [GET /test-environments/{id}/jobs/{jobId}](https://developer.zuora.com/v1-api-reference/api/test-environment-jobs/getjoboftestenvironment.md): Use this operation to retrieve a specific job associated with a Test Environment by its unique job ID. It handles HTTP GET requests to the /test-environments/{id}/jobs/{jobId} endpoint and returns a JobResponse object if the job is found. If the specified job does not exist, it returns a 404 error. ### User Access Permission You must be assigned the Refresh Central Sandbox permission to run this operation. ### Perform an action on a test environment job - [POST /test-environments/{id}/jobs/{jobId}/actions](https://developer.zuora.com/v1-api-reference/api/test-environment-jobs/performactionofjob.md): Use this operation to perform a specified action on a Test Environment job. It handles HTTP POST requests to the /test-environments/{id}/jobs/{jobId}/actions endpoint, accepting a JobActionRequest object in the request body. Upon successful execution, it returns a JobResponse object reflecting the updated job state. ### User Access Permission You must be assigned the Refresh Central Sandbox permission to run this operation. ## Test Environment Notifications A Test Environment Notification is an automated email dispatched to inform stakeholders when a Test Environment Job is completed or cancelled. ### Create a test environment notification - [POST /test-environments/{id}/notifications](https://developer.zuora.com/v1-api-reference/api/test-environment-notifications/createtestenvironmentnotification.md): Use this operation to create a new notification for a specific Test Environment. It handles HTTP POST requests to the /test-environments/{id}/notifications endpoint, accepting a TestEnvironmentNotificationRequest object in the request body. Upon successful creation, it returns a TestEnvironmentNotificationResponse object and sets the Location header to the URL of the created notification. ### User Access Permission You must be assigned the Refresh Central Sandbox permission to run this operation. ### List all email notifications of a test environment - [GET /test-environments/{id}/notifications](https://developer.zuora.com/v1-api-reference/api/test-environment-notifications/getallemailnotificationoftestenv.md): Use this operation to retrieve all notifications associated with a specific Test Environment. It handles HTTP GET requests to the /test-environments/{id}/notifications endpoint and returns an ArrayResponse containing TestEnvironmentNotificationResponse objects. ### User Access Permission You must be assigned the Refresh Central Sandbox permission to run this operation. ### Retrieve a notification response of a test environment - [GET /test-environments/{id}/notifications/{notificationId}](https://developer.zuora.com/v1-api-reference/api/test-environment-notifications/gettestenvironmentnotification.md): Use this operation to retrieve a specific notification associated with a Test Environment by its unique notification ID. It handles HTTP GET requests to the /test-environments/{id}/notifications/{notificationId} endpoint and returns a TestEnvironmentNotificationResponse object if the notification is found. If the specified notification does not exist, it returns a 404 error. ### User Access Permission You must be assigned the Refresh Central Sandbox permission to run this operation. ### Update a test environment notification - [PATCH /test-environments/{id}/notifications/{notificationId}](https://developer.zuora.com/v1-api-reference/api/test-environment-notifications/updatetestenvironmentnotification.md): Use this operation to update an existing notification for a specific Test Environment. It handles HTTP PATCH requests to the /test-environments/{id}/notifications/{notificationId} endpoint, accepting a TestEnvironmentNotificationRequest object in the request body. Upon successful update, it returns a TestEnvironmentNotificationResponse object. ### User Access Permission You must be assigned the Refresh Central Sandbox permission to run this operation. ### Delete a notification of a test environment - [DELETE /test-environments/{id}/notifications/{notificationId}](https://developer.zuora.com/v1-api-reference/api/test-environment-notifications/deletetestenvironmentnotification.md): Use this operation to delete a specific notification associated with a Test Environment. It handles HTTP DELETE requests to the /test-environments/{id}/notifications/{notificationId} endpoint and returns a TestEnvironmentNotificationResponse object for the deleted notification. If the specified notification does not exist, it returns a 404 error. ### User Access Permission You must be assigned the Refresh Central Sandbox permission to run this operation. ## Actions 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. ### Create - [POST /v1/action/create](https://developer.zuora.com/v1-api-reference/api/actions/action_postcreate.md): Use the create call to create one or more objects of a specific type. You can specify different types in different create calls, but each create call must apply to only one type of object. ### Limitations This call has the following limitations: * A maximum of 50 objects are supported in a single call. * The Orders feature is not supported. * The Invoice Settlement feature is not supported. This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. * The default WSDL version for Actions is 79. To create objects according to a different 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. ### How to use this call You can create on an array of one or more zObjects. The fields you should specify can be found in the corresponding "CRUD: Create an zObject" operation. For example, to create one or multiple accounts, use the request fields in the CRUD: Create an account operation. It returns an array of SaveResults sorted in the same order, indicating the success or failure of creating each object. The following information applies to this call: * You cannot pass in null zObjects. * You can pass in a maximum of 50 zObjects at a time. * All objects must be of the same type. #### Using Create and Subscribe Calls Both the Create and Subscribe calls will create a new account. However, there are differences between the calls. Use the create call to create an account independent of a subscription. Use the subscribe call to create the account with the subscription and the initial payment information. ### Delete - [POST /v1/action/delete](https://developer.zuora.com/v1-api-reference/api/actions/action_postdelete.md): Deletes one or more objects of the same type. You can specify different types in different delete calls, but each delete call must apply only to one type of object. The following information applies to this call: * You will need to first determine the IDs for the objects you wish to delete. * You cannot pass in any null IDs. * All objects in a specific delete call must be of the same type. ### Objects per Call 50 objects are supported in a single call. ### Query - [POST /v1/action/query](https://developer.zuora.com/v1-api-reference/api/actions/action_postquery.md): The query call sends a query expression by specifying the object to query, the fields to retrieve from that object, and any filters to determine whether a given object should be queried. You can use Zuora Object Query Language(ZOQL) to construct those queries, passing them through the queryString. Once the call is made, the API executes the query against the specified object and returns a query response object to your application. Your application can then iterate through rows in the query response to retrieve information. ### Limitations This call has the following limitations: * All ZOQL limitations apply. * All ZOQL keywords must be in lower case. * The number of records returned is limited to 2000 records. * The Invoice Settlement feature is not supported. This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. * The Orders feature is not supported, which means that the objects listed in Orders Object Model are not supported. * The Active Rating feature is not supported. * The default WSDL version for Actions is 79. To query objects or fields according to a different 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. * Fields with NULL values are not returned in the response. ### QueryMore - [POST /v1/action/queryMore](https://developer.zuora.com/v1-api-reference/api/actions/action_postquerymore.md): Use queryMore to request additional results from a previous query call. If your initial query call returns more than 2000 results, you can use queryMore to query for the additional results. Any queryLocator results greater than 2,000, will only be stored by Zuora for 5 days before it is deleted. This call sends a request for additional results from an initial query call. If the initial query call returns more than 2000 results, you can use the queryLocator returned from query to request the next set of results. Note: Zuora expires queryMore cursors after 15 minutes of activity. To use queryMore, you first construct a query call. By default, the query call will return up to 2000 results. If there are more than 2000 results, query will return a boolean done, which will be marked as false, and a queryLocator, which is a marker you will pass to queryMore to get the next set of results. ### Update - [POST /v1/action/update](https://developer.zuora.com/v1-api-reference/api/actions/action_postupdate.md): Updates the information in one or more objects of the same type. You can specify different types of objects in different update calls, but each specific update call must apply to only one type of object. ### Limitations This call has the following limitations: * A maximum of 50 objects are supported in a single call. * The Invoice Settlement feature is not supported. This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. * The default WSDL version for Actions is 79. To update objects or fields according to a different 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. ### How to use this call? You can update an array of one or more zObjects. The fields you should specify can be found in the corresponding "CRUD: Update an zObject" operation. For example, to update one or multiple accounts, use the request fields in the CRUD: Update an account operation. It returns an array of SaveResults sorted in the same order, indicating the success or failure of updating each object. The following information applies to this call: * You cannot pass in null zObjects. * You can pass in a maximum of 50 zObjects at a time. * All objects must be of the same type. * For each field in each object, you must determine that object's ID. Then populate the fields that you want update with the new information. * Zuora ignores unrecognized fields in update calls. For example, if an optional field is spelled incorrectly or a field that does not exist is specified, Zuora ignores the field and continues to process the call. No error message is returned for unrecognized fields. ## Settings 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. ### Submit settings requests - [POST /settings/batch-requests](https://developer.zuora.com/v1-api-reference/api/settings/post_processsettingsbatchrequest.md): Submit a batch of settings requests by this single API operation. See a 200 response sample in CSV format that lists all available settings. See a 200 response sample in JSON format that lists all available parameters of each setting. By default, one batch settings request can contain a maximum of 100 single operation requests, including: * All the single requests in the process batch settings request. * All the children requests of the single requests. This maximum value is configurable. ### List all settings - [GET /settings/listing](https://developer.zuora.com/v1-api-reference/api/settings/get_listallsettings.md): Get a list of all available settings in your tenant. The response message is by default in JSON format. If you want to receive all the available settings in csv format, include Accept in the header parameters and set it to application/csv. See a 200 response sample in CSV format that lists all available settings. See a 200 response sample in JSON format that lists all available parameters of each setting. You can find a specific operation of an available setting item in your tenant from the 200 response body of this call. See the following common use cases of Settings API for how to operate on a specifc setting item. * Billing Rules: * Get a specific setting - Billing Rules * Update a specific setting - Billing Rules * Get accounting rules - Billing Rules * Age Buckets: * Get Age Buckets * Update Age Buckets * Invoice Templates: * Get a specific Invoice Template * Get all Invoice Templates * Create a new Invoice Template * Update a specific Invoice Template * Delete a specific Invoice Template * Invoice Group: * Create an invoice group * Update an invoice group * Get a specific invoice group * Communications Profiles: * Create a new Communication Profile * Get a Communication Profile * Get all Communication Profiles * Modify a Communication Profile * Notification Definitions: * Get all notification definitions under a particular Communication Profile * Create a notification definition under a particular Communication Profile * Get a notification definition * Update a notification definition * Delete a notification definition * Reusable Blocks: * Create or update reusable blocks * Get all reusable blocks * Get a reusable block * Update a reusable block * Delete a reusable block * Chart of Accounts: * Get Chart of Accounts * Add a new Chart of Account * Quote Templates: * Get all Quote Templates * Get a specific Quote Template * Create a new Quote Template * Direct Integration Tax Engine: * Create a Tax Engine * Retrieve a Tax Engine * Update a Tax Engine * Connect Tax Engines: * Create a Connect Tax Engine * Get a Connect Tax Engine * Update a Connect Tax Engine * Delete a Connect Tax Engine * Zuora Tax Engine: * Get Tax Engines * Create Tax Code using Zuora Tax Engine * Get Tax Code using Zuora Tax Engine * Update Tax Code using Zuora Tax Engine * Delete Tax Code using Zuora Tax Engine * Zuora Tax Rate Period: * Create Tax Rate Periods * Get Tax Rate Periods * Update Tax Rate Periods * Delete Tax Rate Periods * Zuora Tax Code: * Get Specific Tax Code ID * Create Tax Codes * Update Tax Codes * Delete Tax Codes * Zuora Tax Rates: * Get List of Tax Rates * Create Tax Rates * Update Tax Rates * Delete Tax Rates * Units of Measure: * Create a Unit of Measure * Get a Unit of Measure * Get all Units of Measure * Update a Unit of Measure * Delete a Unit of Measure * Summary Statement: * Get a specific summary statement template * Get all templates for summary statement * Create a new summary statement template * Update a specific summary statement template * Delete a specific summary statement template ## Files You can use the operations contained in this section to retrieve files such as export results, invoices, accounting period reports, and so on. ### Retrieve a file - [GET /v1/files/{file-id}](https://developer.zuora.com/v1-api-reference/api/files/get_files.md): Retrieve files such as export results, invoices, and accounting period reports. The response content type depends on the type of file that you retrieve. For example, if you retrieve an invoice PDF, the value of the Content-Type header in the response is application/pdf;charset=UTF-8. Other content types include: - text/csv for CSV files - application/msword for Microsoft Word files - application/vnd.ms-excel and application/vnd.openxmlformats-officedocument.spreadsheetml.sheet for Microsoft Excel files (.xls and .xlsx respectively) - application/zip and application/x-gzip for ZIP and Gzip files respectively - text/html for HTML files - text/plain for text files The response always contains character encoding information in the Content-Type header. For example, Content-Type: application/zip;charset=UTF-8. Note: The maximum file size is 2,047 MB. If you have a data request that exceeds this limit, Zuora returns the following 403 response: 2047MB. Submit a request at Zuora Global Support to determine if large file optimization is an option for you. ### Restore a file - [PUT /v1/files/{file-id}/restore](https://developer.zuora.com/v1-api-reference/api/files/put_files.md): Restores a previously archived file to its RESTORED status. Once a file is archived, it cannot be used directly until the file is restored using this API. ### Notes - This API operation will fail if the count of restored files exceeds the quota limit (1000 by default) in the past 24 hours. - The actual restoration process may take between 12 to 48 hours to complete. - You can monitor the status of the file restoration process using the Retrieve file status API operation until the status transitions to RESTORED. ### Retrieve file status - [GET /v1/files/{file-id}/status](https://developer.zuora.com/v1-api-reference/api/files/get_filestatus.md): Retrieves the status of the file. ## Imports 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. ### CRUD: Create an import - [POST /v1/object/import](https://developer.zuora.com/v1-api-reference/api/imports/object_postimport.md): Creates a data import. ### CRUD: Retrieve an import - [GET /v1/object/import/{id}](https://developer.zuora.com/v1-api-reference/api/imports/object_getimport.md): Retrieve an data import job. ## Custom Exchange Rates 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 Zuora Global Support. ### List custom exchange rates by currency - [GET /v1/custom-exchange-rates/{currency}](https://developer.zuora.com/v1-api-reference/api/custom-exchange-rates/get_customexchangerates.md): This feature is in Limited Availability. If you wish to have access to the feature, submit a request at Zuora Global Support. This reference describes how to query custom foreign exchange rates from Zuora. You can use this API method to query exchange rates only if you use a custom exchange rate provider and upload rates with the Import Foreign Exchange Rates mass action. ## Attachments 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 Attachments. ### Create an attachment - [POST /v1/attachments](https://developer.zuora.com/v1-api-reference/api/attachments/post_attachments.md): Use the Add Attachment REST request with a multipart/form-data to attach a document file to an Account, a Subscription, an Invoice, a Credit Memo, or a Debit Memo. You can only use this operation if you have a Billing role that includes the Manage Attachments permission. For more information, see Billing roles. To change your Billing role, contact your Zuora platform administrator. Note: The Credit and Debit Memos feature is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. ### Delete an attachment - [DELETE /v1/attachments/{attachment-id}](https://developer.zuora.com/v1-api-reference/api/attachments/delete_attachments.md): Use the Delete Attachment REST request to delete an attachment from a Zuora object. You can only use this operation if you have a Billing role that includes the Manage Attachments permission and the Delete Attachments permission. For more information, see Billing roles. To change your Billing role, contact your Zuora platform administrator. ### Retrieve an attachment - [GET /v1/attachments/{attachment-id}](https://developer.zuora.com/v1-api-reference/api/attachments/get_attachments.md): Use the View Attachment REST request to retrieve information about an attachment document. You can only use this operation if you have a Billing role that includes the Manage Attachments permission. For more information, see Billing roles. To change your Billing role, contact your Zuora platform administrator. ### Update an attachment - [PUT /v1/attachments/{attachment-id}](https://developer.zuora.com/v1-api-reference/api/attachments/put_attachments.md): Use the Edit Attachment REST request to make changes to the descriptive fields of an attachment, such as the description and the file name. You cannot change the actual content of the attached file in Zuora. If you need to change the actual content, you need to delete the attachment and add the updated file as a new attachment. You can only use this operation if you have a Billing role that includes the Manage Attachments permission. For more information, see Billing roles. To change your Billing role, contact your Zuora platform administrator. ### List attachments by object type and key - [GET /v1/attachments/{object-type}/{object-key}](https://developer.zuora.com/v1-api-reference/api/attachments/get_attachmentslist.md): Use the View Attachment REST request to get a list of attachments on an account, an invoice, a subscription, a credit memo, or a debit memo. You can only use this operation if you have a Billing role that includes the Manage Attachments permission. For more information, see Billing roles. To change your Billing role, contact your Zuora platform administrator. Note: The Credit and Debit Memos feature is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. ## Describe 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 an object - [GET /v1/describe/{object}](https://developer.zuora.com/v1-api-reference/api/describe/get_describe.md): Provides a reference listing of each object that is available in your Zuora tenant. The information returned by this call is useful if you are using CRUD: Create Export or the AQuA API to create a data source export. See Export ZOQL for more information. ### Response The response contains an XML document that lists the fields of the specified object. Each of the object's fields is represented by a ` element in the XML document. Response sample: xml ProductRatePlanCharge Product Rate Plan Charge ... TaxMode Tax Mode picklist TaxExclusive TaxInclusive export ... ... It is strongly recommended that your integration checks elements in the response. If your integration does not check ` elements, your integration may process fields that are not available for use in data source exports. See Changes to the Describe API for more information. ## Products **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 Commerce API. 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. ### CRUD: Create a product - [POST /v1/object/product](https://developer.zuora.com/v1-api-reference/api/products/object_postproduct.md) ### CRUD: Retrieve a product - [GET /v1/object/product/{id}](https://developer.zuora.com/v1-api-reference/api/products/object_getproduct.md): Retrieve a specific product. ### CRUD: Update a product - [PUT /v1/object/product/{id}](https://developer.zuora.com/v1-api-reference/api/products/object_putproduct.md): Updates a Product object. ### CRUD: Delete a product - [DELETE /v1/object/product/{id}](https://developer.zuora.com/v1-api-reference/api/products/object_deleteproduct.md): Deletes a specific product. ## 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 Commerce API. 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. ### List all products - [GET /v1/catalog/products](https://developer.zuora.com/v1-api-reference/api/catalog/get_catalog.md): Retrieves the entire product catalog, including all products, features, and their corresponding product rate plans, charges. Products are returned in reverse chronological order on the UpdatedDate field. For each product, this operation returns a maximum of 300 product rate plans in the response. Across the returned product rate plans, up to 300 product rate plan charges can be returned for each product. ### Retrieve a product - [GET /v1/catalog/products/{product-key}](https://developer.zuora.com/v1-api-reference/api/catalog/get_product.md): Retrieves detailed information about a specific product, including information about its product rate plans and charges. This operation returns a maximum of 300 product rate plans and 300 product rate plan charges across all product rate plans in the response. ## Catalog Groups **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 Commerce API. A catalog group is used to group a list of product rate plans with a specific grade. ### Create a catalog group - [POST /v1/catalog-groups](https://developer.zuora.com/v1-api-reference/api/catalog-groups/post_createcataloggroup.md): Note: This operation 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 want to join this early adopter program, submit a request at Zuora Global Support. Creates a catalog group which groups a list of product rate plans. ### List all catalog groups - [GET /v1/catalog-groups](https://developer.zuora.com/v1-api-reference/api/catalog-groups/get_listallcataloggroups.md): Note: This operation 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 want to join this early adopter program, submit a request at Zuora Global Support. Retrieves basic information about all catalog groups. ### Retrieve a catalog group - [GET /v1/catalog-groups/{catalog-group-key}](https://developer.zuora.com/v1-api-reference/api/catalog-groups/get_retrievecataloggroup.md): Note: This operation 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 want to join this early adopter program, submit a request at Zuora Global Support. Retrieves basic information about a catalog group. ### Update a catalog group - [PUT /v1/catalog-groups/{catalog-group-key}](https://developer.zuora.com/v1-api-reference/api/catalog-groups/put_updatecataloggroup.md): Note: This operation 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 want to join this early adopter program, submit a request at Zuora Global Support. Updates a catalog group by its unique number or ID. ### Notes - It is best practice to only specify the fields that you want to change in the request body. - If you specify an empty value for a field in the request body, the corresponding field in the catalog group is emptied. - The catalog group type cannot be changed. ### Delete a catalog group - [DELETE /v1/catalog-groups/{catalog-group-key}](https://developer.zuora.com/v1-api-reference/api/catalog-groups/delete_cataloggroup.md): Note: This operation 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 want to join this early adopter program, submit a request at Zuora Global Support. Deletes a catalog group. ## 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 Commerce API. 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. ### List all product rate plans of a product - [GET /v1/products/{product-key}/product-rate-plans](https://developer.zuora.com/v1-api-reference/api/product-rate-plans/get_productrateplans.md): Retrieves information about all product rate plans of a specific product. ### Retrieve a product rate plan by ID - [GET /v1/product-rate-plans/{id}](https://developer.zuora.com/v1-api-reference/api/product-rate-plans/get_productrateplan.md): Retrieves a product rate plan by its ID. ### List product rate plans by external ID - [GET /v1/product-rate-plans/external-id/{id}](https://developer.zuora.com/v1-api-reference/api/product-rate-plans/get_productrateplansbyexternalid.md): Retrieves information about one or multiple product rate plans by external ID. ### CRUD: Create a product rate plan - [POST /v1/object/product-rate-plan](https://developer.zuora.com/v1-api-reference/api/product-rate-plans/object_postproductrateplan.md): Retrieves a product rate plan. ### CRUD: Retrieve a product rate plan - [GET /v1/object/product-rate-plan/{id}](https://developer.zuora.com/v1-api-reference/api/product-rate-plans/object_getproductrateplan.md): Retrieves a product rate plan. ### CRUD: Update a product rate plan - [PUT /v1/object/product-rate-plan/{id}](https://developer.zuora.com/v1-api-reference/api/product-rate-plans/object_putproductrateplan.md): Updates a product rate plan. ### CRUD: Delete a product rate plan - [DELETE /v1/object/product-rate-plan/{id}](https://developer.zuora.com/v1-api-reference/api/product-rate-plans/object_deleteproductrateplan.md): Deletes a product rate plan. ## 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 Commerce API. 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. ### Create a product rate plan definition - [POST /v1/product-rateplan-definitions](https://developer.zuora.com/v1-api-reference/api/product-rate-plan-definitions/post_createproductrateplandefinition.md): Creates a product rate plan definition to use a charge in a product rate plan. In the request, you must specify either the unique ID or number of both the charge and the product rate plan to add the specified charge to a specific rate plan. Note: This operation requires the Attribute-based Pricing feature to be enabled, which is in the Early Adopter phase. ### List product rate plan definitions - [GET /v1/product-rateplan-definitions](https://developer.zuora.com/v1-api-reference/api/product-rate-plan-definitions/get_retrieveproductrateplandefinitions.md): Retrieves basic information about the product rate plan definitions for a product rate plan. Note: This operation requires the Attribute-based Pricing feature to be enabled, which is in the Early Adopter phase. ### Retrieve a product rate plan definition - [GET /v1/product-rateplan-definitions/{product-rateplan-definition-key}](https://developer.zuora.com/v1-api-reference/api/product-rate-plan-definitions/get_retrieveproductrateplandefinition.md): Retrieves basic information about a product rate plan definition. Note: This operation requires the Attribute-based Pricing feature to be enabled, which is in the Early Adopter phase. ### Delete a product rate plan definition - [DELETE /v1/product-rateplan-definitions/{product-rateplan-definition-key}](https://developer.zuora.com/v1-api-reference/api/product-rate-plan-definitions/delete_productrateplandefnition.md): Deletes a product rate plan definition. Note: This operation requires the Attribute-based Pricing feature to be enabled, which is in the Early Adopter phase. ## 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 Commerce API. 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. ### Retrieve a product rate plan charge - [GET /v1/product-rate-plan-charges/{product-rate-plan-charge-key}](https://developer.zuora.com/v1-api-reference/api/product-rate-plan-charges/get_retrieveproductrateplancharge.md): Retrieves basic information about a product rate plan charge. ### CRUD: Create a product rate plan charge - [POST /v1/object/product-rate-plan-charge](https://developer.zuora.com/v1-api-reference/api/product-rate-plan-charges/object_postproductrateplancharge.md): Creates a product rate plan charge for a specified rate plan charge. Product rate plan charges can be of three types, one-time fees, recurring fees, and usage fees. ### CRUD: Retrieve a product rate plan charge - [GET /v1/object/product-rate-plan-charge/{id}](https://developer.zuora.com/v1-api-reference/api/product-rate-plan-charges/object_getproductrateplancharge.md): Retrieves a specific product rate plan charge. ### CRUD: Update a product rate plan charge - [PUT /v1/object/product-rate-plan-charge/{id}](https://developer.zuora.com/v1-api-reference/api/product-rate-plan-charges/object_putproductrateplancharge.md): Updates the information about a product rate plan charge. ### CRUD: Delete a product rate plan charge - [DELETE /v1/object/product-rate-plan-charge/{id}](https://developer.zuora.com/v1-api-reference/api/product-rate-plan-charges/object_deleteproductrateplancharge.md): Deletes a product rate plan charge. ## 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 Commerce API. 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. ### Create a product charge definition - [POST /v1/product-charge-definitions](https://developer.zuora.com/v1-api-reference/api/product-charge-definitions/post_createproductchargedefinition.md): Creates a product charge definition for a charge. You can create as many product charge definitions as needed for one charge. In the request, you must specify the unique ID or number of the charge for which this charge definition is to be created. The ID or number of a product rate plan is optional. Note: This operation requires the Attribute-based Pricing feature to be enabled, which is in the Early Adopter phase. ### List product charge definitions - [GET /v1/product-charge-definitions](https://developer.zuora.com/v1-api-reference/api/product-charge-definitions/get_retrieveproductchargedefinitions.md): Retrieves basic information about the product charge definitions. Note: This operation requires the Attribute-based Pricing feature to be enabled, which is in the Early Adopter phase. ### Create product charge definitions - [POST /v1/product-charge-definitions/bulk](https://developer.zuora.com/v1-api-reference/api/product-charge-definitions/post_createproductchargedefinitionbulk.md): Bulk creates product charge definitions for a charge. You can create up to 1000 product charge definitions at a given time for a specific charge. In the request, you must specify the unique ID or number of the charge for which this charge definition is to be created. The ID or number of a product rate plan is optional. Note: This operation requires the Attribute-based Pricing feature to be enabled, which is in the Early Adopter phase. ### Update product charge definitions - [PUT /v1/product-charge-definitions/bulk](https://developer.zuora.com/v1-api-reference/api/product-charge-definitions/put_updateproductchargedefinitionbulk.md): Bulk updates multiple product charge definitions. Note: This operation requires the Attribute-based Pricing feature to be enabled, which is in the Early Adopter phase. ### Retrieve a product charge definition - [GET /v1/product-charge-definitions/{product-charge-definition-key}](https://developer.zuora.com/v1-api-reference/api/product-charge-definitions/get_retrieveproductchargedefinition.md): Retrieves basic information about a product charge definition. Note: This operation requires the Attribute-based Pricing feature to be enabled, which is in the Early Adopter phase. ### Update a product charge definition - [PUT /v1/product-charge-definitions/{product-charge-definition-key}](https://developer.zuora.com/v1-api-reference/api/product-charge-definitions/put_updateproductchargedefinition.md): Update a product charge definition. Note: This operation requires the Attribute-based Pricing feature to be enabled, which is in the Early Adopter phase. ### Delete a product charge definition - [DELETE /v1/product-charge-definitions/{product-charge-definition-key}](https://developer.zuora.com/v1-api-reference/api/product-charge-definitions/delete_productchargedefnition.md): Deletes a product charge definition. Note: This operation requires the Attribute-based Pricing feature to be enabled, which is in the Early Adopter phase. ## 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 Commerce API. 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. ### CRUD: Retrieve a product rate plan charge tier - [GET /v1/object/product-rate-plan-charge-tier/{id}](https://developer.zuora.com/v1-api-reference/api/product-rate-plan-charge-tiers/object_getproductrateplanchargetier.md): Retrieves a specific product rate plan charge tier. ### CRUD: Update a product rate plan charge tier - [PUT /v1/object/product-rate-plan-charge-tier/{id}](https://developer.zuora.com/v1-api-reference/api/product-rate-plan-charge-tiers/object_putproductrateplanchargetier.md): Updates the price of a product rate plan charge tier. To make other updates to product rate plan charge tiers, use CRUD: Update a product rate plan charge and specify ProductRatePlanChargeTierData in the request body. ## Zuora Revenue Integration **Note:** You can only use the operations in this section if you have the Billing - Revenue Integration feature enabled. See Billing - Revenue Integration 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 Commerce API. ### Update a Zuora Revenue accounting code - [PUT /v1/revpro-accounting-codes](https://developer.zuora.com/v1-api-reference/api/zuora-revenue-integration/put_revproaccountingcodes.md): Update the Zuora Revenue accounting code that corresponds to a specific Product Rate Plan Charge Id in Zuora Billing.