API Reference: Billing

Amend Modifies a subscription by creating Amendment objects. However, to modify a subscription, Zuora recommends that you use [Update subscription](https://www.zuora.com/developer/api-reference/#operation/PUT_Subscription) instead of this action. The Amend action cannot modify the custom fields on the Subscription object. You must use [Update subscription](https://www.zuora.com/developer/api-reference/#operation/PUT_Subscription) or [Update subscription custom fields of a specified subscription version](https://www.zuora.com/developer/api-reference/#operation/PUT_UpdateSubscriptionCustomFieldsOfASpecifiedVersion) to modify the custom fields on the Subscription object. You can use this action to create up to 10 Amendment objects. You must specify the following fields for each Amendment object: * `ContractEffectiveDate` * `Name` * `SubscriptionId` * `Type` Additionally, the value of `SubscriptionId` must be the same for each Amendment object. You cannot use this operation to update multiple subscriptions. **Note:** When you call this operation, Zuora modifies the subscription in the order that you specify Amendment objects in the request body. If Zuora is unable to create an Amendment object when you call this operation, the entire call fails.

Create 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 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](https://knowledgecenter.zuora.com/DC_Developers/G_SOAP_API/Zuora_SOAP_API_Version_History). ## How to Use this Call You can call create on an array of one or more zObjects. It returns an array of SaveResults, 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. For a use case of this call, see [Upload usage records](https://www.zuora.com/developer/api-guides/#Upload-usage-records). ### 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.

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.

Execute Use the execute call to execute a process to split an invoice into multiple invoices. The original invoice must be in draft status. The resulting invoices are called split invoices. **Note:** This feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com). To split a draft invoice into multiple split invoices: 1. Use the create call to create a separate InvoiceSplitItem object for each split invoice that you want to create from the original draft invoice. 2. Use the create call to create a single InvoiceSplit object to collect all of the InvoiceSplitItem objects. 3. Use the execute call to split the draft invoice into multiple split invoices. You need to create InvoiceSplitItem objects and an InvoiceSplit object before you can use the execute call. * Supported objects: InvoiceSplit * Asynchronous process: yes

Generates an on-demand invoice for a specific customer. This is similar to creating an ad-hoc bill run for a specific customer account in the Zuora UI. * Supported objects: Invoice * Asynchronous process: yes The ID of the generated invoice is returned in the response. If multiple invoices are generated, only the id of the first invoice generated is returned. This occurs when an account has multiple subscriptions with the [invoice subscription separately](https://knowledgecenter.zuora.com/BC_Subscription_Management/Subscriptions/B_Creating_Subscriptions/Invoicing_Subscriptions_Separately) option enabled.

Query 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](https://knowledgecenter.zuora.com/DC_Developers/K_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 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 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](https://knowledgecenter.zuora.com/DC_Developers/G_SOAP_API/Zuora_SOAP_API_Version_History).

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

Subscribe This call performs many actions. Use the subscribe call to bundle information required to create at least one new subscription. The call takes in an array of SubscribeRequests. Because it takes an array, you can submit a batch of subscription requests at once. You can create up to 50 different subscriptions in a single subscribe call. This is a combined call that you can use to perform all of the following tasks in a single call: * Create accounts * Create contacts * Create payment methods, including external payment options * Create an invoice for the subscription * Apply the first payment to a subscription ## Object Limits 50 objects are supported in a single call. ## Effective Date If the effective date is in the future, the invoices will not be generated, and there will be no invoice number. ## Subscription Name, Number, and ID ### Subscription Name and Number The subscription name is a unique identifier for the subscription. If you do not specify a value for the name, Zuora will create one automatically. The automatically generated value is known as the subscription number, such as `A-S00000080`. You cannot change the subscription name or number after creating the subscription. * **Subscription name**: The name that you set for the subscription. * **Subscription number**: The value generated by Zuora automatically if you do not specify a subscription name. Both the subscription name and number must be unique. If they are not, an error will occur. ### Subscription ID The subscription ID is a 32-digit ID in the format 4028xxxx. This is also the unique identifier for a subscription. This value is automatically generated by the system and cannot be edited or updated, but it can be queried. One subscription can have only one subscription name or number, but it can have multiple IDs: Each version of a subscription has a different ID. The Subscription object contains the fields `OriginalId` and `PreviousSubscriptionId`. `OriginalId` is the ID for the first version of a subscription. `PreviousSubscriptionId` is the ID of the version created immediately prior to the current version. ## Subscription Preview You can preview invoices that would be generated by the subscribe call. When previewing invoices with the subscribe call, the correspondinig Contract Effective, Service Activation, or Customer Acceptance date is required if the subscription contains a charge with its trigger event being set as `ContractEffectiveDate`, `ServiceActivationDate`, or `CustomerAcceptanceDate`. ## Invoice Subscriptions Separately If you have enabled the invoice subscriptions separately feature, a subscribe call will generate an invoice for each subscription for every subscription where the field `IsInvoiceSeparate` is set to `true`. If the invoice subscriptions separately feature is disabled, a subscribe call will generate a single invoice for all subscriptions. See [Invoicing Subscriptions Separately](https://knowledgecenter.zuora.com/BC_Subscription_Management/Subscriptions/B_Creating_Subscriptions/Invoicing_Subscriptions_Separately) for more information. ## Subscriptions and Draft Invoices If a draft invoice that includes charges exists in a customer account, using the subscribe call to create a new subscription and generate an invoice will cause the new subscription to be added to the existing draft invoice. Zuora will then post the invoice. ## When to Use Subscribe and Create Calls You can use either the subscribe call or the create call to create the objects associated with a subscription (accounts, contacts, and so on). There are differences between these calls, however, and some situations are better for one or the other. ### Use the Subscribe Call The subscribe call bundles up all the information you need for a subscription. Use the subscribe call to create new subscriptions when you have all the information you need. Subscribe calls cannot update BillTo, SoldTo, and Account objects. Payment information objects cannot be updated if there is an existing account ID in the call. These objects are not supported in a subscribe call. ### Use the Create Call The create call is more useful when you want to develop in stages. For example, if you want to first create an account, then a contact, and so on. If you do not have all information available, use the create call. To create a subscription, you must activate the account from Draft status to Active by calling the subscribe call.

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. You can update an array of one or more zObjects. It returns an array of SaveResults, 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. ## 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](https://knowledgecenter.zuora.com/DC_Developers/G_SOAP_API/Zuora_SOAP_API_Version_History).

Delete an accounting code 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.

Delete an accounting period 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](https://knowledgecenter.zuora.com/CF_Users_and_Administrators/A_Administrator_Settings/User_Roles/f_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

Delete an attachment Use the Delete Attachment REST request to delete an attachment from a Zuora object.

Delete a credit memo **Note:** This operation is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/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](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/Invoice_Settlement_Migration_Checklist_and_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](https://knowledgecenter.zuora.com/CF_Users_and_Administrators/A_Administrator_Settings/User_Roles/d_Billing_Roles) for more information.

Cancel a data query job Cancels a [data query](https://knowledgecenter.zuora.com/DC_Developers/BA_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`.

Delete a debit memo **Note:** This operation is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/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](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/Invoice_Settlement_Migration_Checklist_and_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](https://knowledgecenter.zuora.com/CF_Users_and_Administrators/A_Administrator_Settings/User_Roles/d_Billing_Roles) for more information.

Delete an email template Deletes an email template. **Note**: This operation is only applicable to notifications for custom events.

Delete a notification definition Deletes a notification definition. **Note**: This operation is only applicable to notifications for custom events.

Delete notification histories for an account Delete all notification histories for the given account. All email and callout notifications for this account will be deleted upon successful operation. **Note**: This operation is only available if you have the Notification and the Configurable Event features enabled.

Delete document properties **Note:** This feature is available only if you have the Billing Document Properties Setup feature enabled. The Billing Document Properties Setup feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/). Deletes document properties with a specific ID for a billing document. Billing documents include invoices, credit memos, and debit memos. **Note:** You can delete document properties for credit and debit memos only if you have the Invoice Settlement feature 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](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/Invoice_Settlement_Migration_Checklist_and_Guide) for more information.

