Tools (430)

Extracted live via the executor SDK.

• accountingCodes.deleteAccountingCode

  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.

• accountingCodes.getAccountingCode

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

• accountingCodes.getAllAccountingCodes

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

• accountingCodes.postAccountingCode

  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.

• accountingCodes.putAccountingCode

  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.

• accountingCodes.putActivateAccountingCode

  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.

• accountingCodes.putDeactivateAccountingCode

  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.

• accountingPeriods.deleteAccountingPeriod

  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

• accountingPeriods.getAccountingPeriod

  Retrieves an accounting period. Prerequisites

  You must have Zuora Finance enabled on your tenant.

• accountingPeriods.getAllAccountingPeriods

  Retrieves all accounting periods on your tenant.

• accountingPeriods.postAccountingPeriod

  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.
• accountingPeriods.putCloseAccountingPeriod

  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.

• accountingPeriods.putPendingCloseAccountingPeriod

  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.

• accountingPeriods.putReopenAccountingPeriod

  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.
• accountingPeriods.putRunTrialBalance

  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.

• accountingPeriods.putUpdateAccountingPeriod

  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.
• accounts.getAccount

  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.

• accounts.getAccountSummary

  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.

• accounts.objectDeleteAccount

  Deletes a specific account asynchronously.

  Note: When Orders is enabled, before deleting a customer account, you must delete all related orders and subscriptions where this account has been referenced as a subscription owner or invoice owner.

• accounts.objectGetAccount

  Retrieves the information about one specific account.

• accounts.objectPostAccount

  Creates an account without creating any associated objects such as subscriptions.

• accounts.objectPutAccount

  Updates an account.

• accounts.postAccount

  Creates a customer account with a payment method, a bill-to contact, and an optional sold-to contact. 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 either the workEmail or personalEmail field is specified, then the account's email delivery preference is automatically set to true. (In that case, emails go to the workEmail address, if it exists, or else the personalEmail.) If neither field is specified, the email delivery preference is automatically set to false.

  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

• accounts.putAccount

  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 on file or to the email delivery preference. If either the personalEmail or workEmail is specified (or both), the system updates the corresponding email address(es) on file 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 and sold-to contacts are separate data entities. If you select the Same as Bill To Contact check box during account creation, both the Bill To and Sold To contacts are updated upon updating either one because they point to the same contact record. In this case, if you want to update only one of them, you have to first create another contact and update the Bill To or Sold To contact of the customer account to be the newly created one.

  For a use case of this operation, see Configure payment methods.

• actions.actionPosTamend

  Modifies a subscription by creating Amendment objects. However, to modify a subscription, Zuora recommends that you use Update subscription instead of this action.

  The Amend action cannot modify the custom fields on the Subscription object. You must use Update subscription or Update subscription custom fields of a specified subscription version 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.

• actions.actionPosTcreate

  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.

  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.

  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.

• actions.actionPosTdelete

  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.

• actions.actionPosTexecute

  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.

  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
• actions.actionPosTgenerate

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

• actions.actionPosTquery

  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 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.
• actions.actionPosTqueryMore

  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.

• actions.actionPosTsubscribe

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

• actions.actionPosTupdate

  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.
• amendments.getAmendmentsByKey

  Retrieves detailed information about the specified subscription amendment.

• amendments.getAmendmentsBySubscriptionId

  Retrieves detailed information about the amendment with the specified subscription.

• amendments.objectDeleteAmendment

  Invoiced amendments cannot usually be deleted. One exception to this rule is auto-renew amendments. You can delete the last auto-renew amendment even if an invoice has been generated.

• amendments.objectGetAmendment
• amendments.objectPutAmendment
• attachments.deleteAttachments

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

• attachments.getAttachments

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

• attachments.getAttachmentsList

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

• attachments.postAttachments

  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.

  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.

• attachments.putAttachments

  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.

• billingDocuments.getBillingDocumentFilesDeletionJob

  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.

• billingDocuments.getBillingDocuments

  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
• billingDocuments.postBillingDocumentFilesDeletionJob

  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.

• billingDocuments.postGenerateBillingDocuments

  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.

• billingPreviewRun.getBillingPreviewRun

  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.

• billingPreviewRun.postBillingPreviewRun

  Creates a billing preview run for multiple customer accounts.

  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.

• billRun.objectDeleteBillRun

  Deletes a bill run.

  When deleting a bill run, the logic is the same as when using the UI to delete a bill run. The only required parameter is BillRunId. The Status for the bill run must be Canceled in order to delete a bill run.

• billRun.objectGetBillRun

  Retrieves information about a bill run.

  Business operations depending on the completion of the bill run will not be available while the bill run query returns PostInProgress. Upon completion of the bill run, a query will return Posted.

• billRun.objectPostBillRun

  Creates an ad hoc bill run or a single account or multiple customer accounts.

  When creating a single account ad hoc bill run, your request must include AccountId and must not include Batch or BillCycleDay.

  If more than 500 bill runs created by using this operation are in Pending status, no more bill runs can be created by using this operation.

• billRun.objectPutBillRun

  Posts or cancels a bill run.

  Post a Bill Run

  Posting a bill run is an asynchronous operation. To post a bill run, the current bill run must have a status of Completed.

  When a bill run is posted, its status is changed to PostInProgress. Once all invoices for this bill run are posted then its status is changed to Posted.

  When you post a bill run and query the status of a bill run, you will get one of the following results PostInProgress, Completed, or Posted. If all invoices in the bill run are posted, then the status of the bill run is Posted. If one or more invoices fail to post, the status will change back to Completed and you will need to post the bill run again.

  Cancel a Bill Run

  Canceling a bill run is an asynchronous operation. When canceling a bill run, the logic is the same as when using the UI to cancel a bill run. You need to provide the BillRunId, and set the Status to Canceled.

  When canceling a bill run, consider the following:

  • Canceling a bill run with a Completed status.
    • Only the current bill run will be canceled.
  • Canceling a bill run with a Pending status.
    • When canceling an Ad-hoc bill run, only the current bill run will be canceled.
    • When canceling a scheduled bill, all scheduled bill runs will be canceled.

  The Cancel operation may not be successful. Its success depends on its current business validation. Only a bill run that has no posted invoices can be canceled. If any posted invoices belong to the bill run then an invalid value exception will be thrown with the message, "The Bill Run cannot be Cancelled, There are Posted invoices."

• billRun.postEmailBillingDocumentsfromBillRun

  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.

• catalog.getCatalog

  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.

  With product rate plans and rate plan charges, the REST API has a maximum array size.

  For a use case of this operation, see Retrieve the product catalog.

• catalog.getProduct

  Retrieves detailed information about a specific product, including information about its product rate plans and charges.

• catalog.postCatalog

  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.

  Shares a product with a target entity. Zuora synchronizes the shared products to the target entity after sharing. For more information about product sharing, see Products Sharing Across Entities.

  Note that:

  • You must finish all the prerequisites before sharing products with other entities.

  • Only source entity administrators have permission to share products with other entities. You must make the call as a source entity administrator.

  • Currently, you can only share a product with one entity at a time. An error occurs if you try to share a product to more than one entity.

• chargeMetrics.getChargeMetrics

  Retrieves key charge metrics about rate plan charges that have changes in a specified time range.

  The purpose of fromTimestamp and toTimestamp is to synchronize charge metrics data incrementally.

• chargeMetrics.getChargeMetricsDiscountAllocationDetails

  Retrieves discount allocation details about rate plan charges that have changes in a specified time range.

  The purpose of fromTimestamp and toTimestamp is to synchronize discount allocation details incrementally.

• chargeRevenueSummaries.getCrsByChargeId

  Retrieves the details of a charge revenue summary by specifying the subscription charge ID. This response retrieves all revenue items associated with a charge revenue summary.

• chargeRevenueSummaries.getCrsByCrsNumber

  Retrieves the details of a charge revenue summary by specifying the charge revenue summary number. The response includes all revenue items associated with the charge revenue summary.

• communicationProfiles.objectGetCommunicationProfile
• connections.postConnections

  Establishes a connection to the Zuora REST API service based on a valid user credentials.

  **Note:**This is a legacy REST API. Zuora recommends you to use OAuth for authentication instead.

  This call authenticates the user and returns an API session cookie that's used to authorize subsequent calls to the REST API. The credentials must belong to a user account that has permission to access the API service.

  As noted elsewhere, it's strongly recommended that an account used for Zuora API activity is never used to log into the Zuora UI. Once an account is used to log into the UI, it may be subject to periodic forced password changes, which may eventually lead to authentication failures when using the API.

• contacts.objectDeleteContact

  Deletes a contact.

• contacts.objectGetContact

  Retrieves detailed information about a specific contact.

• contacts.objectPostContact

  Creates a contact for a specified account.

• contacts.objectPutContact

  Updates a contact for a specified account.

  You can update contacts for cancelled accounts.

  For a use case of this operation, see Edit the contact information for an account.

• contacts.putScrubContact

  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.

• creditBalanceAdjustments.objectGetCreditBalanceAdjustment
• creditBalanceAdjustments.objectPostCreditBalanceAdjustment
• creditBalanceAdjustments.objectPutCreditBalanceAdjustment
• creditMemos.deleteCreditMemo

  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.

• creditMemos.getCreditMemo

  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.

• creditMemos.getCreditMemoItem

  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.

• creditMemos.getCreditMemoItemPart

  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 item. A credit memo part item is a single line item in a credit memo part. A credit memo part can consist of several different types of items.

• creditMemos.getCreditMemoItemParts

  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 part. A credit memo part item is a single line item in a credit memo part. A credit memo part can consist of several different types of items.

• creditMemos.getCreditMemoItems

  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/creditmemos/402890245c7ca371015c7cb40ac30015/items?amount=100

  • /v1/creditmemos/402890245c7ca371015c7cb40ac30015/items?amount=100&sort=createdDate

• creditMemos.getCreditMemoPart

  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.

• creditMemos.getCreditMemoParts

  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.

• creditMemos.getCreditMemos

  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/creditmemos?status=Posted

  • /v1/creditmemos?referredInvoiceId=null&status=Draft

  • /v1/creditmemos?status=Posted&type=External&sort=+number

• creditMemos.getTaxationItemsOfCreditMemoItem

  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.

• creditMemos.postCmTaxationItems

  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.

• creditMemos.postCreditMemoFromPrpc

  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.

  For a use case of this operation, see Create credit memo.

• creditMemos.postCreditMemoPdf

  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.

• creditMemos.postEmailCreditMemo

  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.
• creditMemos.postRefundCreditMemo

  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 10,000.

  For a use case of this operation, see Refund processing.

• creditMemos.postUploadFileForCreditMemo

  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.
• creditMemos.putApplyCreditMemo

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

• creditMemos.putCancelCreditMemo

  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.

• creditMemos.putPostCreditMemo

  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.

• creditMemos.putUnapplyCreditMemo

  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 10,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, you have to specify the invoices or debit memos in the request.
  • 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.

  If the Proration application rule is used, when unapplying 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.

• creditMemos.putUnpostCreditMemo

  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.

• creditMemos.putUpdateCreditMemo

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

  You can update a credit memo only if you have the user permission. See Billing Roles for more information.

• customExchangeRates.getCustomExchangeRates

  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.

• customObjectDefinitions.deleteCustomObjectDefinitionByType

  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.

• customObjectDefinitions.getAllCustomObjectDefinitionsInNamespace

  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.

• customObjectDefinitions.getCustomObjectDefinitionByType

  Retrieves the custom object definition by type for the given tenant.

• customObjectDefinitions.postCustomObjectDefinitions

  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 options is 250.
  • The default maximum number of characters for the Text field is 512. You can configure the max length up to 4,096 characters when creating or updating the custom object definition via API.
• customObjectDefinitions.postUpdateCustomObjectDefinition

  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.
• customObjectJobs.getAllCustomObjectBulkJobs

  Lists all custom object bulk jobs submitted by your tenant.

• customObjectJobs.getCustomObjectBulkJob

  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.

• customObjectJobs.getCustomObjectBulkJobErrors

  Lists all errors for a custom object bulk job.

• customObjectJobs.postCustomObjectBulkJob

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

  Limits

  This custom object bulk jobs have the following limits:

  • The concurrent bulk job limit per tenant is 5. Bulk jobs in open, 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 bulk job. See Platform Permissions for more information.
• customObjectJobs.postUploadFileForCustomObjectBulkJob

  Uploads a file to a create custom object bulk job. Only one file is allowed per job. The job must be in pending status when you upload the file to it. The job will start creating records 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.

• customObjectRecords.deleteCustomObjectRecordById

  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.

• customObjectRecords.getAllRecordsForCustomObjectType

  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.
• customObjectRecords.getCustomObjectRecordById

  Retrieves a record of a given type by ID.

• customObjectRecords.patchPartialUpdateCustomObjectRecord

  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    }  ]}

• customObjectRecords.postCustomObjectRecords

  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    }  ]}

• customObjectRecords.postCustomObjectRecordsBatchUpdateOrDelete

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

• customObjectRecords.putCustomObjectRecord

  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    }  ]}

• dataQueries.deleteDataQueryJob

  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.

• dataQueries.getDataQueryJob

  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.

• dataQueries.getDataQueryJobs

  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.

• dataQueries.postDataQueryJob

  Submits a data query to be performed by Zuora and creates a query job. You can use Retrieve a data query job to track the status of the query job and obtain the URL of the query results.

• debitMemos.deleteDebitMemo

  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.

• debitMemos.getDebitMemo

  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.

• debitMemos.getDebitMemoApplicationParts

  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.

• debitMemos.getDebitMemoItem

  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.

• debitMemos.getDebitMemoItems

  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/debitmemos/402890245c7ca371015c7cb40b28001f/items?amount=100

  • /v1/debitmemos/402890245c7ca371015c7cb40b28001f/items?amount=100&sort=createdDate

• debitMemos.getDebitMemos

  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/debitmemos?status=Posted

  • /v1/debitmemos?referredInvoiceId=null&status=Draft

  • /v1/debitmemos?status=Posted&type=External&sort=+number

• debitMemos.getTaxationItemsOfDebitMemoItem

  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.

• debitMemos.postDebitMemoCollect

  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.

  Reistrictions

  Since this API will do lots of works, and some of them are resource consuming, we need to resitrict 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.
• debitMemos.postDebitMemoFromPrpc

  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.

• debitMemos.postDebitMemoPdf

  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.

• debitMemos.postDmTaxationItems

  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.

• debitMemos.postEmailDebitMemo

  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.
• debitMemos.postUploadFileForDebitMemo

  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.
• debitMemos.putBatchUpdateDebitMemos

  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 batches with one call.

• debitMemos.putCancelDebitMemo

  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.

• debitMemos.putDebitMemo

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

  You can update a debit memo only if you have the user permission. See Billing Roles for more information.

• debitMemos.putPostDebitMemo

  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.

• debitMemos.putUnpostDebitMemo

  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.

• describe.getDescribe

  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 <field> element in the XML document.

  Each <field> element contains the following elements:

  Element	Description
  <name>	API name of the field.
  <label>	Name of the field in the Zuora user interface.
  <type>	Data type of the field. The possible data types are: boolean, date, datetime, decimal, integer, picklist, text, timestamp, and ZOQL. If the data type is picklist, the <field> element contains an <options> element that lists the possible values of the field.
  <contexts>	Specifies the availability of the field. If the <contexts> element lists the export context, the field is available for use in data source exports.

  The <field> element contains other elements that provide legacy information about the field. This information is not directly related to the REST API.

  Response sample:

  xml

  <?xml version="1.0" encoding="UTF-8"?><object>  <name>ProductRatePlanCharge</name>  <label>Product Rate Plan Charge</label>  <fields>    ...    <field>      <name>TaxMode</name>      <label>Tax Mode</label>      <type>picklist</type>      <options>        <option>TaxExclusive</option>        <option>TaxInclusive</option>      </options>      <contexts>        <context>export</context>      </contexts>      ...    </field>    ...  </fields></object>

  It is strongly recommended that your integration checks <contexts> elements in the response. If your integration does not check <contexts> 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.

• documentProperties.deleteDocumentProperties

  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.

  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 for more information.

• documentProperties.getDocumentProperies

  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.

  Retrieve information about document properties of a billing document. Billing documents include invoices, credit memos, and debit memos.

  Note: You can retrieve information about document properties of 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 for more information.

• documentProperties.postDocumentProperties

  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.

  Creates custom document properties for a billing document. For example, a document property can be a custom name used for files generated for billing documents. Billing documents include invoices, credit memos, and debit memos.

  If you want to configure custom file names for billing documents created through API operations, you have to call this operation before posting the billing documents.

  Note: You can create 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 for more information.

• documentProperties.putDocumentProperties

  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.

  Updates document properties with a specific ID for a billing document. Billing documents include invoices, credit memos, and debit memos.

  Note: You can update 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 for more information.

• entities.deleteEntities

  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.

  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.

• entities.getEntities

  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.

  Retrieves detailed information of certain entities in a multi-entity hierarchy.

  You can retrieve:

  • Provisioned entities

  • Unprovisioned entities

  • Both provisioned and unprovisioned entities

  User Access Permission

  You can make the call as any entity user.

• entities.getEntityById

  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.

  Retrieves detailed information about a specified entity.

  User Access Permission

  You can make the call as any entity user.

• entities.postEntities

  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.

  Creates an entity in a multi-entity hierarchy.

  User Access Permission

  You must make the call as a global entity administrator.

  Notes

  • We recommend that you assign only one administrator to manage the entity hierarchy, because an administrator of the global entity by default can only access to the entities that are created by themselves.
• entities.putEntities

  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.

  Edits the following information about an unprovisioned entity:

  • Name

  • Display name

  • Locale

  • Timezone

  User Access Permission

  You must make the call as a global entity administrator.

  Notes

  • You are not allowed to edit the locale and time zone of the provisioned entities through the REST API.
  • You are not allowed to edit the display name of the global entity.
• entities.putProvisionEntity

  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.

  Provisions an entity. You can only provision an entity if its parent entity is provisioned.

  User Access Permission

  You must make the call as a global entity administrator.

  Notes

  • Zuora does not allow you to remove a provisioned entity from the multi-entity hierarchy. So before you provision an entity, make sure that you put the entity in the correct place in the multi-entity hierarchy.
• entityConnections.getEntityConnections

  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.

  Retrieves information about certain connections for a specified entity. You can specify the entity to retrieve in the Zuora-Entity-Ids request header.

  You can retrieve:

  • Inbound connections
  • Outbound connections
  • Both inbound and outbound connections

  User Access Permission

  You can make the call as any entity user.

• entityConnections.postEntityConnections

  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.

  Initiates a connection request from a source entity to a target entity.

  User Access Permission

  You must make the call as a source entity administrator. Also, this administrator must have permission to access to the target entity.

• entityConnections.putEntityConnectionsAccept

  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.

  Accepts a connection request.

  User Access Permission

  You must make the call as an entity administrator to accept a connection request.

• entityConnections.putEntityConnectionsDeny

  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.

  Denies a connection request.

  User Access Permission

  You must make the call as an entity administrator to deny a connection request.

• entityConnections.putEntityConnectionsDisconnect

  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.

  Disconnects an established connection. If you have shared objects from a global entity to a target entity, disconnecting the connection will break the mapping relationship between these entities and cannot be recovered later.

  User Access Permission

  You must make the call as an administrator of the target entity or source entity.

• eventTriggers.deleteEventTrigger
• eventTriggers.getEventTrigger

  Retrieve an event trigger

• eventTriggers.getEventTriggers

  List event triggers

• eventTriggers.postEventTrigger

  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
  • DebitMemo
  • DebitMemoItem
  • Feature
  • Invoice
  • InvoiceAdjustment
  • InvoiceItem
  • InvoiceItemAdjustment
  • JournalEntry
  • JournalEntryItem
  • Order
  • OrderAction
  • Payment
  • PaymentApplication
  • PaymentMethod
  • PaymentPart
  • Product
  • ProductFeature
  • ProductRatePlan
  • ProductRatePlanCharge
  • RatePlan
  • RatePlanCharge
  • Refund
  • RefundApplication
  • RevenueEvent
  • RevenueEventItem
  • RevenueSchedule
  • RevenueScheduleItem
  • Subscription
  • SubscriptionProductFeature
  • TaxationItem
  • Usage

  Tenant level base objects and tenant level event triggers

  Zuora identifies the following base objects as the tenant level base objects:

  • AccountingCode
  • AccountingPeriod
  • BillingRun
  • Feature
  • JournalEntry
  • JournalEntryItem
  • Product
  • ProductFeature
  • ProductRatePlan
  • ProductRatePlanCharge

  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

  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:

  • The maximum number of event triggers is 20. If you want to increase the limit, submit a request at Zuora Global Support.

  • The INSERT change type is not supported on RatePlan base objects.

  • The INSERT change type is not supported on SubscriptionProductFeature base objects.

• eventTriggers.putEventTrigger
• exports.objectGetExport

  Use this operation to check the status of a data source export and access the exported data.

  When you export data from Zuora, each exported file is available for download for 7 days. Data source exports (Export objects) older than 90 days are automatically deleted.

• exports.objectPostExport

  Use this operation to create a data source export. After you have created a data source export, use CRUD: Retrieve an export to check the status of the data source export and access the exported data.

  Limits

  Zuora system enforces the following limits on data source exports:

  • The maximum processing time per export is 3 hours. If an export is executed for longer than 3 hours, it will be killed automatically.
  • The maximum number of concurrent exports is 50 per tenant. Exports in Pending and Processing status are counted towards the concurrent export limit. Zuora system will reject the subsequent data source export requests once the concurrent export limit is reached.

  When you export data from Zuora, each exported file is available for download for 7 days. Data source exports (Export objects) older than 90 days are automatically deleted.

  Note: This operation supports the Export ZOQL query language. However, this operation does not support some data sources, objects, and fields in Export ZOQL queries. For full compatibility with Export ZOQL, Zuora recommends that you use the AQuA API instead of this operation.

• features.objectDeleteFeature
• features.objectGetFeature
• features.objectPostFeature
• features.objectPutFeature
• files.getFiles

  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: <security:max-object-size>2047MB</security:max-object-size>. Submit a request at Zuora Global Support to determine if large file optimization is an option for you.

• hmacSignatures.postHmacSignatures

  This REST API reference describes how to return unique signature and token values that used to process a CORS enabled API call.

• hostedPages.getHostedPages

  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 1.0 configuration information: GET <BaseURL>/hostedpages?version=1
  • The request for Payment Pages 2.0 configuration information: GET <BaseURL>/hostedpages?version=2
  • The request for all versions of Payment Pages configuration information: GET <BaseURL>/hostedpages

  Notes

  If you do not have the corresponding tenant setting enabled, e.g., the request version parameter set to 2 with the Payment Pages 2.0 setting disabled, you will receive an error.

• imports.objectGetImport
• imports.objectPostImport

  Creates a data import.

• invoiceAdjustments.objectDeleteInvoiceAdjustment
• invoiceAdjustments.objectGetInvoiceAdjustment
• invoiceAdjustments.objectPostInvoiceAdjustment
• invoiceAdjustments.objectPutInvoiceAdjustment
• invoiceItemAdjustments.objectDeleteInvoiceItemAdjustment
• invoiceItemAdjustments.objectGetInvoiceItemAdjustment
• invoiceItems.objectGetInvoiceItem
• invoicePayments.objectGetInvoicePayment
• invoicePayments.objectPostInvoicePayment
• invoicePayments.objectPutInvoicePayment
• invoices.getInvoiceApplicationParts

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

• invoices.getInvoiceFiles

  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.

• invoices.getInvoiceItems

  Retrieves the information about all items of a specified invoice.

• invoices.getTaxationItemsOfInvoiceItem

  Retrieves information about the taxation items of a specific invoice item.

• invoices.objectDeleteInvoice
• invoices.objectGetInvoice
• invoices.objectPutInvoice
• invoices.postCreditMemoFromInvoice

  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.

• invoices.postDebitMemoFromInvoice

  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.

• invoices.postEmailInvoice

  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.
• invoices.postStandaloneInvoice

  Note: This operation is only available if you have Unified Invoicing enabled. The Unified Invoicing 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.

  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 Create Standalone Invoice and Modify Invoice user permissions. See Billing Roles for more information.

• invoices.postUploadFileForInvoice

  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.
• invoices.putBatchUpdateInvoices

  Updates multiple invoices in batches with one call.

  Limitations

  This operation has the following limitations:

  • You can update a maximum of 50 invoices by one call.
• invoices.putReverseInvoice

  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.

  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 2,000 items in total, including invoice items, discount items, and taxation items.

  See Invoice Reversal for more information.

• invoices.putUpdateInvoice

  Updates a specific invoice.

• invoices.putWriteOffInvoice

  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.

• invoiceSplitItems.objectGetInvoiceSplitItem
• invoiceSplits.objectGetInvoiceSplit
• journalRuns.deleteJournalRun

  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.

• journalRuns.getJournalRun

  This REST API reference describes how to get information about a journal run. Request and response field descriptions and sample code are provided.

• journalRuns.postJournalRun

  This REST API reference describes how to create a journal run. Request and response field descriptions and sample code are provided.

• journalRuns.putJournalRun

  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.
• massUpdater.getMassUpdater

  Describes how to get information about the result of a mass action through the REST API.

• massUpdater.postMassUpdater

  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.

• massUpdater.putMassUpdater

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

  Deletes an email template.

  Note: This operation is only applicable to notifications for custom events.

• notifications.deleteDeleteNotificationDefinition

  Deletes a notification definition.

  Note: This operation is only applicable to notifications for custom events.

• notifications.deleteDeleteNotificationHistoryForAccount

  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.

• notifications.getCalloutHistory

  Describes how to get a notification history for callouts.

• notifications.getEmailHistory

  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

• notifications.getGetEmailTemplate

  Queries the email template of the specified ID.

  Note: This operation is only applicable to email templates for custom events.

• notifications.getGetNotificationDefinition

  Queries the notification definition of the given ID.

  Note: This operation is only applicable to notifications for custom events.

• notifications.getGetNotificationHistoryDeletionTask

  Get the notification history deletion task by ID.

  Note: This operation is only available if you have the Notification and the Configurable Event features enabled.

• notifications.getQueryEmailTemplates

  Queries email templates.

  Note: This operation is only applicable to email templates for custom events.

• notifications.getQueryNotificationDefinitions

  Queries notification definitions with the specified filters.

  Note: This operation is only applicable to notifications for custom events.

• notifications.postCreateEmailTemplate

  Creates an email template.

  Note: This operation is only applicable to email templates for custom events.

• notifications.postCreateNotificationDefinition

  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. See a step-by-step guide for creating a custom notification in Zuora API Guides.

  Note: This operation is only applicable to notifications for custom events.

• notifications.putUpdateEmailTemplate

  Updates an email template.

  Note: This operation is only applicable to email templates for custom events.

• notifications.putUpdateNotificationDefinition

  Updates a notification definition.

  Note: This operation is only applicable to notifications for custom events.

• oAuth.createToken

  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. The rate limit is 100 requests per minute.

• operations.postBillingPreview

  Note: The Billing Preview feature is in Limited Availability. If you wish to have access to the feature, submit a request at Zuora Global Support.

  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 does not calculate taxes for charges in the subscription.

  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.

• operations.postTransactionInvoicePayment

  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.

• orderLineItems.getOrderLineItem

  Note: The 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.

  Note: You also need to enable the Orders feature to access the Order Line Items feature. 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.

  Retrieves the detailed information about a specified order line item.

• orderLineItems.postOrderLineItems

  Note: The 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.

  Note: You also need to enable the Orders feature to access the Order Line Items feature. 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.

  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.

• orderLineItems.putOrderLineItem

  Note: The 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.

  Note: You also need to enable the Orders feature to access the Order Line Items feature. 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.

  Updates a specified order line item.

• orders.deleteOrder

  Note: 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 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: The 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.

  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.

• orders.getAllOrders

  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 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 information about all orders in your tenant. By default, it returns the first page of the orders.

• orders.getJobStatusAndResponse

  Note: 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 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: The 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.

  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.

• orders.getOrder

  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 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 the detailed information about a specified order.

• orders.getOrderMetricsforEvergreenSubscription

  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: As of Zuora Billing Release 306, Zuora has upgraded the methodologies for calculating metrics in Orders. The new methodologies are reflected in the following Order Delta Metrics objects.

  • Order Delta Mrr
  • Order Delta Tcv
  • Order Delta Tcb

  It is recommended that all customers use the new Order Delta Metrics. If you are an existing Order Metrics customer and want to migrate to Order Delta Metrics, submit a request at Zuora Global Support.

  Whereas new customers, and existing customers not currently on Order Metrics, will no longer have access to Order Metrics, existing customers currently using Order Metrics will continue to be supported.

  Note: As of Zuora Billing Release 306, any new customers who onboard on Orders or Orders Harmonization will no longer get this operation.

  Retrieves the metrics of an evergreen subscription in a specified order.

• orders.getOrdersByInvoiceOwner

  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 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 the detailed information about all orders for a specified invoice owner.

• orders.getOrdersBySubscriptionNumber

  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 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 the detailed information about all orders for a specified subscription. Any orders containing the changes on the specified subscription are returned.

• orders.getOrdersBySubscriptionOwner

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

• orders.getSubscriptionTermInfo

  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.

  Retrieves the terms of the specified subscription.

• orders.postCreateOrderAsynchronously

  Note: 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 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: The 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.

  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.

  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

  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.

  If you have a need for a large order that exceeds any limits of the above, you can request a limit increase for the Orders asynchronous API by submitting a request at Zuora Global Support.

• orders.postOrder

  Note: 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 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: The 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.

  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 an order line item
  • Create an order line item with a new subscription

  You can also see the API Guides for more use cases of the "Create an order" operation.

  Creating a draft order is currently not supported. See Known Limitations in Orders for additional limitations.

  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

  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.

  If you have a need for a large order that exceeds any limits of the above, you can request a limit increase for the Orders asynchronous API by submitting a request at Zuora Global Support.

  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.

• orders.postPreviewOrder

  Note: 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 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: The 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.

  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.

  See Preview a Subscription Creation Order for a use case of the "Preview an order" operation.

  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

  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.

  If you have a need for a large order that exceeds any limits of the above, you can request a limit increase for the Orders asynchronous API by submitting a request at Zuora Global Support.

• orders.postPreviewOrderAsynchronously

  Note: 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 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: The 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.

  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.

  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

  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.

  If you have a need for a large order that exceeds any limits of the above, you can request a limit increase for the Orders asynchronous API by submitting a request at Zuora Global Support.

• orders.putOrderTriggerDates

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

  Updates the triggering dates for either of the following order actions:

  • CreateSubscription
  • AddProduct
  • UpdateProduct
  • RemoveProduct
  • RenewSubscription
  • TermsAndConditions
• orders.putUpdateOrderCustomFields

  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.

• orders.putUpdateSubscriptionCustomFields

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

  Updates the custom fields of a specified subscription.

• paymentGatewayReconciliation.postReconcileRefund

  Reconciles a refund when receiving the gateway reconciliation request or event.

• paymentGatewayReconciliation.postRejectPayment

  Sets the Payment status to "Rejected", creates a refund for the payment amount, and returns the Refund object as response.

• paymentGatewayReconciliation.postReversePayment

  Sets the Payment status to "Reversed", creates a refund for the amount specified in the request, and returns the Refund object as response.

• paymentGatewayReconciliation.postSettlePayment

  Sets the Payment status to "Settled" and returns the Payment object as response.

• paymentGateways.getPaymentgateways

  Retrieves the basic information about all the payment gateways.

• paymentMethods.deletePaymentMethods

  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.

• paymentMethods.getPaymentMethod

  This operation allows you to get the detailed information about a payment method.

• paymentMethods.getPaymentMethodsCreditCard

  This REST API reference describes how to retrieve all credit card information for the specified customer account.

  Notes

  The response includes details of credit or debit cards for the specified customer account. Card numbers are masked, e.g., "************1234". Cards are returned in reverse chronological order of last update.

  Though you can also send requests for bank transfer, ACH, or other supported payment methods, the response will not include effective details of these payment methods.

• paymentMethods.getStoredCredentialProfiles

  Retrieves the stored credential profiles within a payment method.

  Note: This feature is in the Early Adopters phase. We are actively soliciting feedback from a small set of early adopters before releasing as generally available.

• paymentMethods.objectDeletePaymentMethod
• paymentMethods.objectGetPaymentMethod
• paymentMethods.objectPostPaymentMethod
• paymentMethods.objectPutPaymentMethod

  For a use case of this operation, see Configure Payment Methods.

• paymentMethods.postCancelAuthorization

  Note: If you wish to enable this feature, submit a request at Zuora Global Support.

  Allows you to cancel an authorization. The payment gateways that support this operation include Verifi, CyberSource 1.28, CyberSource 1.97, Chase Paymentech Orbital, and Ingenico ePayments.

• paymentMethods.postCancelStoredCredentialProfile

  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.

  Note: This feature is in the Early Adopters phase. We are actively soliciting feedback from a small set of early adopters before releasing as generally available.

• paymentMethods.postCreateAuthorization

  Note: If you want to enable this feature, submit a request at Zuora Global Support.

  Enables you to authorize the availability of funds for a transaction but delay the capture of funds until a later time. Subsequently, use CRUD: Create a payment or Create a payment to capture the authorized funds, or use Cancel authorization to cancel the authorization.

  The payment gateways that support this operation include:

  • Adyen integration v2.0 - This gateway does not support Cancel authorization.
  • CyberSource 1.28
  • CyberSource 1.97
  • CyberSource 2.0 - This gateway does not support Cancel authorization.
  • Chase Paymentech Orbital
  • Ingenico ePayments
  • Verifi - This gateway does not support Cancel authorization.

  Note that CyberSource 2.0 supports the Delayed Capture feature for both Credit Cards and Credit Card Reference payment methods.

  If you have the Invoice Settlement feature enabled, use the Create payment operation to capture the funds instead of the CRUD: Create payment operation.

• paymentMethods.postCreateStoredCredentialProfile

  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.

  Note: This feature is in the Early Adopters phase. We are actively soliciting feedback from a small set of early adopters before releasing as generally available.

• paymentMethods.postExpireStoredCredentialProfile

  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.

  Note: This feature is in the Early Adopters phase. We are actively soliciting feedback from a small set of early adopters before releasing as generally available.

• paymentMethods.postPaymentMethods

  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. The orphan payment method must be associated with a customer account within 10 days. Otherwise, it will be deleted.

  This operation supports the payment methods listed below.

  PayPal Express Checkout

  The following request body fields are specific to this payment method:

  • BAID (required)
  • email (required)

  PayPal Native Express Checkout

  The following request body fields are specific to this payment method:

  • BAID (required)
  • email (optional)

  PayPal Adaptive

  The following request body fields are specific to this payment method:

  • preapprovalKey (required)
  • email (required)

  Credit Card

  The following request body fields are specific to this payment method:

  • cardHolderInfo (cardHolderName required)
  • cardNumber (required)
  • cardType (required)
  • expirationMonth (required)
  • expirationYear (required)
  • mitConsentAgreementRef
  • mitConsentAgreementSrc
  • mitNetworkTransactionId
  • mitProfileAction
  • mitProfileType
  • mitProfileAgreedOn
  • securityCode
  • checkDuplicated

  ACH

  The following request body fields are applicable to this payment method:

  • bankABACode (required)
  • bankAccountName (required)
  • bankAccountNumber (required)
  • bankAccountType (required)
  • bankName (required)
  • addressLine1
  • addressLine2
  • phone
  • email
  • city
  • country
  • state
  • zipCode

  SEPA

  The following request body fields are applicable to this payment method:

  • IBAN (required)
  • accountHolderInfo (required)
  • businessIdentificationCode

  Betalingsservice (Direct Debit DK)

  The following request body fields are applicable to this payment method:

  • accountNumber (required)
  • identityNumber (required)
  • bankCode (required)
  • accountHolderInfo (required)

  Autogiro (Direct Debit SE)

  The following request body fields are applicable to this payment method:

  • accountNumber (required)
  • identityNumber (required)
  • branchCode (required)
  • accountHolderInfo (required)

  Bacs (Direct Debit UK)

  The following request body fields are applicable to this payment method:

  • accountNumber (required)
  • bankCode (required)
  • accountHolderInfo (required)

  Becs (Direct Entry AU)

  The following request body fields are applicable to this payment method:

  • accountNumber (required)
  • branchCode (required)
  • accountHolderInfo (required)

  Becsnz (Direct Debit NZ)

  The following request body fields are applicable to this payment method:

  • accountNumber (required)
  • bankCode (required)
  • branchCode (required)
  • accountHolderInfo (required)

  PAD (Pre-Authorized Debit)

  The following request body fields are applicable to this payment method:

  • accountNumber (required)
  • bankCode (required)
  • branchCode (required)
  • accountHolderInfo (required)

  Custom payment methods

  Note: This feature is in the Early Adopter phase. If you want to use this feature, submit a request at Zuora Global Support to enable the Universal Payment Connector and Open Payment Method services that support this feature.

  With the support of Universal Payment Connector (UPC) and Open Payment Method (OPM) services, you can create custom payment methods by using the fields defined in a definition file for this type of custom payment method. See Set up custom payment gateways and payment methods for details.

• paymentMethods.postPaymentMethodsCreditCard

  You can create a credit card payment method for a customer account or an orphan credit card payment method that is not associated with any customer account. The orphan payment method must be associated with a customer account within 10 days. Otherwise, it will be deleted.

  This API call is CORS Enabled. Use client-side JavaScript to invoke the call.

  Note: If you use this operation to create credit card payment methods instead of using the iFrame of Hosted Payment Pages, you are subject to PCI-compliance audit requirements.

• paymentMethods.postPaymentMethodsDecryption

  The decryption API endpoint can conditionally perform 3 tasks in one atomic call:

  • Decrypt Apple Pay Payment token
  • Create Credit Card Payment Method in Zuora with decrypted Apple Pay information
  • Process Payment on a specified Invoice (optional)
• paymentMethods.putPaymentMethod

  This operation allows you to update an existing payment method.

  The following request body fields can be updated regardless of payment method types:

  • authGateway
  • gatewayOptions
  • accountHolderInfo
  • Custom fields

  The following request body fields can be updated only for the Credit Card payment method:

  • expirationMonth
  • expirationYear
  • securityCode
• paymentMethods.putPaymentMethodsCreditCard

  Updates an existing credit card payment method.

• paymentMethods.putScrubPaymentMethods

  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.

• paymentMethods.putVerifyPaymentMethods

  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.

• paymentMethodSnapshots.objectGetPaymentMethodSnapshot

  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.

• paymentMethodTransactionLogs.objectGetPaymentMethodTransactionLog
• paymentRuns.deletePaymentRun

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

• paymentRuns.getPaymentRun

  Retrives the information about a specific payment run.

• paymentRuns.getPaymentRunData

  Retrieves payment run data and the processing result with details, if the data field was specified in the Create payment run operation.

• paymentRuns.getPaymentRuns

  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

• paymentRuns.getPaymentRunSummary

  Retrives the summary of a payment run.

• paymentRuns.postPaymentRun

  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.

  If no filter criteria are specified in the request body, the payment run collects payments for all accounts.

• paymentRuns.putPaymentRun

  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.

• payments.deletePayment

  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.

• payments.getPayment

  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.

• payments.getPaymentItemPart

  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.

• payments.getPaymentItemParts

  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.

• payments.getPaymentPart

  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.

• payments.getPaymentParts

  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.

• payments.getRetrieveAllPayments

  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.

  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

• payments.objectDeletePayment

  Deletes a payment. Only payments with the Cancelled status can be deleted.

• payments.objectGetPayment

  Retrieves the information about one specific payment.

• payments.objectPostPayment

  Creates a payment for one or multiple invoices.

• payments.objectPutPayment

  Updates a payment.

• payments.postCreatePayment

  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.

    The support for standalone payments is in the Early Adopter phase. If you want to use this feature, submit a request at Zuora Global Support to enable it.

  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 10,000.

  For more information, see Create Payments and Create Payments Without Specifying Customer Accounts.

• payments.postRefundPayment

  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, see Refund Payments.

  For a use case of this operation, see Refund processing.

• payments.putApplyPayment

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

• payments.putCancelPayment

  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.

• payments.putTransferPayment

  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.

• payments.putUnapplyPayment

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

• payments.putUpdatePayment

  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.

• paymentTransactionLogs.objectGetPaymentTransactionLog

  Retrieves information about a specific payment transaction log.

• productFeatures.objectDeleteProductFeature
• productFeatures.objectGetProductFeature
• productRatePlanCharges.objectDeleteProductRatePlanCharge

  Deletes a product rate plan charge.

• productRatePlanCharges.objectGetProductRatePlanCharge
• productRatePlanCharges.objectPostProductRatePlanCharge

  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.

• productRatePlanCharges.objectPutProductRatePlanCharge

  Updates the information about a product rate plan charge.

• productRatePlanChargeTiers.objectGetProductRatePlanChargeTier
• productRatePlanChargeTiers.objectPutProductRatePlanChargeTier

  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.

• productRatePlans.getProductRatePlans

  Retrieves information about all product rate plans of a specific product.

  For a use case of this operation, see Retrieve the product catalog.

• productRatePlans.objectDeleteProductRatePlan
• productRatePlans.objectGetProductRatePlan
• productRatePlans.objectPostProductRatePlan
• productRatePlans.objectPutProductRatePlan
• products.objectDeleteProduct
• products.objectGetProduct
• products.objectPostProduct
• products.objectPutProduct
• quotesDocument.postQuotesDocument

  The document call generates a quote document and returns the generated document URL. You can directly access the generated quote file through the returned URL.

  The document call should be only used from Zuora Quotes.

  File Size Limitation

  The maximum export file size is 2047MB. If you have large data requests that go over this limit, you will get the following 403 HTTP response code from Zuora: security:max-object-size>2047MB</security:max-object-size>

  Submit a request at Zuora Global Support if you require additional assistance.

  We can work with you to determine if large file optimization is an option for you.

• ramps.getRampByRampNumber

  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.

• ramps.getRampMetricsByOrderNumber

  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.

• ramps.getRampMetricsByRampNumber

  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.

• ramps.getRampMetricsBySubscriptionKey

  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.

• ramps.getRampsBySubscriptionKey

  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.

• ratePlanCharges.objectGetRatePlanCharge
• ratePlanCharges.objectPutRatePlanCharge
• ratePlanChargeTiers.objectGetRatePlanChargeTier
• ratePlans.objectGetRatePlan
• refundInvoicePayments.objectGetRefundInvoicePayment
• refunds.deleteRefund

  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 or Error status.

  If you have the Invoice Settlement feature enabled, refunds applied to credit balance cannot be deleted.

• refunds.getRefund

  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.

• refunds.getRefundItemPart

  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.

• refunds.getRefundItemParts

  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.

• refunds.getRefundPart

  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.

• refunds.getRefundParts

  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.

• refunds.getRefunds

  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

• refunds.objectDeleteRefund
• refunds.objectGetRefund
• refunds.objectPostRefund

  Creates a refund.

  If you have the Invoice Settlement feature enabled, you can use this operation to unapply the payment from an invoice or multiple invoices, and refund the payment.

  If the unapplied payment is left in the following scenarios, you have to reapply the unapplied payment to the original invoices:

  • An electronic refund in Processing status is handled to change to Error. An unapplied payment is left.
  • An electronic refund gets to Error, and payment reapplying fails due to the concurrent issue.
  • The refund canceling operation updates the status of a refund from Processed to Canceled. When it is successful, an unapplied payment is left.
• refunds.objectPutRefund
• refunds.putCancelRefund

  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.

• refunds.putUpdateRefund

  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.

• refundTransactionLogs.objectGetRefundTransactionLog
• revenueEvents.getRevenueEventDetails

  This REST API reference describes how to get revenue event details by specifying the revenue event number. Request and response field descriptions and sample code are provided.

• revenueEvents.getRevenueEventForRevenueSchedule

  This REST API reference describes how to get all revenue events in a revenue schedule by specifying the revenue schedule number. Request and response field descriptions and sample code are provided.

• revenueItems.getRevenueItemsByChargeRevenueEventNumber

  This REST API reference describes how to get the details of each revenue item in a revenue event by specifying the revenue event number. Request and response field descriptions and sample code are provided.

• revenueItems.getRevenueItemsByChargeRevenueSummaryNumber

  This REST API reference describes how to get the details for each revenue item in a charge revenue summary by specifying the charge revenue summary number. Request and response field descriptions and sample code are provided.

• revenueItems.getRevenueItemsByRevenueSchedule

  This REST API reference describes how to get the details for each revenue items in a revenue schedule by specifying the revenue schedule number. Request and response field descriptions and sample code are provided.

• revenueItems.putCustomFieldsonRevenueItemsByRevenueEvent

  This REST API reference describes how to update custom fields on revenue items by specifying the revenue event number. Request and response field descriptions and sample code are provided.

• revenueItems.putCustomFieldsonRevenueItemsByRevenueSchedule

  This REST API reference describes how to update custom fields on revenue Items by specifying the revenue schedule number. Request and response field descriptions and sample code are provided.

• revenueRules.getRevenueAutomationStartDate

  Describes how to get the revenue automation start date. Request and response field descriptions and sample code are provided.

• revenueRules.getRevenueRecRulebyProductRatePlanCharge

  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 revenue recognition rule associated with a production rate plan charge by specifying the charge ID.

• revenueRules.getRevenueRecRules

  Retrieves the revenue recognition rule associated with a subscription charge by specifying the charge ID. Request and response field descriptions and sample code are provided.

• revenueSchedules.deleteRs

  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.

• revenueSchedules.getRs

  Retrieves the details of a revenue schedule by specifying the revenue schedule number. Request and response field descriptions and sample code are provided.

• revenueSchedules.getRSbyCreditMemoItem

  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 details about a revenue schedule by specifying a valid credit memo item ID.

• revenueSchedules.getRSbyDebitMemoItem

  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 details about a revenue schedule by specifying a valid debit memo item ID.

• revenueSchedules.getRSbyInvoiceItem

  Retrieves the details of a revenue schedule by specifying the invoice item ID.

• revenueSchedules.getRSbyInvoiceItemAdjustment

  Retrieves the details of a revenue schedule by specifying a valid invoice item adjustment identifier. Request and response field descriptions and sample code are provided.

• revenueSchedules.getRSbyProductChargeAndBillingAccount

  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 details about all revenue schedules of a product rate plan charge by specifying the charge ID and billing account ID.

• revenueSchedules.getRSforSubscCharge

  Retrieves the revenue schedule details by specifying subscription charge ID. Request and response field descriptions and sample code are provided

• revenueSchedules.postRSforCreditMemoItemDistributeByDateRange

  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 revenue schedule for a credit memo item, and automatically distribute the revenue by specifying the recognition start and end dates.

• revenueSchedules.postRSforCreditMemoItemManualDistribution

  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 revenue schedule for a credit memo item, and manually distribute the revenue.

• revenueSchedules.postRSforDebitMemoItemDistributeByDateRange

  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 revenue schedule for a debit memo item, and automatically distribute the revenue by specifying the recognition start and end dates.

• revenueSchedules.postRSforDebitMemoItemManualDistribution

  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 revenue schedule for a debit memo item, and manually distribute the revenue.

• revenueSchedules.postRSforInvoiceItemAdjustmentDistributeByDateRange

  Creates a revenue schedule for an Invoice Item Adjustment and distribute the revenue by specifying the recognition start and end dates.

• revenueSchedules.postRSforInvoiceItemAdjustmentManualDistribution

  Creates a revenue schedule for an Invoice Item Adjustment and manually distribute the revenue.

• revenueSchedules.postRSforInvoiceItemDistributeByDateRange

  Creates a revenue schedule for an Invoice Item and distribute the revenue by specifying the recognition start and end dates.

• revenueSchedules.postRSforInvoiceItemManualDistribution

  Creates a revenue schedule for an Invoice Item and manually distribute the revenue.

• revenueSchedules.postRSforSubscCharge

  Creates a revenue schedule by specifying the subscription charge. This method is for custom unlimited revenue recognition only.

  Note: You can create a maximum of 3,000 revenue schedules for a subscription charge.

• revenueSchedules.putRevenueAcrossAp

  Distributes revenue by specifying the revenue schedule number. Request and response field descriptions and sample code are provided.

• revenueSchedules.putRevenueByRecognitionStartandEndDates

  Distributes revenue by specifying the recognition start and end dates. Request and response field descriptions and sample code are provided.

