Skip to main content

RatePlanCharge

Zuora

RatePlanCharge

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

Rate plan charges represent the actual charges for the rate plans or services that you sell.

Updating default values on a Product Rate Plan Charge

Use the RatePlanCharge object to define the charges in a RatePlan. Upon creation, it inherits values from the corresponding ProductRatePlanCharge. You can alter some of the field values on an individual subscription or amendment basis using the RatePlanCharge object. To update it, first query it, then update the relevant fields and use it in a RatePlanChargeData array in a subscribe() call. See Subscribe()  and RatePlanChargeData for more information.

Type of rate plan charges

Rate plan charges have the same types as their counterparts in product: one-time fees, recurring fees, and usage fees.

A one-time fee is a charge that your customer pays only once. One-time fees don't recur. Upfront setup fees and activation fees are examples of a one-time fee.

A recurring fee is a fee that repeats on a regular basis. You can set the schedule to be monthly, quarterly, semi-annually, or annually. Once the charge is triggered, the customer is automatically charged on the appropriate dates in the future. Monthly charges for satellite TV and yearly charges for authoring licenses on a hosted wiki are examples of a recurring fee. See Triggering Conditions for more information.

A usage fee is a fee based on the quantity of units, such as media storage, that customers use during a given billing period. Usage charges are billed in arrears based on a customer's actual usage. Per-minute charges for phone calls and GB of media storage are examples of usage fees.

Segmented rate plan charges (charge segments)

Zuora returns segmented rate plan charges, which are referred to as rate plan charge segments or charge segments. Every time an amendment (or an order action) changes a charge (except the Remove Product amendment), Zuora creates a new segmented RatePlanCharge object. Segmentation help you to use the fields, Segment, EffectiveEndDate, EffectiveStartDate, andisLastSegment, to determine the following:

  • The current price and quantity of a charge:
    EffectiveStartDate <= Today < EffectiveEndDate
    or 
    isLastSegment=true(As this filter condition always returns the last charge segment, if a subscription has any future dated changes, the future dated charge segment will be returned rather than the current charge segment. In this scenario, use the filter condition above.)
  • The previous details of a charge, such as its price and quantity:
    EffectiveStartDate < Today
  • Pending charges:
    EffectiveStartDate > Today
  • The entire history of a charge:
    Order the RatePlanCharge object by segments, starting with the Segment field with the value, 1.

Segmented rate plan charges are supported as of WSDL version 20.0+.

Supported Calls

You can use this object with the following calls:

Walkthroughs and Use Cases

Here are some common ways to use this object:

  • Apply multiple discount charges
  • Override settings in the ProductRatePlanCharge object
  • Review the history of a charge

Field Descriptions

All field names are case sensitive. Check enumerated values in descriptions to confirm capitalization and spacing. See Field Types for additional information.

See API Basics for information on usage.

Name Required? Allowed Operation Description
AccountingCode optional

Query
Filter

The accounting code for the charge. Accounting codes group transactions that contain similar accounting attributes.

Type: string
Character limit: 100
Version notes: --
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.

amendedByOrderOn n/a Query
Filter

The date when the rate plan charge is amended through an order or amendment.

This field is to standardize the booking date information to increase audit ability and traceability of data between Zuora Billing and Zuora Revenue. It is mapped as the booking date for a sale order line in Zuora Revenue.

Type: string
Version notes: 118.0

ApplyDiscountTo optional

Query
Filter

Specifies the type of charges a specific discount applies to. 

Type: string (enum)
Character limit: 21
Version notes: WSDL 26.0+
Values: inherited from
ProductRatePlanCharge.ApplyDiscountTo

BillCycleDay optional

Subscribe
Query
Filter

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.

Type: int
Character limit: 2
Version notes: WSDL 30.0+.
Values: inherited from 
ProductRatePlanCharge.BillCycleDay

BillCycleType optional

Subscribe
Create
Query
Filter

Specifies how to determine the billing day for the charge.

Type: string (enum)
Character limit: 20
Version notes: The SpecificDayofWeek value is available in WSDL 74.0+, all other values are available in WSDL 26.0+.
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.

BillingPeriod optional

Subscribe
Create
Query
Filter

Allows billing period to be overridden on rate plan charge.

Type: string ()
Version notes: The Week and Specific Weeks values are available in WSDL 74.0+, all other values are available in WSDL 50.0+.
Valuesinherited 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.

BillingPeriodAlignment optional

Subscribe
Query
Filter

Aligns charges within the same subscription if multiple charges begin on different dates.

Type: string (enum)
Character limit: 24
Version notes: WSDL 14.0+
Values: inherited from 
ProductRatePlanCharge.BillingPeriodAlignment

BillingTiming optional

Create
Update
Query

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.

Type: string (enum)
Character limit
Version notes: WSDL 70.0+
Values: one of the following:

  • In Advance
  • In Arrears

Note: You can override the value inherited from the Product Rate Plan Charge when a subscription has a recurring charge type.

ChargedThroughDate optional Query
Filter

The date through which a customer has been billed for the charge.

Type

  • date: Supported as of WSDL version 69+
  • dateTime: Supported through WSDL version 68

Character limit: 29
Version notes: WSDL 20.0+
Values: automatically generated

Note: The value of UpdatedDate for the RatePlanCharge does not change when ChargedThroughDate is updated.

ChargeModel optional Query
Filter

Determines how to evaluate charges. Charge models must be individually activated in the web-based UI.

Type: string (enum)
Character limit: 27
Version notes: WSDL 20.0+
Values: inherited from 
ProductRatePlanCharge.ChargeModel

ChargeNumber optional

Create
Query
Filter

A unique number that identifies the charge. This number is returned as a string.

Type: sequence/string
Character limit: 50
Version notes: --
Values: one of the following:

  • automatically generated if left null
  • a unique number of 50 characters or fewer
ChargeType optional

Query
Filter

Specifies the type of charge.

Type: string (enum)
Character limit: 9
Version notes: WSDL 20.0+
Values: inherited from
ProductRatePlanCharge.ChargeType

CreatedById optional

Query
Filter

The ID of the Zuora user who created the RatePlanCharge object.

Type: zns:ID
Character limit: 32
Version notes: WSDL 20.0+
Values: automatically generated 

CreatedDate optional

Query
Filter

The date when the RatePlanCharge object was created.

Type: dateTime
Character limit: 29
Version notes: WSDL 20.0+
Values: automatically generated

Description optional

Subscribe
Query
Filter

A description of the charge.

Type: string
Character limit: 500
Version notes: --
Values: inherited from 
ProductRatePlanCharge.Description

DiscountAmount optional

Subscribe
Create
Update
Query
Filter

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.

If this field is included in a query, the query will filter out the rate plans whose ChargeModel field is not of a Discount type.

You cannot query this field with the following fields in a single query:

  • Price
  • IncludedUnits
  • DiscountPercentage
  • OveragePrice

Type: decimal (currency)
Character limit: 16
Version notes: WSDL 26.0+
Values: a valid currency amount

DiscountClass

optional

Query

The class that the discount belongs to. The discount class defines the order in which discount rate plan charges are applied.

For the order in which discount charges apply to the same product rate plan charge, see Processing Discount Charges.

Type: string

Character limit: 50
Version notes: 85.0+
Values: a string of 50 characters or fewer

DiscountLevel optional

Query
Filter

Specifies if the discount applies to just the product rate plan, the entire subscription, or to any activity in the account.

Type: string (enum)
Character limit: 12
Version notes: WSDL 26.0+
Values: inherited from 
ProductRatePlanCharge.DiscountLevel

DiscountPercentage optional

Subscribe
Create
Update
Query
Filter
Delete

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.

You cannot query this field with the following fields in a single query:

  • Price
  • IncludedUnits
  • DiscountAmount
  • OveragePrice

Type: decimal
Character limit: 16
Version notes: WSDL 26.0+
Values: a decimal value between -100 and 100, exclusive

DMRC optional

Query
Filter

A delta monthly recurring charge is the change in monthly recurring revenue caused by an amendment or a new subscription. This is the value at the charge segment level.

Type: decimal
Character limit: 16
Version notes: type is double for WSDL 18.0 and older
Values: automatically generated

DTCV optional

Query
Filter

After an Amendment, the change in the total contract value (TCV) amount for this charge segment, compared with its previous value.

Type: decimal
Character limit: 16
Version notes: type is double for WSDL 18.0 and older
Values: automatically generated

EffectiveEndDate optional

Query
Filter

The date when the segmented charge ends or ended.

Type

  • date: Supported as of WSDL version 69+
  • dateTime: Supported through WSDL version 68

Character limit: 16
Version notes: WSDL 20.0+
Values: automatically generated

EffectiveStartDate optional

Query
Filter

The date when the segmented charge starts or started.

Type

  • date: Supported as of WSDL version 69+
  • dateTime: Supported through WSDL version 68

Character limit: 16
Version notes: WSDL 20.0+
Values: automatically generated

EndDateCondition

optional

Subscribe
Create
Query
Update*
Amend
Filter

Defines when the charge ends after the charge trigger date.

This field can be updated when Status is Draft.

Type: string (enum)
Character limit: --
Version notes: WSDL 72.0+
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.
  • OneTime: All the one-time charges have the field set to this value.

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.

ExcludeItemBookingFromRevenue optional

Subscribe
Create
Amend
Query

Specifies whether to exclude non-revenue related rate plan charges and order line items from syncing to Zuora Revenue. This field is only available if you have enabled the Order to Revenue or Billing - Revenue Integration feature.

You can set this field for a rate plan charge when creating a new subscription or adding a new product to an existing subscription. You can access this field for a rate plan charge through the Zuora UI, API, and Rate Plan Charge data source. However, you can not update this field for a rate plan charge in the subscription.

Type: boolean
Character limit: 5
Version notes: WSDL 115.0 and later
Values:true, false

ExcludeItemBillingFromRevenue optional Subscribe
Create
Amend
Query

Specifies whether to exclude non-revenue related invoice items, invoice item adjustments, credit memo items, and debit memo items from syncing to Zuora Revenue. This field is only available if you have enabled the Order to Revenue or Billing - Revenue Integration feature.

You can set this field for a rate plan charge when creating a new subscription or adding a new product to an existing subscription. You can access this field for a rate plan charge through the Zuora UI, API, and Rate Plan Charge data source. However, you can not update this field for a rate plan charge in the subscription.

Type: boolean
Character limit: 5
Version notes: WSDL 115.0 and later
Values:true, false

Id optional Query
Filter

The ID of this object. Upon creation, the ID of this object is RatePlanChargeId.

Type: zns:ID
Character limit: 32
Version notes: --
Values: automatically generated

InvoiceOwnerId required Query

The invoice owner ID of the subscription that the rate plan belongs to.

Type: zns:ID
Character limit: 32
Version notes: --
Values: a valid account ID

IncludedUnits optional

Create*
Query
Filter

Specifies the number of units in the base set of units.

This field can only be created for overage charge models.

You cannot query this field with the following fields in a single query:

  • Price
  • DiscountAmount
  • DiscountPercentage
  • OveragePrice

Type: decimal
Character limit: 16
Version notes: type is double for WSDL 18.0 and older
Values: inherited from
ProductRatePlanCharge.IncludedUnits

IsAllocationEligible optional Create
Query
Update
This field is used to identify if the charge segment is allocation eligible in revenue recognition.

Type: boolean
Character limit: 5
Version notes: WSDL 132.0 and later
Values: truefalse (default)

Note: This feature is in the Early Adopter phase. If you want to use the feature, submit a request at Zuora Global Support, and we will evaluate whether the feature is suitable for your use cases.

IsLastSegment optional

Query
Filter

Indicates if the segment of the rate plan charge is the most recent segment.

Type: boolean
Character limit: 5
Version notes: WSDL 24.0+
Values: automatically generated: true, false

IsUnbilled optional Create
Query
Update
This field is used to dictate how to perform the accounting during revenue recognition.

Type: boolean
Character limit: 5
Version notes: WSDL 132.0 and later
Values: truefalse (default)

Note: This feature is in the Early Adopter phase. If you want to use the feature, submit a request at Zuora Global Support, and we will evaluate whether the feature is suitable for your use cases.

ListPriceBase optional

Subscribe
Create
Query
Update
Subscribe
Amend

The list price base for the product rate plan charge.

You can only update the value of this field if the amendment type is NewProduct.

Typestring (enum)
Character limit: --
Version notes: WSDL 67+
Values: one of the following:

  • Per Month
  • Per Billing Period
  • Per Week
  • Per Year
MRR optional

Query
Filter

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. This field returns MRR of a particular charge segment.

Type: decimal
Character limit: 16
Version notes: type is double for WSDL 18.0 and older
Values: automatically generated

Name optional

Query
Filter

The name of the rate plan charge.

Type: string
Character limit: 100
Version notes: --
Values: automatically generated

NumberOfPeriods optional

Query
Filter

Specifies the number of periods to use when calculating charges in an overage smoothing charge model.

Type: long
Character limit: 5
Version notes: --
Values: inherited from
ProductRatePlanCharge.NumberOfPeriod

OriginalChargeId

n/a

n/a

Deprecated. Use OriginalId instead.

OriginalId optional

Query
Filter

The original ID of the rate plan charge.

Type: zns:ID
Character limit: 32
Version notes: WSDL 20.0+
Values: automatically generated

originalOrderDate n/a Query
Filter

The date when the rate plan charge is created through an order or amendment.

This field is to standardize the booking date information to increase audit ability and traceability of data between Zuora Billing and Zuora Revenue. It is mapped as the booking date for a sale order line in Zuora Revenue.

Type: string
Version notes: 118.0

OverageCalculationOption optional

Query
Filter

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.

Type: string (enum)
Character limit: 20
Version notes: --
Values: inherited from
ProductRatePlanCharge.OverageCalculationOption

OveragePrice optional

Query
Filter

The price for units over the allowed amount.

You cannot query this field with the following fields in a single query:

  • Price
  • IncludedUnits
  • DiscountAmount
  • DiscountPercentage

Type: decimal (currency)
Character limit: 16
Version notes: type is double for WSDL 18.0 and older
Values: inherited from ProductRatePlanChargeTier.Price if <codeproductrateplanchargetier.isoverageprice> is true</codeproductrateplanchargetier.isoverageprice>

OverageUnusedUnitsCreditOption optional

Query
Filter

Determines whether to credit the customer with unused units of usage.

Type: string (enum)
Character limit: 20
Version notes: --
Values: inherited from 
ProductRatePlanCharge.OverageUnusedUnitsCreditOption

Price optional

Create
Subscribe
Query
Filter

The price for units in the subscription rate plan. Use this field with a subscribe() call to override the price in the associated subscription rate plan charge tiers.

You cannot query this field with the following fields in a single query:

  • IncludedUnits
  • DiscountAmount
  • DiscountPercentage
  • OveragePrice

Type: decimal (currency)
Character limit: decimal (22, 9)
Version notes: type is double for WSDL 18.0 and older
Values: a valid currency amount

When querying the price of a rate plan charge or filtering by price, the response will include results from the following charge models:

  • FlatFee
  • PerUnit
  • Overage
PriceChangeOption optional Create
Query
Update
Delete
Filter

Applies an automatic price change when a termed subscription is renewed.

Type: string (enum)
Character limit
Version notes: WSDL 43.0+
Values: one of the following:

  • NoChange (default)
  • SpecificPercentageValue
  • UseLatestProductCatalogPricing
PriceIncreasePercentage optional Create
Query
Update
Delete
Filter

Specifies the percentage to increase or decrease the price of renewed subscriptions. Use this field if the ProductRatePlanCharge.PriceChangeOption value is set to SpecificPercentageValue.

Type: decimal
Character limit: 16
Version notes: --
Values: a decimal value between -100 and 100

ProcessedThroughDate optional

Query
Filter

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.

Type

  • date: Supported as of WSDL version 69+
  • dateTime: Supported through WSDL version 68

Character limit: 29
Version notes: WSDL 20.0+
Values: automatically generated

Note: The value of UpdatedDate for the RatePlanCharge does not change when ProcessedThroughDate is updated.

ProductCategory optional Create
Query
Update

This is used to maintain the product category.

Type: string
Character limit
Version notes: WSDL 132.0 and later
Values:

Note: This field is only available if you have the Additional Revenue Fields property enabled.

ProductClass optional Create
Query
Update

This is used to maintain the product class.

Type: string
Character limit
Version notes: WSDL 132.0 and later
Values:

Note: This field is only available if you have the Additional Revenue Fields property enabled.

ProductFamily optional Create
Query
Update

This is used to maintain the product family.

Type: string
Character limit
Version notes: WSDL 132.0 and later
Values:

Note: This field is only available if you have the Additional Revenue Fields property enabled.

ProductLine optional Create
Query
Update

This is used to maintain the product line.

Type: string
Character limit
Version notes: WSDL 132.0 and later
Values:

Note: This field is only available if you have the Additional Revenue Fields property enabled.

ProductRatePlanChargeId

required

Query
Filter

The ID of the product rate plan charge associated with the subscription rate plan charge,

Type: zns:ID
Character limit: 32
Version notes: --
Values: inherited from 
ProductRatePlanCharge.Id

Quantity optional

Subscribe
Create
Query
Filter

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.

Type: decimal (quantity)
Character limit: 16
Version notes: type is double for WSDL 18.0 and older
Values: a valid quantity value

RatePlanId

required

Query
Filter

The ID of the rate plan associated with the rate plan charge.

Type: zns:ID
Character limit: 32
Version notes: --
Values: inherited from RatePlan.Id

RatingGroup

conditional

Create
Query
Update
Delete
Filter

Specifies a rating group based on which usage records are rated.

See Usage Rating by Group for more information.

Type: string (enum)
Character limit
Version notes: WSDL 74.0+
Values: one of the following:

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

  • The ByBillingPeriod value can be applied for all charge models.
  • The ByUsageStartDate, ByUsageRecord, and ByUsageUpload values can only be applied for the per unit, volume pricing, or tiered pricing charge model.
  • The ByGroupId value is only available if you have the Active Rating feature enabled.
  • Use this field only for Usage charges. One-Time Charges and Recurring Charges return NULL.

RevenueRecognitionRuleName

optional

Create
Subscribe
Amend
Update*

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. Unless overwritten, 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.

However, after you use this field to overwrite 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.

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.

See Manage Revenue Rules for more information.

This field is only available to Z-Revenue users.

You must have the Override Revenue Recognition Rule Z-Billing User Role permission enabled to use this field.

Type: string
Character limit: n/a
Version notes: WSDL 53.0+
Values: inherited from ProductRatePlanCharge.RevenueRecognitionRuleName or the name of an active Revenue Recognition Rule

RevRecCode

optional

Create
Update

Associates this product rate plan charge with a specific revenue recognition code.

Type: string
Character limit: 70
Version notes: WSDL 52.0+
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.

RevRecTriggerCondition optional Create
Update

Specifies when revenue recognition begins.

Type: string (enum)
Character limit: 22
Version notesWSDL 52.0+
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.

RolloverBalance optional

Query
Filter

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.

Type: decimal
Character limit: 16
Version notes: --
Values: automatically generated
Note:

  • You cannot query or filter this field with other fields in a single query.
  • To query or filter this field, you must specify and only specify the rate plan charge Id in the condition.
  • You cannot use this field in the query or filter condition.
Segment required

Query
Filter

The identifying number of the subscription rate plan segment. Segments are numbered sequentially, starting with 1.

Type: int
Character limit: 2
Version notes: WSDL 20.0+
Values: automatically generated

SpecificBillingPeriod optional Create
Subscribe
Query
Filter

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.

Type: smallint
Character limit: 5
Version notes: WSDL 50.0+
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.

SpecificEndDate

optional

Create
Subscribe
Query
Update*
Subscribe
Amend
Filter

The specific date on which the charge ends.

Type: date
Character limit: 29
Version notes: WSDL 72.0+
Values: a valid date and time value
Note:

  • This field is only applicable when the EndDateCondition field is set to SpecificEndDate.
  • If the subscription ends before the specific 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 specific end date.
SubscriptionId required Query The ID of the subscription that the rate plan charge belongs to.

Type: zns:ID
Character limit: 32
Version notes: --
Values: a valid subscription ID

SubscriptionOwnerId required Query

The subscription owner ID of the subscription that the rate plan belongs to.

Type: zns:ID
Character limit: 32
Version notes: --
Values: a valid account ID

TCV optional

Query
Filter

The total contract value (TCV) is the value of a single rate plan charge at the segment level 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.

Type: decimal
Character limit: 16
Version notes: type is double for WSDL 18.0 and older
Values: automatically generated

TriggerDate optional

Create
Subscribe
Query
Update
Filter

The date when the charge becomes effective, and billing begins. This field is required if the TriggerEvent field value is SpecificDate.

Type

  • date: Supported as of WSDL version 69+
  • dateTime: Supported through WSDL version 68

Character limit: 29
Version notes: WSDL 17.0
Valuesa valid date and time value

TriggerEvent required

Create
Subscribe
Query
Update
Filter

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.

Type: string (enum)
Character limit: 18
Version notes: SpecificDate value is not available in WSDL 16.0 and older
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.
  • SpecificDateis valid only on the RatePlanCharge.

UnusedUnitsCreditRates

optional

Query
Filter

Specifies the rate to credit a customer for unused units of usage. This field is applicable only for overage charge models when the OverageUnusedUnitsCreditOption field value is CreditBySpecificRate.

Type: decimal
Character limit: 16
Version notes: --
Values: a valid decimal value

UOM optional

Query
Filter

Specifies the units to measure usage. Units of measure are configured in the web-based UI: Z-Billing > Settings.

Type: string
Character limit: 25
Version notes: --
Values: inherited from
ProductRatePlanCharge.UOM

UpdatedById optional

Query
Filter

The ID of the last user to update the object.

Type: zns:ID
Character limit: 32
Version notes: WSDL 20.0+
Values: automatically generated

UpdatedDate optional

Query
Filter

The date when the object was last updated.

Type: dateTime
Character limit: 29
Version notes: --
Values: automatically generated

UpToPeriods

optional

Create
Subscribe
Query
Update*
Filter

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

Type: long
Character limit: 5
Version notes: WSDL 26.0+
Values: inherited from
ProductRatePlanCharge.UpToPeriods

Note

  • You must use this field together with the UpToPeriodsType field to specify the time period. This field is only applicable only when the EndDateCondition field is set to FixedPeriod
  • You can override the value inherited from the Product Rate Plan Charge, but only when creating a new subscription or a New Product amendment.
  • Use this field to override the value in ProductRatePlanCharge.UpToPeriod.
  • If you override the value in this field, enter a whole number between 0 and 65535, exclusive.
  • If the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge end date will change accordingly up to the original period end.

UpToPeriodsType

optional

Create
Subscribe
Query
Update*
Subscribe
Amend
Filter

The period type used to define when the charge ends.

This field can be updated when Status isDraft

Type: string (enum)
Character limit: --
Version notes: WSDL 72.0+
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
UsageRecordRatingOption optional Query

Determines how Zuora processes usage records for per-unit usage charges. 

Type: string (enum)
Character limit: 18
Version notes: --
Values: automatically generated

UseDiscountSpecificAccountingCode optional Query
Filter

Determines whether to define a new accounting code for the new discount charge.

Type: boolean
Character limit: 5
Version notes: WSDL 34.0
Values: inherited from 
ProductRatePlanCharge.UseDiscountSpecificAccountingCode

Version optional

Query
Filter

The version of the rate plan charge. Each time a charge is amended, Zuora creates a new version of the rate plan charge. 

Type: long
Character limit: 5
Version notes: WSDL 20.0+
Values: automatically generated

WeeklyBillCycleDay

optional Create
Update
Query

Specifies which day of the week as the bill cycle day (BCD) for the charge.

Type: string (enum)
Version notes: WSDL 74.0+
Values: one of the following:

  • Sunday
  • Monday
  • Tuesday
  • Wednesday
  • Thursday
  • Friday
  • Saturday
cf_txtn__c optional

Create
Subscribe
Amend
Update
Query

One or more custom fields.
cf_pkn__c optional Create
Subscribe
Amend
Update
Query
One or more custom fields.

Additional Field Detail

ApplyDiscountTo

Specifies the type of charges a specific discount applies to. This field inherits its value from ProductRatePlanCharge.ApplyDiscountTo, and can be one of the following values:

  • RECURRING
  • USAGE
  • ONETIME
  • ONETIMERECURRING
  • ONETIMEUSAGE
  • RECURRINGUSAGE
  • ONETIMERECURRINGUSAGE

All field values are case sensitive: note that these values are in all-caps.

BillCycleDay

Sets the bill cycle day (BCD) for the charge. The BCD determines which day of the month customer is billed. The BCD value in the account can override the BCD in this object.

Use this field in the RatePlanCharge object only if you want to override the settings in the product's ProductRatePlanCharge object.

Use this field for recurring charges and usage charges. Omit this field for one-time charges.

Set this field value to whole number, 1 - 31. Set the value to 31 if you want to bill this charge at the end of the month, including months with fewer than 31 days. The number, 0, isn't a valid value for this object; 0 represents the auto-set trigger, which applies to Account objects, not ProductRatePlanCharge objects.

BillCycleType

Specifies how to determine the billing day for the charge.

Use this field in the RatePlanCharge object only if you want to override the settings in the product's ProductRatePlanCharge object.

Use one of the following values:

  • DefaultFromCustomer sets the bill cycle day (BCD) according to the BillCycleDay field value in related Account objects.
  • SpecificDayofMonth sets the BCD to a specific day of every month on a recurring basis. If you use this value, then you need to specify a BCD value for the BillCycleDay field in this object.
  • SubscriptionStartDay sets the BCD to the day that the subscription starts, which equates to one of the following dates. The date depends on which one you assigned to trigger the start of subscription charges in the Subscription object.
    • Contract effective date: the date that the contract for this subscription takes effect.
    • Service activation date: the date that services or products for this subscription are delivered or rendered.
    • Customer acceptance date: the date that the customer accepts the services or products for this subscription.
  • ChargeTriggerDay sets the BCD to the day that charges for this product rate plan are triggered to start.
  • SpecificDayofWeek sets the BCD to a specific day of every week on a recurring basis. If you use this value, then you need to specify a BCD value for the WeeklyBillCycleDay field in this object.

BillingPeriod

The billing period for the charge.

By default, this value is inherited from the product rate plan charge, but you have the option to override the value for recurring and usage charges when creating a new subscription or performing a New Product amendment. Omit this field for one-time charges.

If the value is set to Specific Months or Specific Weeks then you must also set a value for the SpecificBillingPeriod field. The Specific Months  or Specific Weeks value lets you specify a month or a week in the SpecificBillingPeriod field to customize the billing period for the charge.

BillingPeriodAlignment

Aligns charges within the same subscription if multiple charges begin on different dates.

This field anchors quarterly, semi-annual, or annual charges. When this value is the same for charges, then charges are added to the same subscription on different dates have aligned billing periods.

A typical use case for this object is to use the subscribe() call and default to the inherited value in ProductRatePlanCharge.BillingPeriodAlignment, then change the field value when you use an amend() call and Amendment object to add a new product.

Use one of the following values:

  • AlignToCharge starts the biling period on the first bill cycle day (BCD) on or after the charge trigger date. Charges bill on their own schedules and don't align with each other within the subscription. This value is the default value.
  • AlignToSubscriptionStart aligns all billing period to the first BCD on or after the subscription start date. Charges are aligned as soon as they're triggered.
  • AlignToTermStart aligns all billing periods to the first BCD on or after the current term start date. Charges are billed on their own schedules until the subscription reaches the end of its term and renews. The billing period for charges aligns when the subscription renews.

ChargeModel

Determines how to calculate charges. Charge models must be individually activated in Z-Billing administration.

Use one of the following values if they're active on your tenant:

  • Discount-Fixed Amount is a fixed amount discount charge model, such as a one-time, $100 discount if the customer signs up for a subscription in January.
  • Discount-Percentage is a percentage discount charge model, such as a 15% discount on all subscription charges for the initial six months of service.
  • Flat Fee Pricing is a single price or fixed amount.
  • Per Unit Pricing charges per unit.
  • Overage Pricing charges a per-unit price on units in excess of included units in the base charge. Use this charge model only for usage-based charges.
  • Tiered Pricing changes pricing progressively as volume increases. A price table calculates pricing based on tiers that each define a range of volume and the corresponding pricing rule to apply when customers purchase a quantity of units that falls within the range of the tier.

You can't create multiple discounts in a single product rate plan.

You can't update the chage model on a product rate plan charge if it's part of an existing subscription.

ChargeType

Specifies the type of charge:

  • OneTime is a charge that happens once during the subscription, such as an activation or initiation fee.
  • Recurring is a charge that repeats during the subscription, such as monthly or annually.
  • Usage is a charge assessed on a customer's actual usage during a specific billing period of a subscription. Usage is always billed in arrears because it's based on actual usage. For example, a customer's usage in January is billed in February in a monthly billing period plan.

ChargedThroughDate

The date until when a customer was billed for the charge. Use this field value when you amend a subscription to determine an EffectiveDate field value or SuspendDate field value to set the amendment to a date that doesn't require proration, such as when the amendment cancels a subscription or suspending a subscription.

DiscountLevel

Specifies if the discount applies to just the product rate plan, the entire subscription, or to any activity in the account. This field is required in the associated ProductRatePlanCharge object if the ChargeModel field value is DiscountFixedAmount or DiscountPercentage.

You can't create multiple discounts in a single rate plan. However, you can apply multiple discounts to an individual customer. Customers can have a discount of each discount level type.

For example, Sergio has a $1000 recurring subscriptioncharge. He has the following discounts to apply to that $1000 charge:

  • A rate plan discount of 10%, which equals $100, and reduces his charge from $1000 to $900:
    $1000 charge - 10% discount = $900 charge
  • A subscription discount of 20%, which equals $180, and reduces his charge from $900 to $720:
    $900 charge - 20% discount = $720 charge
  • An account discount of 30%, which equals $216, and reduces his charge from $720 to $504:
    $720 charge - 30% discount = $504 charge

Discount charge models don't support tax inclusive modes; don't use this field if the ProductRatePlanCharge.TaxMode field value is set to TaxInclusive.

Id

The ID of this object. Every object has a unique identifier that Zuora automatically assigns upon creation. You use this ID later when you work with the object. For example, if you send an amend() call to modify an existing subscription, then you need to include the specific Subscription object's ID with the call.

The ID for the RatePlanCharge object is RatePlanChargeId.

IncludedUnits

Specifies the number of usage units that are provided as part of the plan's upfront fees. Any usage that exceeds the value set in IncludedUnits is recorded as overage. This field is for usage-based fees only.

NumberOfPeriods

Specifies the number of periods to use when calculating charges in an overage smoothing charge model, which is an advanced type of usage model that avoids spikes in usage charges. If a customer's usage spikes in a single period, an overage smoothing model eases overage charges by considering usage over multiple periods. The value that you provide in the NumberOfPeriod field determines the number of these periods to consider.

OverageCalculationOption

Determines whether to calculate overage charges at the end of the smoothing period or at the individual billing periods. This field is for usage charges that use either an overage charge model or a tiered overage charge model.

OverageUnusedUnitsCreditOption

Determines whether to credit the customer with unused units of usage. Use this field for usage charges that use either an overage charge model or a tiered overage charge model.

Use NoCredit to issue no credit to the customer for unused usage. Use CreditBySpecificRate to issue credit to the customer for unused usage at a specified rate of units to credit.

Price

The price for units in the subscription rate plan. Use this field with a subscribe() call to override the price in the associated subscription rate plan charge tiers.

Prices are always stored in subscription rate plan charge tiers even when the charge model isn't tiered pricing. You can query for Price from a RatePlanCharge object unless the charge model is volume or tiered pricing. If the charged model is volume or tiered pricing, then you need to query for Price from the relevant RatePlanChargeTier.

SpecificBillingPeriod

Specifies a custom number of months for the billing period of a particular charge.

If you override the BillingPeriod when creating a new subscription or a New Product amendment, then this field is required if you set the value of the BillingPeriod field to Specific Months.

If you want to charge a customer annually, semi-annually, quarterly, or monthly, then you can simply specify that choice in the BillingPeriod field, rather than using this SpecificBillingPeriod field.

UsageRecordRatingOption

Determines how Zuora processes usage records for per-unit usage charges

This field cannot be updated. The UsageRecordRatingOption field on a charge is owned by the product catalog in the product rate plan charge. This value is not a property of the subscription rate plan charge. The subscription rate plan charge always points back to the original product rate plan charge for this data. The value for this field is EndOfBillingPeriod or OnDemand.

UseDiscountSpecificAccountingCode

Determines whether to define a new accounting code for the new discount charge.

Set the value to True to define a dedicated accounting code for the discount charge. Set the value to False to copy the accounting code from the regular charge that the discount applies to.