RatePlanCharge
From API Documentation
A RatePlanCharge, like RatePlan, is part of a Subscription. Each subscription can have one or more rate plans, and each rate plan can have one or more rate plan charges. Rate plan charges are the actual charges for the services (rate plans) that you are giving, and can be of different types. For example, one-time fees, monthly recurring fees, and usage fees. When a RatePlan object of type NewProduct is created as part of an Amendment, the ProductRatePlans and ProductRatePlanCharges from the corresponding Product are created automatically as RatePlans and RatePlanCharges on the Amendment. To update a particular RatePlanCharge, you must query it, then update the desired fields (such as Quantity or Price).
You can also use this object to change the price of a tier in a subscription. Use the Price and Quantity fields with the subscribe call to submit a change in your pricing. See Using RatePlanCharge, below, for more information.
Please note that as of version 20.0, Zuora returns segmented RatePlanCharges. Every time a charge is changed through an amendment, Zuora will create a new segmented RatePlanCharge. Thus, you can now quickly and easily parse a charge's history, know when price or quantity were changed, and if there are any future pending changes to a charge. By default, Zuora will now return a RatePlanCharge for each segment of the charge. With RatePlanCharge.Segment, RatePlanCharge.EffectiveEndDate and RatePlanCharge.EffectiveStartDate, you can quickly:
- Determine current price/quantity of a charge (EffectiveStartDate <= Today <= EffectiveEndDate)
- See previous states of the charge (such as price/quantity) (EffectiveEndDate < Today)
- See future, pending changes (EffectiveStartDate > Today)
- Piece together an entire charge history (Order RatePlanCharge by segments, starting with segment=1)
| Name | Required? | Type | Allowed Operations: ● Yes ○ No | Allowable Values | Description |
|---|---|---|---|---|---|
| AccountingCode | No | string | ○ Create
● Query | 50 characters | You can use this to enter your accounting code for this charge. |
| ApplyDiscountTo | No | string | ○ Create
● Query | NULL, ONETIME, RECURRING, USAGE, ONETIMERECURRING, ONETIMEUSAGE, RECURRINGUSAGE, ONETIMERECURRINGUSAGE | If the RatePlanCharge is a discount charge, specify the type of charge that it affects. Available in version 26.0. |
| BillCycleDay | No. You must set BillCycleType to SpecificDayofMonth if you set this field. | int | ○ Create
● Query | 1-31 | Available in version 26.0+ of the API. Use this to override the billing day of the charge at the subscription level. Must set BillCycleType to SpecificDayofMonth to use this field. |
| BillCycleType | No. Only specify if you intend to override the settings from the ProductRatePlanCharge. | string | ○ Create
● Query | DefaultFromCustomer, SpecificDayofMonth, SubscriptionStartDay, ChargeTriggerDay | Available in version 26.0+ of the API. Use this to specify whether to set the billing day for the charge at the subscription (charge) level. Choices are using the default billing day for the account (DefaultFromCustomer), choosing a specific day of the month (SpecificDayofMonth, must specify BillCycleDay if you use this option), or setting the billing to when the subscription starts (SubscriptionStartDay) or when the charge is first triggered (ChargeTriggerDay). |
| BillingPeriodAlignment | No | string | ○ Create
● Query | AlignToCharge, AlignToSubscriptionStart, AlignToTermStart | Available in version 14.0+ of the API. Use this to specify how the charge should be aligned. Typical use case is to default to the value specified in the product catalog when making the subscribe() call, and to set as desired when adding charges with an Add Product amendment. |
| ChargedThroughDate | No, system generated. | dateTime | ○ Create
● Query | Available as of version 20.0. The date to when the customer account has been billed for this charge. Users wanting to make amendments that do not incur any pro-rated charges will want use this date. | |
| ChargeModel | No | string (enum) | ○ Create
● Query | Flat Fee Pricing, Per Unit Pricing, Overage Pricing, Tiered Pricing, Tiered With Overage Pricing, Volume Pricing, Discount-Fixed Amount, Discount-Percentage | The charge model for this rate plan charge. |
| ChargeNumber | No | sequence | ○ Create
● Query | This number is automatically generated if not specified. Must be unique if specified (can be specified in subscribe() call via the API, or in the UI when creating the subscription). 50 characters maximum. | An identifying number for the charge; this number is returned as a string. |
| ChargeType | No | string (enum) | ○ Create
● Query | OneTime, Recurring, Usage | The type of charge this is. One-time fees are for charges that are made only once; for example, at the start of the subscription, or when changes are made. Monthly recurring fees are for charges that are made every month (for example, the monthly charge for the subscription). Usage fees are charges for using specific items, such as a number of minutes over what is allowed in the monthly subscription. |
| CreatedById | System generated, always exists | ZNS:Id | ○ Create
● Query | 32 characters maximum. This field is not editable. | Available as of version 20.0 of the API. The Zuora system automatically generates this Id of the user who created the object. |
| CreatedDate | System generated, always exists | dateTime | ○ Create
● Query | This field is not editable. | Available as of version 20.0 of the API. The Zuora system automatically generates this, and denotes when the objects was first created. |
| Description | No | string | ○ Create
● Query | 500 characters maximum | A description of this rate plan charge. |
| DiscountAmount | No. Only used if overriding value from the product catalog. | decimal (currency) | ○ Create
● Query | Available as of version 26.0 of the API. Used for charge model Discount-Fixed Amount. Specifies the amount of the discount. | |
| DiscountLevel | No | string | ○ Create
● Query | account, rateplan, subscription | Available as of version 26.0 of the API. Specifies if the discount should be applied to just the rate plan, to entire subscription, or customer account. |
| DiscountPercentage | No. Only used if overriding value from the product catalog. | decimal | ○ Create
● Query | Available as of version 26.0 of the API. Used for charge model Discount-Percentage. Specifies the amount of the discount. | |
| DMRC | No | double (v1.0-18.0) / decimal (v19.0+) | ○ Create
● Query | This is automatically calculated | Change in Monthly Recurring Charges. (D stands for Delta.) Also known as Change in Monthly Recurring Revenue. This represents the change in MRR that is represented by an amendment or new subscription. Although this value is automatically generated, it can be queried using the query call. |
| DTCV | No | double (v1.0-18.0) / decimal (v19.0+) | ○ Create
● Query | This is automatically calculated | Change in Total Contract Value. Represents the change in TCV that a new amendment or subscription represents from its previous value. Although this value is automatically generated, it can be queried using the query call. |
| EffectiveEndDate | System generated, always exist | dateTime | ○ Create
● Query | Valid dateTime stamp | Available as of version 20.0. The date when the (segmented) charge ends/ended. |
| EffectiveStartDate | System generated, always exist | dateTime | ○ Create
● Query | Valid dateTime stamp | Available as of version 20.0. The date when the (segmented) charge starts/started. |
| IncludedUnits | Yes if ChargeModel is set to Overage or Tiered with Overage. Otherwise, no. | double (v1.0-18.0) / decimal (v19.0+) | ○ Create
● Query | Any positive value | The number of units of this type of rate plan charge that is given by default. |
| IsLastSegment | System-generated, always exists. | boolean | ○ Create
● Query | True/False | Available in version 24.0+ of the API. Specifies whether the Segment of RatePlanCharge is the latest segment. |
| MRR | No | double (v1.0-18.0) / decimal (v19.0+) | ○ Create
● Query | This is automatically calculated | Monthly Recurring Revenue. Also known as Monthly Recurring Charges, or MRC. In any given month, the MRR is the amount of recurring charges occurring in that month. One-time charges and Usage charges are not included in this calculation. Although this value is automatically generated, it can be queried using the query call. |
| Name | No | string | ○ Create
● Query | 50 characters maximum | The name of the subscription's rate plan charge. |
| NumberOfPeriods | Yes if ChargeModel is set to Overage orTieredWithOverage. Otherwise, no. | long | ○ Create
● Query | Any positive value | The number of periods over which to calculate the charge. For example, you may wish to allow averaging (smoothing) of charges over three monthly billing cycles, so that even if a customer went over their allowed units one month, if they went under by a sufficient amount the next month, they are not billed overage fees. This applies only to the only to the Overage and TieredWithOverage models of ProductRatePlanCharge. |
| OriginalId | No | zns:ID | ○ Create
● Query | 50 characters maximum. | The source RatePlanCharge ID. |
| OverageCalculationOption | No, only used for Usage charges that have Overage or Tiered With Overage charge models. | string | ○ Create
● Query | EndOfSmoothingPeriod (default), PerBillingPeriod | Specifies how Zuora should calculate overage, whether to calculate at the end of the smoothing period or per billing period. |
| OveragePrice | No | double (v1.0-18.0) / decimal (v19.0+) | ○ Create
● Query | A valid currency amount | The price for units over the allowed amount. |
| OverageUnusedUnitsCreditOption | No, only used for Usage charges that have Overage or Tiered With Overage charge models. | string | ○ Create
● Query | NoCredit (default), CreditBySpecificRate | Specifies how Zuora should handle unused units of usage, whether or not credit is given to the customer. |
| Price | No | double (v1.0-18.0) / decimal (v19.0+) | ○ Create
● Query | A valid currency amount | The price for units in the rate plan. This should only be used for subscribe() and subscribeWithExistinAccount() calls. It is meant for overriding the price of a given charge, and is short cut for setting the price stored on the associated RatePlanChargeTiers.
Note: Price is always stored at the RatePlanChargeTier level, even if the pricing model is not tiered. For convenience, you can usually query for price from that RatePlanCharge. However, you will always need to query for price from RatePlanChargeTier level for volume and tiered pricing models. Also, you cannot query for both price and quantity at the same time. |
| PriceIncreasePercentage | No | decimal | ● Create
● Query | A positive or negative integer from 0 to 100 or 0 to -100. | Specify the percentage to increase or decrease the price of renewed subscriptions. See Automated Price Change (Uplift) for Renewed Subscriptions for more information. |
| ProcessedThroughDate | No, system generated | dateTime | ○ Create
● Query | Available as of version 20.0. The date for which the charge has been processed through. When billing in arrears, this will be the same as the ChargedThroughDate. It is also the earliest date a charge can be amended. | |
| ProductRatePlanChargeId | Yes | zns:ID | ○ Create
● Query | The identification number of a valid product rate plan charge. Specifies the product rate plan charge that this rate plan is associated to. | |
| Quantity | Yes if the charge model is a quantity-based one (such as Tiered, Volume, Per-Unit) and there is no default quantity set for the charge. | double (v1.0-18.0) / decimal (v19.0+) | ○ Create
● Query | Any positive value | This is applicable only for per-unit charge models and flat-fee charge models.
Note: You cannot query for both price and quantity at the same time. |
| RatePlanId | Yes | zns:ID | ○ Create
● Query | The identification number of the rate plan that this charge applies to. | |
| RolloverBalance | No, read-only | decimal | ○ Create
● Query | A valid currency amount. | Specifies the amount of units of measure carried over ("rolled over") from previous periods. Only applicable to Usage based charges with overage models. |
| Segment | System generated, always exists | int | ○ Create
● Query | An integer value of 1 or greater | As of version 20.0. The identifying number (order) of the segment. Segments are numbered sequentially, starting with 1. |
| TCV | No | double (v1.0-18.0) / decimal (v19.0+) | ○ Create
● Query | This is automatically calculated | Total Contract Value: The value of all charges in a subscription over the lifetime of the subscription. This includes both recurring charges as well as one-time charges, but not usage charges. Although this value is automatically generated, it can be queried using the query call. |
| TriggerDate | Yes if TriggerEvent=SpecificDate | datetime | ○ Create
● Query | Valid date for triggering charges | Available in Version 17.0 of the API. The date when the charge becomes effective, and Zuora will begin billing. |
| TriggerEvent | Yes | string (enum) | ○ Create
● Query | ContractEffective, CustomerAcceptance, ServiceActivation, and SpecificDate (SpecificDate available in version 17.0) | The event that starts the billing at this charge rate for the rate plan that this charge applies to. |
| UnusedUnitsCreditRates | No, only used with Usage charges that have Overage or Tiered With Overage charge models. | decimal | ○ Create
● Query | Only used for Overage charge models and when OverageUnusedUnitsCreditOption is set to "CreditBySpecificRate." Specifies the rate used to credit the customer for unused units of usage. | |
| UOM | No | string | ○ Create
● Query | Allowable values are defined in the Admin interface | This is the unit of measure that is being used for this charge. |
| UpdatedById | System generated, always exists | ZNS:Id | ○ Create
● Query | 32 characters maximum. This field is not editable. | Available as of version 20.0 of the API. The Zuora system automatically generates this Id of the user who last updated the object. |
| UpdatedDate | System generated, always exists | dateTime | ○ Create
● Query | This field is not editable. | Available as of version 20.0 of the API. The Zuora system automatically generates this, and denotes when the objects was last updated. |
| UpToPeriods | No | long | ○ Create
● Query | Must be an integer. | Available as of version 26.0. On Discount items, this field specifies the number of billing periods the discount charge should be applied. If not specified, it defaults to the value of set in the Product Catalog. If that value is not set, the discount will be set to recur indefinitely.
For non-discount items, this field tracks the number of periods to pre-pay. |
| UseDiscountSpecificAccountingCode | No | boolean | ○ Create
● Query | true, false | If this is set to true, the accounting code will be copied from another (non-discount) charge. If this is false, you can define a dedicated accounting code on the new discount charge.
|
| Version | System generated, always exists | long | ○ Create
● Query | An integer value of 1 or greater | As of version 20.0. The version of the rate plan charge. Each time a charge is amended, a new version of the rate plan changed is created. |