• revenueSchedules.putRevenueSpecificDate

  Distributes revenue on a specific recognition date. Request and response field descriptions and sample code are provided.

• revenueSchedules.putRsBasicInfo

  Retrieves basic information of a revenue schedule by specifying the revenue schedule number. Request and response field descriptions and sample code are provided.

• rsaSignatures.postDecryptRsaSignatures

  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.

• rsaSignatures.postRsaSignatures

  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.

• sequenceSets.deleteSequenceSet

  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.

• sequenceSets.getSequenceSet

  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.

• sequenceSets.getSequenceSets

  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.

• sequenceSets.postSequenceSets

  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.

• sequenceSets.putSequenceSet

  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.

• settings.getListAllSettings

  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 availabe settings in csv format, include Accept in the header parameters and set it to application/csv.

  See a 200 response sample in JSON format.

  See a 200 response sample in CSV format.

  You can find a specific operate of an available setting item in your tenant from the 200 response body of this call. See the following tutorials 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
  • Age Buckets:
    • Get Age Buckets
    • Update Age Buckets
  • Invoice Templates:
    • Get a specific Invoice Template
    • Get all Invoice Templates
    • Create a new Invoice Template
  • Communications Profiles:
    • Get all Communication Profiles
    • Create a new Communication Profile
    • Modify a Communication Profile
    • Get all Notifications under a particular Communication Profile
  • 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
  • Custom Fields:
    • View all custom fields
    • View custom fields of a specific object
    • Update custom fields of a specific object
• settings.postProcessSettingsBatchRequest

  Submit a batch of settings requests by this single API operation.

  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.

• subscriptionProductFeatures.objectGetSubscriptionProductFeature
• subscriptions.getSubscriptionsByAccount

  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.

• subscriptions.getSubscriptionsByKey

  This REST API reference describes how to retrieve detailed information about a specified subscription in the latest version.

• subscriptions.getSubscriptionsByKeyAndVersion

  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.

• subscriptions.objectDeleteSubscription
• subscriptions.objectGetSubscription
• subscriptions.objectPutSubscription
• subscriptions.postPreviewSubscription

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

• subscriptions.postSubscription

  This REST API reference 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. Otherwise, an error occurs.

  If invoiceCollect is true, the call will not return success = true unless the subscription, invoice, and payment are all successful.

  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

• subscriptions.putCancelSubscription

  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. Otherwise, an error occurs.

• subscriptions.putRenewSubscription

  Renews a termed subscription using existing renewal terms.

  Note: If you have the Invoice Settlement feature enabled, it is best practice to set the zuora-version parameter to 211.0 or later. Otherwise, an error occurs.

• subscriptions.putResumeSubscription

  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. Otherwise, an error occurs.

• subscriptions.putSubscription

  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

  Notes

  • The Update Subscription call creates a new subscription, which has the old subscription number but a new subscription ID. The old subscription is canceled but remains in the system.
  • 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. 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.

• subscriptions.putSuspendSubscription

  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. Otherwise, an error occurs.

• subscriptions.putUpdateSubscriptionCustomFieldsOfASpecifiedVersion

  Updates the custom fields of a specified subscription version.

• summaryJournalEntries.deleteSummaryJournalEntry

  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.

• summaryJournalEntries.getAllSummaryJournalEntries

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

• summaryJournalEntries.getSummaryJournalEntry

  This REST API reference describes how to get information about a summary journal entry by its journal entry number.

• summaryJournalEntries.postSummaryJournalEntry

  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.
• summaryJournalEntries.putBasicSummaryJournalEntry

  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.

• summaryJournalEntries.putSummaryJournalEntry

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

• taxationItems.deleteTaxationItem

  Deletes a specific taxation item by ID.

• taxationItems.getTaxationItem

  Retrieves the information about a specific taxation item by ID.

• taxationItems.objectDeleteTaxationItem
• taxationItems.objectGetTaxationItem
• taxationItems.objectPostTaxationItem
• taxationItems.objectPutTaxationItem
• taxationItems.putTaxationItem

  Updates a specific taxation item by ID.

• transactions.getTransactionInvoice

  Retrieves invoices for a specified account. Invoices are returned in reverse chronological order by updatedDate.

  For a use case of this operation, see View invoices.

• transactions.getTransactionPayment

  Retrieves payments for a specified account. Payments are returned in reverse chronological order by updatedDate.

• unitOfMeasure.objectDeleteUnitOfMeasure
• unitOfMeasure.objectGetUnitOfMeasure
• unitOfMeasure.objectPostUnitOfMeasure
• unitOfMeasure.objectPutUnitOfMeasure
• usage.getUsage

  This REST API reference describes how to retrieve usage details for an account. Usage data is returned in reverse chronological order.

• usage.objectDeleteUsage
• usage.objectGetUsage
• usage.objectPostUsage
• usage.objectPutUsage
• usage.postUsage

  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.

  For a use case of this operation, see Upload usage records.

  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.

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

• users.getEntitiesUserAccessible

  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.

  Retrieves detailed information about all the entities that a user has permission to access.

  User Access Permission

  You can make the call as any entity user.

• users.putAcceptUserAccess

  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.

  Accepts user access to an entity.

  User Access Permission

  You must make the calls as an administrator of the entity that you want to accept the user access to.

• users.putDenyUserAccess

  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.

  Denies a user access to an entity.

  User Access Permission

  You must make the calls as an administrator of the entity that you want to deny the user access to.

• users.putSendUserAccessRequests

  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.

  Sends access requests to the entities that a user wants to access.

  User Access Permission

  You must make the call as an administrator of the entity, in which the request user is created. Also, this administrator must have the permission to access the entities that the request user wants to access.

• workflows.deleteWorkflow

  Deletes a specific workflow by its ID.

• workflows.getWorkflow

  Retrieves information about a specific workflow by its ID.

• workflows.getWorkflowExport

  Export a Workflow in a JSON document. This document can be used to create a copy of this workflow.

• workflows.getWorkflows

  Retrieves a list of workflows available in your Zuora tenant.

• workflows.getWorkflowsTask

  Retrieves a specific workflow task by its ID.

• workflows.getWorkflowsTasks

  Retrieves a list of workflow tasks available in your Zuora tenant.

• workflows.getWorkflowsUsages

  Gets workflow task usage sorted by day within a specified time frame.

• workflows.patchUpdateWorkflow

  Updates the definition of a specific workflow by its ID, which allows you to configure the settings of a workflow via API.

• workflows.postRunWorkflow

  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.

  To learn about how to define parameters, see Configure the settings of a workflow.

• workflows.postWorkflowImport

  Creates a copy of a workflow using the exported JSON document of the original workflow.

• workflows.postWorkflowsTaskRerun

  Reruns a specific workflow task by its ID.

• workflows.putWorkflowsTasksUpdate

  Updates a group of workflow tasks.

• zuoraRevenueIntegration.putRevProAccountingCodes

  Update the Zuora Revenue accounting code that corresponds to a specific Product Rate Plan Charge Id in Zuora Billing.

• openapi.previewSpec

  Preview an OpenAPI document before adding it as a source

• openapi.addSource

  Add an OpenAPI source and register its operations as tools