Multi-entity: Delete an entity **Note:** The Multi-entity feature is in **Limited Availability**. If you wish to have access to the feature, submit a request at [Zuora Global Support](http://support.zuora.com/). Removes an entity and its sub-entities from a multi-entity hierarchy. You can only remove unprovisioned entities. An error occurred when you remove a provisioned entity. ## User Access Permission You must make the call as a global entity administrator.

Delete an event trigger

Delete a journal run 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.

Delete an order **Note:** This operation is only available if you have the [Orders](https://knowledgecenter.zuora.com/BC_Subscription_Management/Orders/AA_Overview_of_Orders#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 and want to adopt Orders, see [What is Orders Harmonization](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Harmonization#What_is_Orders_Harmonization.3F) and join the [Orders Harmonization community group](https://community.zuora.com/t5/Orders-Harmonization/gp-p/Orders-Harmonization) for more information. If you want to enable Orders, submit a request at [Zuora Global Support](https://support.zuora.com/). **Note:** The [Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AA_Overview_of_Order_Line_Items) 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. If you want to join this early adopter program, submit a request at [Zuora Global Support](https://support.zuora.com/). 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 if the charges that are affected by this order are invoiced.

Delete a payment **Note:** This operation is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/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](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/Invoice_Settlement_Migration_Checklist_and_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.

Delete a payment method 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. For a use case of this operation, see [Configure Payment Methods](https://www.zuora.com/developer/api-guides/#Configure-payment-methods).

Delete a payment run Deletes a payment run. Only payment runs with the Canceled or Error status can be deleted.

Delete a revenue schedule Deletes a revenue schedule by specifying its revenue schedule number ## Prerequisites You must have the Delete Custom Revenue Schedule permissions in Zuora Finance. The revenue schedule must not be associated with any invoice item, invoice item adjustment, or credit/debit memo item in Zuora Billing.

Delete a refund **Note:** This operation is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/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](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/Invoice_Settlement_Migration_Checklist_and_Guide) for more information. Deletes a refund. You can delete a refund with the Canceled or Error status. If you have the Invoice Settlement feature enabled, refunds applied to credit balance cannot be deleted.

Delete a sequence set 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](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/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](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/Invoice_Settlement_Migration_Checklist_and_Guide) for more information.

Delete a summary journal entry 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.

Delete a taxation item Deletes a specific taxation item by ID.

Delete a workflow Deletes a specific workflow by its ID.

Delete a custom object definition 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.

Delete a custom object record 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.

Retrieve an account 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.

Retrieve an account summary 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 for the last six recently updated subscriptions. ## 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.

Retrieve an accounting code This reference describes how to query an accounting code through the REST API.

Retrieve an accounting period Retrieves an accounting period. Prerequisites ------------- You must have Zuora Finance enabled on your tenant.

List all accounting codes This reference describes how to query all accounting codes in your chart of accounts through the REST API.

List all accounting periods Retrieves all accounting periods on your tenant.

List all custom object bulk jobs Lists all custom object bulk jobs submitted by your tenant.

List custom object definitions 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](https://www.zuora.com/developer/api-reference/#operation/POST_CustomObjectDefinitions) call in the new tenant to import all the custom objects from the old tenant.

List orders **Note:** This feature is only available if you have the [Order Metrics](https://knowledgecenter.zuora.com/BC_Subscription_Management/Orders/AA_Overview_of_Orders#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](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Orders_Harmonization/Orders_Harmonization). You can still keep the existing Subscribe and Amend API integrations to create and manage subscriptions. **Note:** The [Order Line Items](https://knowledgecenter.zuora.com/Billing/Subscriptions/Orders/Order_Line_Items/AA_Overview_of_Order_Line_Items) 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. If you want to join this early adopter program, submit a request at [Zuora Global Support](https://support.zuora.com/). Retrieves information about all orders in your tenant. By default, it returns the first page of the orders.

List records for a custom object Lists all object records of the given type. You can also use the `q` query parameter to filter the output records. ## Limitations This call has the following limitations: * When a record is created, there will be a delay before it is available for search. For example, if you create 5 records and perform a query that these 5 records satisfy the query conditions, there will be a delay between when the 5 records are created, and when all the 5 records can be returned in the query result.

List all summary journal entries in a journal run This REST API reference describes how to retrieve information about all summary journal entries in a journal run.

Retrieve an amendment Retrieves detailed information about the specified subscription amendment.

List all amendments of a subscription Retrieves detailed information about the amendment with the specified subscription.

Retrieve an attachment Use the View Attachment REST request to retrieve information about an attachment document.

List attachments by object type and key 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. **Note**: The Credit and Debit Memos feature is only available if you have [Invoice Settlement](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/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](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement/Invoice_Settlement_Migration_Checklist_and_Guide) for more information.

Retrieve a job of hard deleting billing document files 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.