This API Reference contains the API operations that we no longer recommend you use.
Although we do not recommend these API operations, you can continue to use these API operations if you have integrated with them. You are not required to make changes to your existing integration.
For more information about this change, see this Community post.
Actions are operations that are batch in nature. For example, the "create", "update", "delete", and other operations allow changes to up-to 50 objects at a time. The "query" operation will return up-to 2000 result records back at a time, before requiring additional pages of data to be returned via a subsequent "queryMore" operation.
The default WSDL version for Actions is 79. If you want to change the WSDL version, set the X-Zuora-WSDL-Version header. To find out in which WSDL version a particular object or field was introduced, see Zuora SOAP API Version History.
Note: Actions do not support the Invoice Settlement feature. This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. Actions also do not support the Orders feature.
Modifies a subscription by creating Amendment objects. However, to modify a subscription, Zuora recommends that you use the Create an order operation instead of this action.
The Amend action cannot modify the custom fields on the Subscription object. You can use the Create an order operation 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:
ContractEffectiveDateNameSubscriptionIdTypeAdditionally, the value of SubscriptionId must be the same for each Amendment object. You cannot use this operation to update multiple subscriptions. 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.
Amendment Preview To view taxation item data for invoices and credit memos in the amendment preview response, you need to set the X-Zuora-WSDL-Version request header to 120 or later.
Specifies whether the call fails if the request body contains unknown fields. With rejectUnknownFields set to true, Zuora returns a 400 response if the request body contains unknown fields. The body of the 400 response is:
{
"message": "Error - unrecognised fields"
}By default, Zuora ignores unknown fields in the request body.
Specify a unique idempotency key if you want to perform an idempotent POST or PATCH request. Do not use this header in other request types.
With this header specified, the Zuora server can identify subsequent retries of the same request using this value, which prevents the same operation from being performed multiple times by accident.
Include the Accept-Encoding: gzip header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response.
If specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a Content-Encoding header with the compression algorithm so that your client can decompress it.
Include the Content-Encoding: gzip header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload.
The value is in the Bearer {token} format where {token} is a valid OAuth token generated by calling Create an OAuth token.
An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.
A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.
The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').
The value of this field must be an array that contains a single AmendRequest object. To specify multiple Amendment objects, use the Amendments field of the AmendRequest object.
curl -i -X POST \
'https://developer.zuora.com/_mock/v1-api-reference/older-api/v1/action/amend?rejectUnknownFields=false' \
-H 'Accept-Encoding: string' \
-H 'Authorization: string' \
-H 'Content-Encoding: string' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: string' \
-H 'X-Zuora-WSDL-Version: 79' \
-H 'Zuora-Entity-Ids: string' \
-H 'Zuora-Track-Id: string' \
-d '{
"requests": [
{
"Amendments": [
{
"Name": "Enable auto-renewal",
"SubscriptionId": "8ad08ad590a1d7900190a56d87634f5a",
"Type": "TermsAndConditions",
"ContractEffectiveDate": "2024-07-12",
"AutoRenew": true
}
]
}
]
}'This header is returned if you specify the Accept-Encoding: gzip request header and the response contains over 1000 bytes of data.
Note that only the following MIME types support gzipped responses:
application/jsonapplication/xmltext/htmltext/csvtext/plainThe request limit quota for the time window closest to exhaustion. See rate limits for more information.
The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.
The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.
The Zuora internal identifier of the API call. You cannot control the value of this header.
{ "results": [ { … } ] }
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.
To access this feature, see Enable Splitting Invoices for steps.
To split a draft invoice into multiple split invoices:
You need to create InvoiceSplitItem objects and an InvoiceSplit object before you can use the execute call.
Specifies whether the call fails if the request body contains unknown fields. With rejectUnknownFields set to true, Zuora returns a 400 response if the request body contains unknown fields. The body of the 400 response is:
{
"message": "Error - unrecognised fields"
}By default, Zuora ignores unknown fields in the request body.
Specify a unique idempotency key if you want to perform an idempotent POST or PATCH request. Do not use this header in other request types.
With this header specified, the Zuora server can identify subsequent retries of the same request using this value, which prevents the same operation from being performed multiple times by accident.
Include the Accept-Encoding: gzip header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response.
If specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a Content-Encoding header with the compression algorithm so that your client can decompress it.
Include the Content-Encoding: gzip header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload.
The value is in the Bearer {token} format where {token} is a valid OAuth token generated by calling Create an OAuth token.
An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.
A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.
The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').
The ID of the object. Values: a valid InvoiceSplit object ID.
curl -i -X POST \
'https://developer.zuora.com/_mock/v1-api-reference/older-api/v1/action/execute?rejectUnknownFields=false' \
-H 'Accept-Encoding: string' \
-H 'Authorization: string' \
-H 'Content-Encoding: string' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: string' \
-H 'X-Zuora-WSDL-Version: 79' \
-H 'Zuora-Entity-Ids: string' \
-H 'Zuora-Track-Id: string' \
-d '{
"ids": [
"2c93808457d787030157e031d5844c53"
],
"synchronous": false,
"type": "InvoiceSplit"
}'This header is returned if you specify the Accept-Encoding: gzip request header and the response contains over 1000 bytes of data.
Note that only the following MIME types support gzipped responses:
application/jsonapplication/xmltext/htmltext/csvtext/plainThe request limit quota for the time window closest to exhaustion. See rate limits for more information.
The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.
The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.
The Zuora internal identifier of the API call. You cannot control the value of this header.
The ID of the object in the call. The value is the same as the value you provide in the ids field for the request.
[ { "Success": true, "Id": "2c93808457d787030157e031d5844c53" } ]
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.
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.
Specifies whether the call fails if the request body contains unknown fields. With rejectUnknownFields set to true, Zuora returns a 400 response if the request body contains unknown fields. The body of the 400 response is:
{
"message": "Error - unrecognised fields"
}By default, Zuora ignores unknown fields in the request body.
Specify a unique idempotency key if you want to perform an idempotent POST or PATCH request. Do not use this header in other request types.
With this header specified, the Zuora server can identify subsequent retries of the same request using this value, which prevents the same operation from being performed multiple times by accident.
Include the Accept-Encoding: gzip header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response.
If specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a Content-Encoding header with the compression algorithm so that your client can decompress it.
Include the Content-Encoding: gzip header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload.
The value is in the Bearer {token} format where {token} is a valid OAuth token generated by calling Create an OAuth token.
An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.
A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.
The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').
curl -i -X POST \
'https://developer.zuora.com/_mock/v1-api-reference/older-api/v1/action/generate?rejectUnknownFields=false' \
-H 'Accept-Encoding: string' \
-H 'Authorization: string' \
-H 'Content-Encoding: string' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: string' \
-H 'X-Zuora-WSDL-Version: 79' \
-H 'Zuora-Entity-Ids: string' \
-H 'Zuora-Track-Id: string' \
-d '{
"objects": [
{
"AccountId": "2c93808457d787030157e0306be53a75",
"InvoiceDate": "2016-10-20",
"TargetDate": "2016-10-20"
}
],
"type": "Invoice"
}'This header is returned if you specify the Accept-Encoding: gzip request header and the response contains over 1000 bytes of data.
Note that only the following MIME types support gzipped responses:
application/jsonapplication/xmltext/htmltext/csvtext/plainThe request limit quota for the time window closest to exhaustion. See rate limits for more information.
The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.
The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.
The Zuora internal identifier of the API call. You cannot control the value of this header.
[ { "Success": true, "Id": "2c93808457d787030157e0306cd13a86" } ]
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:
If the effective date is in the future, the invoices will not be generated, and there will be no invoice number.
Name, Number, and ID
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 numbermust be unique. If they are not, an error will occur.
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.
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.
To view taxation item data for invoices and credit memos in the subscription preview response, you need to set the X-Zuora-WSDL-Version request header to 120 or later.
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.
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.
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.
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.
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.
Specifies whether the call fails if the request body contains unknown fields. With rejectUnknownFields set to true, Zuora returns a 400 response if the request body contains unknown fields. The body of the 400 response is:
{
"message": "Error - unrecognised fields"
}By default, Zuora ignores unknown fields in the request body.
Specify a unique idempotency key if you want to perform an idempotent POST or PATCH request. Do not use this header in other request types.
With this header specified, the Zuora server can identify subsequent retries of the same request using this value, which prevents the same operation from being performed multiple times by accident.
Include the Accept-Encoding: gzip header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response.
If specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a Content-Encoding header with the compression algorithm so that your client can decompress it.
Include the Content-Encoding: gzip header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload.
The value is in the Bearer {token} format where {token} is a valid OAuth token generated by calling Create an OAuth token.
An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.
A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.
The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').
This is the Account object containing the information for this particular subscription. It has all the information needed to create an account for a subscription.
Values: A valid account.
Unique account number assigned to the account.
Character limit: 50
Values: one of the following:
List of additional email addresses to receive emailed invoices.
Character limit: 120
Values: comma-separated list of email addresses
Indicates if associated invoices can be edited.
Character limit: 5
Values: true, false (default if left null)
Indicates if future payments are automatically collected when they're due during a Payment Run.
Character limit: 5
Values: true, false (default)
Organizes your customer accounts into groups to optimize
\ your billing and payment operations.\n\n\nCharacter limit: 20\n\n
\nValues:any system-defined batch (Batch1 - Batch50 or by name).
Note: By default, you have 50 configurable account batches. To increase the limit to 200 batches, you must have the <a href="https://knowledgecenter.zuora.com/Zuora_Central_Platform/Performance_Booster_Elite" target="_blank">Performance Booster Elite</a> package.
Billing cycle day setting option.
Character limit: 9
Values: AutoSet, ManualSet
Billing cycle day (BCD) on which bill runs generate invoices for the account.
Character limit: 2
Values: any activated system-defined bill cycle day (1 - 31)
Associates the account with a specified communication profile.
Character limit: 32
Values: a valid communication profile ID
CRM account ID for the account. A CRM is a customer relationship management system, such as Salesforce.com.
Character limit: 100
Values: a string of 100 characters or fewer
Currency that the customer is billed in. See a currency value defined in the Zuora Ui admin settings
Name of the account's customer service representative, if applicable.
Character limit: 50
Values: a string of 50 characters or fewer
ID of the default payment method for the account. This field is only required if the AutoPay field is set to true.
Character limit: 32
Values: A valid ID for an existing payment method. This field does not support external payment methods.
Internal identifier of an existing account. Only set this field if you want to assign the subscription to an existing account.
Indicates if the customer wants to receive invoices through email. Character limit: 5
Values: true, false (default if left null)
Indicates if the customer wants to receive printed invoices, such as through postal mail.
Character limit: 5
Values: true, false (default if left null)
The ID of the invoice template. Each customer account can use a specific invoice template for invoice generation.
Character limit: 32
Values: a valid template ID configured in Z-Billing Settings To find the ID of your current invoice template: In Zuora, navigate to Settings > Z-Billing > Manage Invoice Rules and Templates and click **Show Id **next to the template you want to use.
The date when the previous invoice was generated for the account. The field value is null if no invoice has ever been generated for the account.
Character limit: 29
Values: automatically generated
Name of the account as displayed in the Zuora UI.
Character limit: 255
Values: a string of 255 characters or fewer
Comments about the account.
Character limit: 65,535
Values: a string of 65,535 characters
Identifier of the parent customer account for this Account object. Use this field if you have customer hierarchy enabled.
Character limit: 32
Values: a valid account ID
Gateway used for processing electronic payments and refunds. This field is only required if there is no default payment gateway is defined in the tenant.
Character limit: 40
Values: one of the following:
Indicates when the customer pays for subscriptions.
Character limit: 100
Values: a valid, active payment term defined in the web-based UI administrative settings
The number of the purchase order associated with this account. Purchase order information generally comes from customers.
Character limit: 100
Values: a string of 100 characters or fewer
The name of the sales representative associated with this account, if applicable.
Character limit: 50
Values: a string of 50 characters or fewer
Unique code that identifies a company account in Avalara. Use this field to calculate taxes based on origin and sold-to addresses in Avalara. This feature is in Limited Availability. If you wish to have access to the feature, submit a request at Zuora Global Support.
Character limit: 50
Values: a valid company code
ID of your customer's tax exemption certificate.
Character limit: 32
Values: a string of 32 characters or fewer
Type of the tax exemption certificate that your customer holds. Character limit: 32
Values: a string of 32 characters or fewer
Description of the tax exemption certificate that your customer holds.
Character limit: 500
Values: a string of 500 characters or fewer
Date when the the customer's tax exemption starts.
Character limit: 29 Version notes: requires Z-Tax
Date when the customer's tax exemption certificate expires Character limit: 29 Version notes: requires Z-Tax
Indicates the jurisdiction in which the customer's tax exemption certificate was issued.
Character limit: 32
Values: a string of 32 characters or fewer
Status of the account's tax exemption. This field is only required if you use Zuora Tax. This field is not available if you do not use Zuora Tax.
Character limit: 19
Values: one of the following:
YesNoPendingVerificationTotal balance of the account's invoices.
Character limit: 16
Values: a valid currency value
EU Value Added Tax ID. This feature is in Limited Availability. If you wish to have access to the feature, submit a request at Zuora Global Support.
Character limit: 25
Values: a valid Value Added Tax ID
Value of the Class field for the corresponding customer account in NetSuite. Only available if you have installed the Zuora Connector for NetSuite.
Value of the Customer Type field for the corresponding customer account in NetSuite. The Customer Type field is used when the customer account is created in NetSuite. Only available if you have installed the Zuora Connector for NetSuite.
Value of the Department field for the corresponding customer account in NetSuite. Only available if you have installed the Zuora Connector for NetSuite.
ID of the corresponding object in NetSuite. Only available if you have installed the Zuora Connector for NetSuite.
Status of the account's synchronization with NetSuite. Only available if you have installed the Zuora Connector for NetSuite.
Value of the Location field for the corresponding customer account in NetSuite. Only available if you have installed the Zuora Connector for NetSuite.
Value of the Subsidiary field for the corresponding customer account in NetSuite. The Subsidiary field is required if you use NetSuite OneWorld. Only available if you have installed the Zuora Connector for NetSuite.
Date when the account was sychronized with NetSuite. Only available if you have installed the Zuora Connector for NetSuite.
Specifies whether the account should be synchronized with NetSuite. Only available if you have installed the Zuora Connector for NetSuite.
Custom fields of the Account object. The name of each custom field has the form <code>customField__c</code>. Custom field names are case sensitive. See Manage Custom Fields for more information.
This is the object that contains the contact associated with this account in the Account's BillToId field. This field is only required if the account does not exist. Values: A valid contact for the account.
This is the object defining the payment details for the Account. The Account will be updated with this payment as the default payment method. Use this field to create an electronic payment method for the account. A payment gateway must be enabled. Values: A valid electronic PaymentMethod.
Only used if you want to call this operation in preview mode. After a call in preview mode is completed, Zuora will roll back the subscription and return only the temporary invoice data.
Unless otherwise specified, this field defaults to the information in the BillToContact field.
Values: A valid contact.
This optional object specifies parameters related to invoicing - whether to immediately generate an invoice and collect payment, and whether the invoice should cover all subscriptions or just this new subscription. The default behavior is to invoice immediately for all the account's subscriptions, with the current date as the target date, and immediately collect payment if the account's AutoPay flag is true.
Values: A valid SubscribeOptions object.
This object contains the information on the contract's dates and terms.
Values: A valid SubscriptionData object.
Container for custom fields of a Rate Plan object.
The ID of the amendment associated with the rate plan. This field only applies to amendment rate plans.
Character limit: 32
Values: a valid amendment ID
The ID of the subscription rate plan modified by the amendment. This field only applies to amendment rate plans.
Character limit: 32
Values: a valid rate plan ID
The type of amendment associated with the rate plan. This field only applies to amendment rate plans.
Character limit: 18
Values: inherited from Amendment.Type
The ID of the Zuora user who created the RatePlan object.
Character limit: 32
Values: automatically generated
The date when the RatePlan object was last updated.
Character limit: 29
Values: automatically generated
The unique identifier for the rate plan purchased on a third-party store. This field is used to represent a subscription rate plan created through third-party stores.
The name of the rate plan. Leave this null in a subscribe call to inherited the ProductRatePlan.Name field value.
Character limit: 100
Values: a string of 100 characters or fewer or inherited from ProductRatePlan.Name
The ID of the associated product rate plan.
Character limit: 32
Values: a valid product rate plan ID
The ID of the subscription that the rate plan belongs to.
Character limit: 32
Values: a valid subscription ID
The ID of the user who last updated the rate plan.
Character limit: 32
Values: automatically generated
The date when the rate plan was last updated.
Character limit: 29
Values: automatically generated
Custom fields of the Rate Plan object. The name of each custom field has the form <code>customField__c</code>. Custom field names are case sensitive. See Manage Custom Fields for more information.
Container for Subscription fields provided by Zuora Quotes.
This field can be updated when Status is Draft.
A filter option for querying all subscriptions under the same account hierarchy.
Character limit: 32
Values: a valid account ID
This field can be updated when Status is Draft. Indicates if the subscription automatically renews at the end of the term. This field is only required if the TermType field is set to TERMED.
Values: true, false
The date of the amendment that canceled the subscription.
Values: inherited from Amendment.EffectiveDate
The date when the customer accepts the contract. This field can be updated when Status is Draft.
This field is only required if the Require Service Activation of Orders? Setting is set to Yes. If this setting is set to Yes:
DRAT status.The date when the contract takes effect. This field can be updated when Status is Draft.
Note: This field is required in the subscribe call. If you set the value of this field to null and both the ServiceActivationDate and ContractAcceptanceDate fields are not required, the subscribe call still returns success, but the new subscription is in DRAFT status. To activate the subscription, you must set a valid date to this field.
The user ID of the person who created the subscription.
Character limit: 32
Values: automatically generated
The date the subscription was created. This value is the same as the OriginalCreatedDate value until the subscription is amended.
Values: automatically generated
The account ID that created the subscription or the amended subscription.
Character limit: 32
Values: automatically generated
The account ID that owns the invoices associated with the subscription or the amended subscription.
Character limit: 32
Values: automatically generated
The length of the period for the current subscription term. This field is only required If the TermType field is set to TERMED and its value must be greater than 0. If TermType is set to EVERGREEN, this value is ignored. Default is 0.
Character limit: 20
Values: automatically generated
The period type for the current subscription term. This field is used with the CurrentTerm field to specify the current subscription term.
Values:
Month (default)YearDayWeekAn enum field on the Subscription object to indicate the name of a third-party store. This field is used to represent subscriptions created through third-party stores.
The length of the period for the first subscription term. This field can be updated when Status is Draft. If you use the subscribe call, this field is required.
This field is only required if the TermType field is set to TERMED.
Character limit: 20
Values: any valid number. The default value is 0.
The period type for the first subscription term.
Values:
Month (default)YearDayWeekNote:
Status is Draft.InitialTerm field to specify the initial subscription term.This field can be updated when Status is Draft.
Determines if the subscription is invoiced separately. If TRUE, then all charges for this subscription are collected into the subscription's own invoice.
Values: TRUE, FALSE (default)
The last booking date of the subscription object. This field is writable only when the subscription is newly created as a first version subscription. You can override the date value when creating a subscription through the Subscribe and Amend API or the subscription creation UI (non-Orders). Otherwise, the default value today is set per the user's timezone. The value of this field is as follows:
The unique identifier of the subscription. If you don't specify a value, then Zuora generates a name automatically. Whether auto-generated or manually specified, the subscription name must be unique. Otherwise an error will occur. You can change this value only when the subscription is in Draft status. Once the subscription is activated, you can't change this value, nor can you use this value for a different subscription.
Character limit: 100
Values: one of the following:
Use this field to record comments about the subscription.
Character limit: 500
Values: a string of 500 characters or fewer
The date when the subscription was originally created. This value is the same as the CreatedDate value until the subscription is amended.
Values: automatically generated
The original ID of this subscription.
Values: automatically generated
The subscription ID immediately prior to the current subscription.
Character limit: 32
Values: automatically generated
This field can be updated when Status is Draft. Specifies whether a termed subscription will remain termed or change to evergreen when it is renewed.
This field is only required if the TermType field is set to TERMED.
Values: RENEW_WITH_SPECIFIC_TERM (default), RENEW_TO_EVERGREEN
The length of the period for the subscription renewal term. This field can be updated when Status is Draft. If you use the subscribe call, this field is required.
This field is only required if the TermType field is set to TERMED.
Character limit: 20
Values: one of the following:
0The period type for the subscription renewal term.
Values:
Month (default)YearDayWeekNote:
Draft.The date when the subscription is activated. This field can be updated when Status is Draft. This field is only required if the Require Service Activation of Orders? Setting is set to Yes. If this setting is set to Yes:
DRAT status.Character limit: 29
The status of the subscription.
Character limit: 17
Values: automatically generated
Possible values: one of the following:
DraftPendingActivationPendingAcceptanceActiveCancelledExpiredSuspendedThe date when the subscription term ends, where the subscription ends at midnight the day before. For example, if the SubscriptionEndDate is 12/31/2016, the subscriptions ends at midnight (00:00:00 hours) on 12/30/2016. This date is the same as the term end date or the cancelation date, as appropriate.
Character limit: 29
Values: automatically generated
The date when the subscription term starts. This date is the same as the start date of the original term, which isn't necessarily the start date of the current or new term.
Character limit: 29
Values: automatically generated
This field can be updated when Status is Draft. The date when the subscription term ends. If the subscription is evergreen, the TermEndDate value is null or is the cancelation date, as appropriate.
Character limit: 29
Values: automatically generated
This field can be updated when Status is Draft. The date when the subscription term begins. If this is a renewal subscription, then this date is different from the subscription start date. If you don't specify a value, then Zuora uses ContractEffectiveDate automatically.
Character limit: 29
This field can be updated when Status is Draft. Indicates if a subscription is termed or evergreen. A termed subscription has a specific end date and requires manual renewal. An evergreen subscription doesn't have an end date and doesn't need renewal. This field can be updated when the subscription status is Draft.
Character limit: 9
Values: TERMED, EVERGREEN
The ID of the user who last updated the subscription. Character limit: 32 **Values: **automatically generated
The date when the subscription was last updated. Character limit: 29
Values: automatically generated
The version number of the subscription.
Values: automatically generated
The Bundle product structures from Zuora Quotes if you utilize Bundling in Salesforce. Do not change the value in this field.
The closing date of the Opportunity. This field is used in Zuora data sources to report on Subscription metrics. If the subscription originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.
The unique identifier of the Opportunity. This field is used in Zuora data sources to report on Subscription metrics. If the subscription originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.
The specific identifier for the type of business transaction the Quote represents such as New, Upsell, Downsell, Renewal or Churn. This field is used in Zuora data sources to report on Subscription metrics. If the subscription originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.
The unique identifier of the Quote. This field is used in Zuora data sources to report on Subscription metrics. If the subscription originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.
The Quote type that represents the subscription lifecycle stage such as New, Amendment, Renew or Cancel. This field is used in Zuora data sources to report on Subscription metrics. If the subscription originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.
ID of the corresponding object in NetSuite. Only available if you have installed the Zuora Connector for NetSuite.
Status of the subscription's synchronization with NetSuite. Only available if you have installed the Zuora Connector for NetSuite.
The NetSuite project that the subscription was created from. Only available if you have installed the Zuora Connector for NetSuite.
The NetSuite sales order than the subscription was created from. Only available if you have installed the Zuora Connector for NetSuite.
Date when the subscription was synchronized with NetSuite. Only available if you have installed the Zuora Connector for NetSuite.
Custom fields of the Subscription object. The name of each custom field has the form <code>customField__c</code>. Custom field names are case sensitive. See Manage Custom Fields for more information.
curl -i -X POST \
'https://developer.zuora.com/_mock/v1-api-reference/older-api/v1/action/subscribe?rejectUnknownFields=false' \
-H 'Accept-Encoding: string' \
-H 'Authorization: string' \
-H 'Content-Encoding: string' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: string' \
-H 'X-Zuora-WSDL-Version: 79' \
-H 'Zuora-Entity-Ids: string' \
-H 'Zuora-Track-Id: string' \
-d '{
"subscribes": [
{
"Account": {
"Name": "Amy Lawrence",
"Currency": "USD",
"BillCycleDay": 1,
"Batch": "Batch1",
"PaymentTerm": "Net 30"
},
"BillToContact": {
"FirstName": "Amy",
"LastName": "Lawrence",
"Country": "United States",
"State": "CA"
},
"PaymentMethod": {
"Type": "CreditCard",
"CreditCardType": "Visa",
"CreditCardNumber": "4111111111111111",
"CreditCardExpirationYear": 2030,
"CreditCardExpirationMonth": 12,
"CreditCardHolderName": "Amy Lawrence"
},
"SubscriptionData": {
"Subscription": {
"ContractEffectiveDate": "2024-07-01",
"TermType": "TERMED",
"InitialTerm": 12,
"RenewalTerm": 12
},
"RatePlanData": [
{
"RatePlan": {
"ProductRatePlanId": "8ad081dd9096ef9501909b40bb4e74a4"
}
}
]
}
}
]
}'This header is returned if you specify the Accept-Encoding: gzip request header and the response contains over 1000 bytes of data.
Note that only the following MIME types support gzipped responses:
application/jsonapplication/xmltext/htmltext/csvtext/plainThe request limit quota for the time window closest to exhaustion. See rate limits for more information.
The number of requests remaining in the time window closest to quota exhaustion. See rate limits for more information.
The number of seconds until the quota resets for the time window closest to quota exhaustion. See rate limits for more information.
The Zuora internal identifier of the API call. You cannot control the value of this header.
Container for credit memo data.
Note: This field is only available if you have the Invoice Settlement feature enabled and set the X-Zuora-WSDL-Version request header to 107 or later.
The ID of the credit memo.
Note: This field is only available if you have the Invoice Settlement feature enabled and set the X-Zuora-WSDL-Version request header to 107 or later.
The number of the credit memo.
Note: This field is only available if you have the Invoice Settlement feature enabled and set the X-Zuora-WSDL-Version request header to 107 or later.
The result of the credit memo.
Note: This field is only available if you have the Invoice Settlement feature enabled and set the X-Zuora-WSDL-Version request header to 107 or later.
[ { "Success": true, "AccountId": "8ad09be4909fc0f80190a0b18f85137e", "AccountNumber": "A00000118", "SubscriptionId": "8ad09be4909fc0f80190a0b1906b13c4", "SubscriptionNumber": "A-S00000138", "InvoiceId": "8ad09be4909fc0f80190a0b192ca13f9", "InvoiceNumber": "INV00000152", "InvoiceResult": { … }, "TotalTcv": 179.88, "TotalMrr": 14.99, "PaymentId": "8ad09be4909fc0f80190a0b193951425", "PaymentTransactionNumber": "5687098.81309958", "GatewayResponse": "This transaction has been approved by Test gateway.", "GatewayResponseCode": "Approved" } ]
Some operations in this section are similar to each other, but are provided for different use scenarios. You should choose the one that best suits your needs.
For example, the Create account operation is used to create an account with a credit card payment method, a bill-to contact, and optionally an sold-to contact or an associated subscription. If you want to create an account without creating any associated objects such as subscriptions, use CRUD: Create Account instead.
If you want to create an account and the associated subscription at the same time without providing credit card information, use the Subscribe action.
You can use amendments to modify subscriptions. However, Zuora recommends you to use the Create an order operation to do so.
This section contains the CRUD bill run operations, including:
The Charge Revenue Summary represents a summary of revenue amounts from all revenue schedules on the whole subscription charge. For example, revenue for one-time setup charges, recurring charges, and overages.
You can list all details of a charge revenue summary or retrieve a charge revenue summary by charge ID through the REST API.
A communication profile enables you to send specific event-driven notifications to targeted customer accounts. For more information, see Communication profiles.
You can manage communication profiles using the REST API:
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.
You can create, update, and retrieve 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.
Note: You can manage document properties for credit memos and debit memos only if you have the <a href="https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement" target="_blank">Invoice Settlement</a> feature enabled.
An entity represents a business unit that operates independently and can sell products to multiple countries. Each entity has its own Zuora environment in which the entity users can perform business operations independent of the other entities. In a multi-entity hierarchy, an entity can share certain business objects with the other entities. Users that are created in an entity can be granted access to the other entities with different roles and permissions.
Note: Entities are available only if you have the <a href="https://knowledgecenter.zuora.com/Billing/Tenant_Management/Multi-entity" target="_blank">Multi-entity</a> feature enabled. If you want to have access to the Multi-entity feature, submit a request at <a href=“http://support.zuora.com/” target=“_blank”>Zuora Global Support</a>.
If you want to share business objects across entities, you have to set up a connection between the source entity and the target entity first.
Note: Entity connections are available only if you have the <a href="https://knowledgecenter.zuora.com/Billing/Tenant_Management/Multi-entity" target="_blank">Multi-entity</a> feature enabled. If you want to have access to the Multi-entity feature, submit a request at <a href=“http://support.zuora.com/” target=“_blank”>Zuora Global Support</a>.
You can export items from Zuora to CSV or HTML files, such as large data sets, invoices, payments, and so on. Use the Export object and Export ZOQL queries to create an export file that you can download and use for charting, reporting, accounting, or for other business intelligence uses.
When you export data from Zuora, each exported file is available for download for 7 days. Export objects older than 90 days are automatically deleted.
After you have created a feature, you can add features to the products and subscriptions to enhance your product offerings.
To create features in the product catalog and use them in subscriptions and Zuora Quotes, you need to enable the following:
A Hash-based Message Authentication Code (HMAC) signature is a form of a digital signature. HMAC signatures start with a secret key that is shared between the sender and the recipient.
You can use the operation contained in this section to generate the unique signature and token values that are used to process CORS-enabled API calls.
An invoice adjustment modifies an existing invoice. You use an invoice adjustment to change the entire invoice. For example, you can apply a late fee to the invoice balance.
An invoice adjustment differs from an invoice item adjustment. An invoice item adjustment affects an individual charge or line item on an invoice. An invoice adjustment affects the invoice at the header-level.
Note: Invoice Adjustment is deprecated on Production in WSDL version 64.0. Zuora recommends that you use the Invoice Item Adjustment to adjust invoices. If you have the <a href="https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement" target="_blank">Invoice Settlement</a> feature enabled, this object is deprecated and only available for backward compatibility.
Invoice item adjustments allow you to adjust the invoice details, including taxes at the charge level, and have those adjustments reported in the system under the same accounting code as the items that are being adjusted.
Note: The <a href="https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/Invoice_Settlement" target="_blank">Invoice Settlement</a> feature is a replacement for Invoice Item Adjustments. We recommend that you enable Invoice Settlement to take advantage of the improved functionalities. If you have the Invoice Settlement feature enabled, the Invoice Item Adjustments feature is deprecated and invoice item adjustments are not presented in the UI. If you have to export data for invoice item adjustments, use <a href="https://knowledgecenter.zuora.com/Billing/Reporting/D_Data_Sources_and_Exports/D_Generate_a_Data_Source_Export" target="_blank">Data Source</a>, <a href="https://knowledgecenter.zuora.com/Central_Platform/Query/Data_Query" target="_blank">Data Query</a>, or REST API.
Invoices provides information about customers' accounts for invoices, for examples, dates, status, and amounts.
For more information about invoices, see <a href="https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/IA_Invoices/A1_Invoice_Introduction" target="_blank">Invoice</a>.
You can use the Retrieve a payment gateway transaction log operation to retrieve log data about all transactions processed through your setup payment gateways.
This section contains the Generate a quote document operation that should be only used from Zuora Quotes.
This operation generates a quote document and returns the generated document URL. You can directly access the generated quote file through the returned URL.
A rate plan charge tier is part of a subscription or an amendment to a subscription, and it comes from a product rate plan charge tier. A rate plan charge tier holds the prices for a rate plan charge. Each rate plan charge has at least one tier associated with it.
Rate plan charge tiers are sometimes called subscription rate plan charge tiers to distinguish them from product rate plan charge tiers. Rate plan charge tiers that are part of an amendment are sometimes called amendment rate plan charge tiers for the same reason. However, the object name is RatePlanChargeTier, not SubscriptionRatePlanChargeTier nor AmendmentRatePlanChargeTier: these latter two names don't exist.
A rate plan charge is part of a subscription or an amendment to a subscription, and it comes from a product rate plan charge. Like a product and its product rate plan charges, a subscription can have one or more rate plan charges. Rate plan charges represent the actual charges for the rate plans or services that you sell.
Rate plan charges are sometimes called subscription rate plan charges to distinguish them from product rate plan charges. Rate plan charges that are part of an amendment are sometimes called amendment rate plan charges for the same reason. The object name is RatePlanCharge – not SubscriptionRatePlanCharge nor AmendmentRatePlanCharge.
A rate plan is part of a subscription or an amendment to a subscription, and it comes from a product rate plan. Like a product and its product rate plans, a subscription can have one or more rate plans. Rate plans are sometimes called subscription rate plans. Rate plans that are part of an amendment are sometimes called amendment rate plans.
Rate plans represent a price or a collection of prices for a service you sell. An individual rate plan contains all charges specific to a particular subscription.
This section contains the CRUD: Retrieve a refund invoice payment operation. You can use this operation to retrieve information from Refund Invoice Payment and associated invoices, payments, and accounts.
This section contains the CRUD: Retrieve a refund transaction log operation. This operation allows you to export a log of all transactions from Zuora to the gateway for the refund.
Zuora allows you to issue and track refunds on payments. Similar to external payments, users can enter external refunds to track refunds that have been performed outside of Zuora Payments (for example, by issuing a check). In addition, you can make electronic refunds using our supported payment gateways, which will automatically refund money to the customer.
The Zuora Reporting API enables you to access reports that you have created in the Zuora UI, manage report runs, and export the results of report runs.
The endpoints of the Reporting API are the same as the endpoints of Zuora REST API. The following table provides some endpoints as reference:
| Environment | API Endpoint |
|---|---|
| API Sandbox (US Cloud Data Center 1) | https://rest.sandbox.na.zuora.com |
| Production (US Cloud Data Center 1) | https://rest.na.zuora.com |
| API Sandbox (US Cloud Data Center 2) | https://rest.apisandbox.zuora.com |
| Production (US Cloud Data Center 2) | https://rest.zuora.com |
| API Sandbox (EU Data Center) | https://rest.sandbox.eu.zuora.com |
| Production (EU Data Center) | https://rest.eu.zuora.com |
| US Central Sandbox | https://rest.test.zuora.com |
| EU Central Sandbox | https://rest.test.eu.zuora.com |
| APAC Developer & Central Sandbox | https://rest.test.ap.zuora.com |
| APAC Production | https://rest.ap.zuora.com |
Historically, the endpoints of the Reporting API were different from the endpoints of the Zuora REST API.
Note that you are still able to use the following endpoints, but it is unrecommended and you can only use username and password to authenticate to the Reporting API. We recommend you to use OAuth to authenticate to the Reporting API. OAuth only works with new endpoints. The endpoints of the Reporting API were:
| Environment | API Endpoint |
|---|---|
| API Sandbox (US Cloud Data Center 1) | https://zconnect.sandbox.na.zuora.com/api/rest/v1 |
| Production (US Cloud Data Center 1) | https://zconnect.na.zuora.com/api/rest/v1 |
| API Sandbox (US Cloud Data Center 2) | https://zconnectsandbox.zuora.com/api/rest/v1 |
| Production (US Cloud Data Center 2) | https://zconnect.zuora.com/api/rest/v1 |
| API Sandbox (EU Data Center) | https://zconnect.sandbox.eu.zuora.com/api/rest/v1 |
| Production (EU Data Center) | https://zconnect.eu.zuora.com/api/rest/v1 |
| US Central Sandbox | https://zconnect-services0001.test.zuora.com/api/rest/v1 |
| EU Central Sandbox | https://zconnect-services0002.test.eu.zuora.com/api/rest/v1 |
| APAC Developer & Central Sandbox | https://zconnect-services0003.test.ap.zuora.com |
| APAC Production | http://zconnect-prod05.ap.zuora.com |
A revenue event is a record or audit trail about a change to a revenue schedule. When you manually distribute revenue schedule, if no change is made to the revenue schedule, no revenue events will not be created.
A revenue event is comprised of:
The Entitlements settings must be enabled to use this operation. Access to the Entitlements feature requires a specific edition of Zuora. See Zuora Editions for details.
A subscription is a product or service that has recurring charges, such as a monthly flat fee or charges based on usage. Subscriptions can also include one-time charges, such as activation fees. Every subscription must be associated with an account. At least one active account must exist before any subscriptions can be created.
For more information, see <a href="https://knowledgecenter.zuora.com/Billing/Subscriptions/Subscriptions" target="_blank">Subscriptions</a>.
The TaxationItem object is used to add a tax amount to an invoice item. In the typical use case, the tax amount that you specify in the object is calculated by <a href="https://knowledgecenter.zuora.com/Billing/Taxes/A_Zuora_Tax" target="_blank">Z-Tax</a> or a third-party tax engine such as <a href="https://knowledgecenter.zuora.com/Billing/Taxes/Direct_Avalara_Integration" target="_blank">Avalara</a> or <a href="https://knowledgecenter.zuora.com/Billing/Taxes/Additional_resources_on_taxes/AA_Connect_Tax_Engines" target="_blank">Connect tax engine</a>.
Changes that you make with this object affect the product charges in your product catalog, but not the charges in existing subscriptions.
You can view all transactions associated with an account, including:
A unit of measure (UOM) is the definable unit that you measure when determining charges. For example, if a customer's subscription rate plan includes 20 licenses, then 20 is the quantity and license is the unit that the quantity measures.
You can customize the units of measure (UOM) your company uses to measure the use of your services; for example, minutes, people, seats, and licenses can all be units of measure.
This section contains the legacy API operations for Usage.
For the "Retrieve a usage record" operation, we recommend that you use the following Object Query operations instead: