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.
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.
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 GET \
'https://developer.zuora.com/_mock/v1-api-reference/older-api/v1/object/rate-plan-charge/{id}?fields=string' \
-H 'Accept-Encoding: string' \
-H 'Authorization: string' \
-H 'Content-Encoding: string' \
-H 'Zuora-Entity-Ids: string' \
-H 'Zuora-Track-Id: string'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 accounting code for the charge. Accounting codes group transactions that contain similar accounting attributes.
Character limit: 100
Values: inherited from ProductRatePlanCharge.AccountingCode
Note: This value changes if ProductRatePlanCharge.AccountingCode is updated. The values of UpdatedById and UpdatedDate for the RatePlanCharge do not change when ProductRatePlanCharge.AccountingCode is updated.
Specifies the type of charges a specific discount applies to. Character limit: 21 Values: inherited from ProductRatePlanCharge.ApplyDiscountTo
Indicates the charge's billing cycle day (BCD), which is when bill runs generate invoices for charges associated with the product rate plan charge or the account. Character limit: 2 Values: inherited from ProductRatePlanCharge.BillCycleDay
Specifies how to determine the billing day for the charge. Character limit: 20 Values: inherited from ProductRatePlanCharge.BillCycleType Note: You can override the value inherited from the Product Rate Plan Charge, but only when creating a new subscription or a New Product amendment.
Allows billing period to be overridden on rate plan charge. **Values: **inherited from ProductRatePlanCharge.BillingPeriod Note: You can override the value inherited from the Product Rate Plan Charge, but only when creating a new subscription or a New Product amendment.
Aligns charges within the same subscription if multiple charges begin on different dates. Character limit: 24 Values: inherited from ProductRatePlanCharge.BillingPeriodAlignment
The billing timing for the charge. You can choose to bill in advance or in arrears for recurring charge types. This field is not used in one-time or usage based charge types. Character limit: Values: one of the following:
In AdvanceIn Arrears Note: You can override the value inherited from the Product Rate Plan Charge when a subscription has a recurring charge type.Determines how to evaluate charges. Charge models must be individually activated in the web-based UI. Character limit: 29 Values: inherited from ProductRatePlanCharge.ChargeModel
A unique number that identifies the charge. This number is returned as a string. Character limit: 50 Values: one of the following:
Specifies the type of charge. Character limit: 9 Values: inherited from ProductRatePlanCharge.ChargeType
The date through which a customer has been billed for the charge. Character limit: 29 Values: automatically generated
The ID of the Zuora user who created the RatePlanCharge object. Character limit: 32 Values: automatically generated
The date when the RatePlanCharge object was created. Character limit: 29 Values: automatically generated
A delta monthly recurring charge is the change in monthly recurring revenue caused by an amendment or a new subscription. Character limit: 16 Values: automatically generated
After an Amendment, the change in the total contract value (TCV) amount for this charge, compared with its previous value. Character limit: 16 Values: automatically generated
A description of the charge. Character limit: 500 Values: inherited from ProductRatePlanCharge.Description
Specifies if the discount applies to just the product rate plan, the entire subscription, or to any activity in the account. Character limit: 12 Values: inherited from ProductRatePlanCharge.DiscountLevel
The date when the segmented charge ends or ended. Character limit: 16 Values: automatically generated
The date when the segmented charge starts or started. Character limit: 16 Values: automatically generated
Defines when the charge ends after the charge trigger date. This field can be updated when Status is Draft. Values: one of the following:
SubscriptionEnd: The charge ends on the subscription end date after the charge trigger date. This is the default value.FixedPeriod: The charge ends after a specified period based on the trigger date of the charge. If you set this field to FixedPeriod, you must specify the length of the period and a period type by defining the UpToPeriods and UpToPeriodsType fields.SpecificEndDate: The specific date on which the charge ends. If you set this field to SpecificEndDate, you must specify the specific date by defining the SpecificEndDate field.Note: If the subscription ends before the charge end date, the charge ends when the subscription ends. But if the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge will end on the charge end date.
The flag to exclude rate plan charge related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.
Note: To use this field, you must set the X-Zuora-WSDL-Version request header to 115 or later. Otherwise, an error occurs.
Note: This field is only available if you have the Billing - Revenue Integration feature enabled.
The flag to exclude rate plan charges from revenue accounting.
Note: To use this field, you must set the X-Zuora-WSDL-Version request header to 115 or later. Otherwise, an error occurs.
Note: This field is only available if you have the Billing - Revenue Integration feature enabled.
Indicates if the segment of the rate plan charge is the most recent segment. Character limit: 5 Values: automatically generated: true, false
The list price base for the product rate plan charge.
Monthly recurring revenue (MRR) is the amount of recurring charges in a given month. The MRR calculation doesn't include one-time charges nor usage charges. Character limit: 16 Values: automatically generated
Specifies the number of periods to use when calculating charges in an overage smoothing charge model. Character limit: 5 Values: inherited from ProductRatePlanCharge.NumberOfPeriod
The original ID of the rate plan charge. Character limit: 32 Values: automatically generated
Determines when to calculate overage charges. If the value of the SmoothingMode field is null (not specified and not inherited from ProductRatePlanCharge.SmoothingMode), the value of this field is ignored. Character limit: 20 Values: inherited from ProductRatePlanCharge.OverageCalculationOption
Determines whether to credit the customer with unused units of usage. Character limit: 20 Values: inherited from ProductRatePlanCharge.OverageUnusedUnitsCreditOption
Applies an automatic price change when a termed subscription is renewed. Character limit: Values: one of the following:
NoChange (default)SpecificPercentageValueUseLatestProductCatalogPricingSpecifies the percentage to increase or decrease the price of renewed subscriptions. Character limit: 16 Values: a decimal value between -100 and 100
The date until when charges have been processed. When billing in arrears, such as usage, this field value is the the same as the ChargedThroughDate value. This date is the earliest date when a charge can be amended. Character limit: 29 Values: automatically generated
The default quantity of units, such as the number of authors in a hosted wiki service. Valid for all charge models except for Flat Fee pricing. Character limit: 16 Values: a valid quantity value
The ID of the rate plan associated with the rate plan charge. Character limit: 32 Values: inherited from RatePlan.Id
A rating group based on which usage records are rated. Only applicable to Usage charges.
Possible values:
ByBillingPeriod: The rating is based on all the usages in a billing period.ByUsageStartDate: The rating is based on all the usages on the same usage start date.ByUsageRecord: The rating is based on each usage record.ByUsageUpload: The rating is based on all the usages in a uploaded usage file (.xls or .csv).ByGroupId: The rating is based on all the usages in a custom group.For more information, see Usage rating by group.
Associates this product rate plan charge with a specific revenue recognition code.
Character limit: 70
Values: inherited from ProductRatePlanCharge.RevRecCode or a valid revenue recognition code
Note: Unless overridden, this value changes if ProductRatePlanCharge.RevRecCode is updated. The values of UpdatedById and UpdatedDate for the RatePlanCharge do not change when ProductRatePlanCharge.RevRecCode is updated.
Specifies when revenue recognition begins.
Character limit: 22
Values: inherited from ProductRatePlanCharge.RevRecTriggerCondition or one of the following:
ContractEffectiveDate
ServiceActivationDate
CustomerAcceptanceDate
Note: Unless overridden, this value changes if ProductRatePlanCharge.RevRecTriggerCondition is updated. The values of UpdatedById and UpdatedDate for the RatePlanCharge do not change when ProductRatePlanCharge.RevRecTriggerCondition is updated.
Specifies the Revenue Recognition Rule that you want the Rate Plan Charge to use. This field can be updated when Status is Draft. By default, the Revenue Recognition Rule is inherited from the Product Rate Plan Charge. For Amend calls, you can use this field only for NewProduct amendments. For Update calls, you can use this field only to update subscriptions in draft status. Note that if you use this field to specify a Revenue Recognition Rule for the Rate Plan Charge, the rule will remain as specified even if you later change the rule used by the corresponding Product Rate Plan Charge.
Character limit: n/a
Values: inherited from ProductRatePlanCharge.RevenueRecognitionRuleName or the name of an active Revenue Recognition Rule
Note: Unless overridden, this value changes if ProductRatePlanCharge.RevenueRecognitionRuleName is updated. The values of UpdatedById and UpdatedDate for the RatePlanCharge do not change when ProductRatePlanCharge.RevenueRecognitionRuleName is updated.
Specifies the number of units of measure (UOM) rolled over from previous periods. The value of this field is the rollover balance for the corresponding account.
This field is applicable only to usage charges with overage models.
Note:
The identifying number of the subscription rate plan segment. Segments are numbered sequentially, starting with 1. Character limit: 2 Values: automatically generated
Customizes the number of months or weeks for the charges billing period. This field is required if you set the value of the BillingPeriod field to Specific Months or Specific Weeks. Character limit: 5 Values: inherited from ProductRatePlanCharge.BillingPeriod Note: You can override the value inherited from the Product Rate Plan Charge, but only when creating a new subscription or a New Product amendment.
The specific date on which the charge ends, in yyyy-mm-dd format. Character limit: 29 Note:
EndDateCondition field is set to SpecificEndDate.The number of months for the list price base of the charge. The value of this field is null if you do not set the value of the ListPriceBase field to Per Specific Months. Note: - This field is available only if you have the <a href="https://knowledgecenter.zuora.com/Billing/Subscriptions/Product_Catalog/I_Annual_List_Price" target="_blank">Annual List Price</a> feature enabled. - The value of this field is null if you do not set the value of the ListPriceBase field to Per Specific Months.
The total contract value (TCV) is the value of a single rate plan charge in a subscription over the lifetime of the subscription. This value does not represent all charges on the subscription. The TCV includes recurring charges and one-time charges, but it doesn't include usage charge. Character limit: 16 Values: automatically generated
The date when the charge becomes effective and billing begins, in yyyy-mm-dd format. This field is required if the TriggerEvent field value is SpecificDate. Character limit: 29
Specifies when to start billing the customer for the charge. **Note: **This field can be passed through the Subscribe and Amend calls and will override the default value set on the Product Rate Plan Charge. Character limit: 18 Values: inherited from ProductRatePlanCharge.TriggerEvent and can be one of the following values:
ContractEffective is the date when the subscription's contract goes into effect and the charge is ready to be billed.ServiceActivation is when the services or products for a subscription have been activated and the customers have access.CustomerAcceptance is when the customer accepts the services or products for a subscription.SpecificDate is valid only on the RatePlanCharge.Specifies the units to measure usage. Character limit: 25 Values: inherited from ProductRatePlanCharge.UOM
Specifies the length of the period during which the charge is active. If this period ends before the subscription ends, the charge ends when this period ends. Character limit: 5 Values: inherited from ProductRatePlanCharge.UpToPeriods Note:
UpToPeriodsType field to specify the time period. This field is only applicable only when the EndDateCondition field is set to FixedPeriod.ProductRatePlanCharge.UpToPeriod.The period type used to define when the charge ends. This field can be updated when Status is Draft. Values: one of the following:
Billing Periods (default)
Days
Weeks
Months
Years Note:
You must use this field together with the UpToPeriods field to specify the time period.
This field is only applicable only when the EndDateCondition field is set to FixedPeriod.
The ID of the last user to update the object. Character limit: 32 Values: automatically generated
The date when the object was last updated. Character limit: 29 Values: automatically generated
The version of the rate plan charge. Each time a charge is amended, Zuora creates a new version of the rate plan charge. Character limit: 5 Values: automatically generated
Specifies which day of the week as the bill cycle day (BCD) for the charge. This feature is in Limited Availability. If you wish to have access to the feature, submit a request at Zuora Global Support.
Values: one of the following:
SundayMondayTuesdayWednesdayThursdayFridaySaturdayCustom fields of the Rate Plan Charge 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.
{ "PriceChangeOption": "NoChange", "OverageCalculationOption": "EndOfSmoothingPeriod", "Id": "2c93808457d787030157e02f9b802fad", "ChargeNumber": "C-00000001", "BillingPeriodAlignment": "AlignToCharge", "UpdatedDate": "2016-10-20T05:43:19.000+02:00", "Version": 1, "BillCycleDay": 1, "BillingPeriod": "Month", "IsLastSegment": true, "UpToPeriodsType": "Billing Periods", "UpdatedById": "2c93808457d787030157e02f84852e27", "Quantity": 1, "EndDateCondition": "SubscriptionEnd", "Segment": 1, "RatePlanId": "2c93808457d787030157e02f9b762fac", "ChargeModel": "Flat Fee Pricing", "TriggerEvent": "ContractEffective", "BillingTiming": "In Arrears", "CreatedById": "2c93808457d787030157e02f84852e27", "CreatedDate": "2016-10-20T05:43:18.000+02:00", "Name": "Recurring_Flat Fee Pricing1476934998566", "ChargeType": "Recurring", "OverageUnusedUnitsCreditOption": "NoCredit", "RolloverBalance": 0, "OriginalId": "2c93808457d787030157e02f9b802fad", "ListPriceBase": "Per Billing Period", "PriceIncreasePercentage": 0, "NumberOfPeriods": 1, "BillCycleType": "DefaultFromCustomer", "Description": "Recurring Flat Fee Pricing", "AccountingCode": "name_1476934998566" }
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.
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 billing timing for the charge. You can choose to bill in advance or in arrears for recurring charge types. This field is not used in one-time or usage based charge types. Character limit: Values: one of the following:
In AdvanceIn Arrears Note: You can override the value inherited from the Product Rate Plan Charge when a subscription has a recurring charge type.Specifies the amount of a fixed-amount discount. You can provide a value for this field if the ChargeModel field value is Discount-Fixed Amount. Character limit: 16 Values: A valid currency amount
The percentage of discount for a percentage discount. Use this field if the value for ProductRatePlanCharge.ChargeModel is Discount-Percentage and you want to override the value in ProductRatePlanChargeTier.DiscountPercentage. Character limit: 16 Values: a decimal value between -100 and 100, exclusive
Defines when the charge ends after the charge trigger date. This field can be updated when Status is Draft. Values: one of the following:
SubscriptionEnd: The charge ends on the subscription end date after the charge trigger date. This is the default value.FixedPeriod: The charge ends after a specified period based on the trigger date of the charge. If you set this field to FixedPeriod, you must specify the length of the period and a period type by defining the UpToPeriods and UpToPeriodsType fields.SpecificEndDate: The specific date on which the charge ends. If you set this field to SpecificEndDate, you must specify the specific date by defining the SpecificEndDate field.Note: If the subscription ends before the charge end date, the charge ends when the subscription ends. But if the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge will end on the charge end date.
The list price base for the product rate plan charge.
Applies an automatic price change when a termed subscription is renewed. Character limit: Values: one of the following:
NoChange (default)SpecificPercentageValueUseLatestProductCatalogPricingSpecifies the percentage to increase or decrease the price of renewed subscriptions. Character limit: 16 Values: a decimal value between -100 and 100
Specifies a rating group based on which usage records are rated.
ByBillingPeriod (default) - The rating is based on all the usages in a billing period.ByUsageStartDate - The rating is based on all the usages on the same usage start date.ByUsageRecord - The rating is based on each usage record.ByUsageUpload - The rating is based on all the usages in a uploaded usage file (.xls or .csv). If you import a mass usage in a single upload, which contains multiple usage files in .xls or .csv format, usage records are grouped for each usage file.ByGroupId - The rating is based on all the usages in the same custom group.Note:
ByBillingPeriod value can be applied for all charge models.ByUsageStartDate, ByUsageRecord, and ByUsageUpload values can only be applied for per unit, volume pricing, and tiered pricing charge models.ByGroupId value is only available if you have the Active Rating feature enabled.NULL.See Usage Rating by Group for more information.
Associates this product rate plan charge with a specific revenue recognition code.
Character limit: 70
Values: inherited from ProductRatePlanCharge.RevRecCode or a valid revenue recognition code
Note: Unless overridden, this value changes if ProductRatePlanCharge.RevRecCode is updated. The values of UpdatedById and UpdatedDate for the RatePlanCharge do not change when ProductRatePlanCharge.RevRecCode is updated.
Specifies when revenue recognition begins.
Character limit: 22
Values: inherited from ProductRatePlanCharge.RevRecTriggerCondition or one of the following:
ContractEffectiveDate
ServiceActivationDate
CustomerAcceptanceDate
Note: Unless overridden, this value changes if ProductRatePlanCharge.RevRecTriggerCondition is updated. The values of UpdatedById and UpdatedDate for the RatePlanCharge do not change when ProductRatePlanCharge.RevRecTriggerCondition is updated.
Specifies the Revenue Recognition Rule that you want the Rate Plan Charge to use. This field can be updated when Status is Draft. By default, the Revenue Recognition Rule is inherited from the Product Rate Plan Charge. For Amend calls, you can use this field only for NewProduct amendments. For Update calls, you can use this field only to update subscriptions in draft status. Note that if you use this field to specify a Revenue Recognition Rule for the Rate Plan Charge, the rule will remain as specified even if you later change the rule used by the corresponding Product Rate Plan Charge.
Character limit: n/a
Values: inherited from ProductRatePlanCharge.RevenueRecognitionRuleName or the name of an active Revenue Recognition Rule
Note: Unless overridden, this value changes if ProductRatePlanCharge.RevenueRecognitionRuleName is updated. The values of UpdatedById and UpdatedDate for the RatePlanCharge do not change when ProductRatePlanCharge.RevenueRecognitionRuleName is updated.
The specific date on which the charge ends, in yyyy-mm-dd format. Character limit: 29 Note:
EndDateCondition field is set to SpecificEndDate.The number of months for the list price base of the charge. This field is required if you set the value of the ListPriceBase field to Per Specific Months. Note: - This field is available only if you have the <a href="https://knowledgecenter.zuora.com/Billing/Subscriptions/Product_Catalog/I_Annual_List_Price" target="_blank">Annual List Price</a> feature enabled. - The value of this field is null if you do not set the value of the ListPriceBase field to Per Specific Months.
The date when the charge becomes effective and billing begins, in yyyy-mm-dd format. This field is required if the TriggerEvent field value is SpecificDate. Character limit: 29
Specifies when to start billing the customer for the charge.
Note: This field can be passed through the Subscribe and Amend calls and will override the default value set on the Product Rate Plan Charge.
Note: When the Update rate plan charge trigger condition? setting is set to Yes, this field can be passed through the update() call and override the previous value. You can use this feature to directly update the trigger condition of a rate plan charge without creating an order action (or amendment).
Character limit: 18 Values: inherited from ProductRatePlanCharge.TriggerEvent and can be one of the following values:
ContractEffective is the date when the subscription's contract goes into effect and the charge is ready to be billed.
ServiceActivation is when the services or products for a subscription have been activated and the customers have access.
CustomerAcceptance is when the customer accepts the services or products for a subscription.
SpecificDate is valid only on the RatePlanCharge. When this value is specified, use the TriggerDate field to set the specific date.
Specifies the length of the period during which the charge is active. If this period ends before the subscription ends, the charge ends when this period ends.
This field can be updated when Status is Draft.
Character limit: 5
Values: inherited from ProductRatePlanCharge.UpToPeriods
Note:
UpToPeriodsType field to specify the time period. This field is only applicable only when the EndDateCondition field is set to FixedPeriod.ProductRatePlanCharge.UpToPeriod.The period type used to define when the charge ends. This field can be updated when Status is Draft. Values: one of the following:
Billing Periods (default)
Days
Weeks
Months
Years Note:
You must use this field together with the UpToPeriods field to specify the time period.
This field is only applicable only when the EndDateCondition field is set to FixedPeriod.
Specifies which day of the week as the bill cycle day (BCD) for the charge. This feature is in Limited Availability. If you wish to have access to the feature, submit a request at Zuora Global Support.
Values: one of the following:
SundayMondayTuesdayWednesdayThursdayFridaySaturdayCustom fields of the Rate Plan Charge 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 PUT \
'https://developer.zuora.com/_mock/v1-api-reference/older-api/v1/object/rate-plan-charge/{id}?rejectUnknownFields=false' \
-H 'Accept-Encoding: string' \
-H 'Authorization: string' \
-H 'Content-Encoding: string' \
-H 'Content-Type: application/json' \
-H 'Zuora-Entity-Ids: string' \
-H 'Zuora-Track-Id: string' \
-d '{
"PriceIncreasePercentage": 10
}'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": "2c92c0f86a79e2e4016a8bad616b257c" }
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: