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, usage fees, and so on.
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 need to first query it and then update the desired field (Quantity) by ID.
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.
This object is used with the query and update calls.
In addition to the following fields, zObject contributes additional fields. For information on the field types, see Field Types.
| Name | Required? | Type | Allowable Values | Description |
|---|---|---|---|---|
| AccountingCode | No | string | 50 characters | You can use this to enter your accounting code for this charge. |
| ChargeModel | No | string (enum) | FlatFee, PerUnit, Overage, Tiered, TieredWithOverage, Volume | The charge model for this rate plan charge. |
| ChargeNumber | No | sequence | This number is automatically generated | An identifying number for the charge; this number is returned as a string. |
| ChargeType | No | string (enum) | 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. |
| Description | No | string | 255 characters | A description of this rate plan charge. |
| DMRC | No | double | 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 | 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. |
| IncludedUnits | Yes if ChargeModel is set to Overage; No otherwise | double | Any positive value | The number of units of this type of rate plan charge that is given by default. |
| MRR | No | double | 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 | 50 characters | The name of the subscription rate plan charge. |
| NumberOfPeriods | Yes if ChargeModel is set to Overage; No otherwise | long | 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. |
| OveragePrice | No | double | A valid currency amount | The price for units over the allowable amount. |
| Price | No | double | A valid currency amount | The price for units in the rate plan. |
| ProductRatePlanChargeId | Yes | zns: ID | NA | 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 | double | Any positive value | This is applicable only for per-unit charge models and flat-fee charge models. |
| RatePlanId | Yes | zns: ID | NA | The identification number of the rate plan that this charge applies to. |
| TCV | No | double | 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. |
| TriggerEvent | Yes | string (enum) | ContractEffective, CustomerAcceptance, ServiceActivation | The event that starts the billing at this charge rate for the rate plan that this charge applies to. |
| UOM | No | string | Allowable values are predefined in the Zuora admin interface | This is the unit of measure: People, minutes, or whatever other unit is being used for this rate plan charge. |
This section provides useful information for understanding and using RatePlanCharge.
When you create a RatePlan for an Amendment, RatePlanCharges are created in the background. (The system clones the selected RatePlan and all sub-objects, including RatePlanCharges.) If you want to update a RatePlanCharge, you need to query it first.
Here is an example:
QueryResult qr = query("select Name from RatePlanCharge where RatePlanId='"+id.getID()+"' and Name='test_one_time'");
RatePlanCharge z = (RatePlanCharge) qr.getRecords()[0];
RatePlanCharge c = new RatePlanCharge();
c.setId(z.getId());
c.setDescription("Test update aaa!!!");
c.setPrice(270.00);
update(c);
To change the price of a subscription, use the Price and Quantity fields with the subscribe call. When you do so, if you are using a non-tiered or non-volume model, the new charge will be taken and applied to the subscription.
If you are using a tiered model, then the new price will be applied to the tier in the subscription within which the specified Quantity falls. For example, if a subscription has a tiered pricing model like this:
And then you submit a subscribe call setting the Quantity to 8 and the Price to $9.00, then the subscription is created with a subscription price table like this:
The reason why the second tier was changed is that the Quantity of 8 units falls within the range of 6-10 units; therefore, the new price was applied to that tier.
Copyright © 2008-2009 Zuora, Inc.