Order Delta Tcb
This article introduces the concept and calculation of the Order Delta Tcb metric, and how to access the Order Delta Tcb object and fields through Data Query.
The Order Delta Tcb metric is part of the Order Delta Metrics. If you are still using the previous Order Metrics, see Key Metrics for Orders.
As of Zuora Billing Release 306, Zuora has updated the methodologies for calculating metrics in Orders. The new methodologies are reflected in the following Order Delta Metrics objects.
It is recommended that all customers use the new Order Delta Metrics. If you are an existing Order Metrics customer and want to migrate to Order Delta Metrics, submit a request at Zuora Global Support. Whereas new customers, and existing customers not currently on Order Metrics, will no longer have access to Order Metrics, existing customers currently using Order Metrics will continue to be supported.
Order Delta Tcb
The value of an Order Delta Tcb metric is the change in estimated billing over the duration of a RatePlanCharge object as the result of an Order.
For a termed subscription, Order Delta Tcb is generated asynchronously when an Order causes a change to the TCB of one-time or recurring charges. For an evergreen subscription, Order Delta Tcb will not be generated. The metrics are associated with the Order Action that causes the change, and the Rate Plan Charges that the Order Action impacts.
If Order Line Items are present in the Order, Order Delta TCB is generated for the Order Line Items as well, representing the total estimated billing amount for the Order Line Items. Gross and Net amount of Order Delta Tcb will always equal to Order Delta Tcv that is associated with the same Order Line Item.
Order Delta Tcb is not generated for evergreen subscriptions.
Calculation
When calculating Order Delta Tcb for Rate Plan Charges, Zuora compares the differences in Tcb between the subscription version before and after the order is placed.
For Order Line Items, the delta Tcb grossAmount equals the grossAmount of the associated order line item.
Tcb for a Rate Plan Charge is the base for calculating Order Delta Tcb. Rate Plan Charge Tcb is calculated with the following methodology:
Discrepancies might exist between TCB and the actual invoice amount. TCB is rated at the time of booking, while the invoice amount is rated at the time of billing. As the rating time is different, several factors can lead to a discrepancy in the rated value, including but not limited to the following:
- Difference in the rounding result caused by the difference in discount applying sequence or bill run scope
- Change of billing rules
- Change of customer account bill cycle day (BCD)
For more scenarios when discrepancies might exist between TCB and the invoice amount, see the scenarios that cause the booking and billing variances for CCV.
Zuora split the RatePlanCharges into multiple segments based on the billing period settings on the rate plan charge. For example, if a rate plan charge starts from 2021-01-01 till 2021-04-01, and the billing cycle is configured as monthly and starts on the 1st. With price being $20 per billing period, the Tcb for the charge is calculated as $60 = $20 per billing period * 3 periods from 2021-01-01 to 2021-04-01.
With the same rate plan charge, if the bill cycle day is 16th, the charge will be splitted into two full billing periods and a partial billing period in the beginning, and one in the end.
Zuora honors the proration rules to calculate the TCB for the partial periods.
When applying discounts, Zuora tries to split the charges by billing periods and will apply discounts to those periods whose start date falls into the duration of the discount charge.
Example 1
For example, suppose that you have subscribed a customer to 10 units of your product for 12 months, with a monthly billing period and a list price of $5.00 per unit per month. Then you renew the subscription for another 3 months. Billing Period is monthly and aligned with the charge start date.
The delta of Tcb before and after the Order is $50 per month for an additional 3 months and therefore OrderDeltaTcb = $150 from 2022-01-01 to 2022-03-31.
Order Delta Tcb for this example will be:
|
StartDate |
EndDate |
RatePanChargeId |
OrderLineItemId |
GrossAmount |
NetAmount |
|
2022-01-01 |
2022-04-01 |
4028fc827a0e48c1017a0e58b9330014 (for RPC-1) |
null |
$150 |
$150 |
See Object and Fields for more details about the fields on this object.
Example 2
With the above example, if there’s also an one-off renewal service charge of $50 occurring on the renewal date, represented by an Order Line Item whose transaction date is set to be 2022-01-01. There will be an additional Order Delta Tcb generated for the Order Line Item.
Order Delta Tcbs for this example will be:
|
StartDate |
EndDate |
RatePanChargeId |
OrderLineItemId |
GrossAmount |
NetAmount |
|
2022-01-01 |
2022-04-01 |
4028fc827a0e48c1017a0e58b9330014 (for RPC-1) |
null |
$150 |
$150 |
|
2022-01-01 |
2022-01-02 |
null |
4028fc827a0e48c1017a0e58b9330014 (for OLI-1) |
$50 |
$50 |
See Object and Fields for more details about the fields on this object.
Example 3
For another example, suppose that you have subscribed a customer to 10 units of your product for 2 months, with a monthly billing period and a list price of $5.00 per unit per month. The charge starts on the 1st and the billing period starts on the 16th.
The corresponding Rate Plan Charge (actually the charge segment RPC-1) will have a TCB of $97.4 = $50(1 full billing period) + $24.2 (for the starting partial period, 50*15/31, 15=[2021-01-01, 2021-01-15], 31=[2020-12-16, 2021-01-15]) + $23.2 (for the ending partial period, 50*13/28, 13=[2021-02-16, 2021-02-28], 28=[2021-02-16, 2021-03-15]) from 2021-01-01 to 2021-03-01.
After one and half months, you place an order and increase the quantity to 13 units from 2021-02-16, so that the TCB of the Rate Plan Charge becomes $104.4 = $50(1 full billing period) + $24.2 (for the starting partial period, 50*15/31) + $30.2 (for the ending partial period, 65*13/28).
The above changes are interpreted as an OrderDeltaTcb of -$23.2 for RPC-1 between 02-16 to 03-01, due to the fact that the duration of RPC-1 has shrunk; and an OrderDeltaTcb of $30.2 for RPC-2 between 02-16 to 03-01, because Zuora creates a new RatePlanCharge object for the new price from 02-16 to 03-01, as shown below.
|
StartDate |
EndDate |
RatePanChargeId |
GrossAmount |
NetAmount |
|
2021-02-16 |
2021-03-01 |
4028fc827a0e48c1017a0e4dccc60002 |
$30.2 |
$30.2 |
|
2021-02-16 |
2021-03-01 |
4028fc827a0e48c1017a0e58b9330014 (for RPC-1) |
-$23.2 |
-$23.2 |
See Object and Fields for more details about the fields on this object.
Discounts
Order Delta Metrics uses the GrossAmount field to store the delta of the gross TCB before and after an order is placed, and uses the NetAmount field to store the delta of TCB net of discounts.
With the above example, if there is also a 20% discount applied to the regular charge, the OrderDeltaTcb becomes:
|
StartDate |
EndDate |
RatePanChargeId |
GrossAmount |
NetAmount |
|
2021-02-16 |
2021-03-01 |
4028fc827a0e48c1017a0e4dccc60002 |
$30.2 |
$24.16 |
|
2021-02-16 |
2021-03-01 |
4028fc827a0e48c1017a0e58b9330014 (for RPC-1) |
-$23.2 |
-$18.56 |
See the following diagram for more details:
Asynchronism
Order Delta Metrics will be generated asynchronously with the order. There could be a delay between the Order submission and metrics generation.
Object and Fields
The Order Delta Tcb object can be accessed through Data Query with the following fields.
|
Field Name |
Description |
|
Id |
The internal ID of the order delta metrics. |
|
OrderNumber |
The Order number for the associated Order. |
|
StartDate |
The Start Date of the metric. This is also the start date of the period where there is an impact on the metrics caused by the order. |
|
EndDate |
The End Date of the metric. This is also the end date of the period where there is an impact on the metrics caused by the order. The End Date is exclusive. |
|
GrossAmount |
The gross amount of the metric. This is the gross value of the metric without applying any discounts. |
|
NetAmount |
The net amount of the metric. This is the net value of the metric after applying the discounts.
Note: When calculating Order Delta Metrics, Zuora does not take account level discount into consideration. |
|
Currency |
ISO 3-letter currency code (uppercase) for the gross and net amount. For example, USD. |
|
OrderActionId |
The Id of the associated Order Action that creates the metric. This field can be null if the metric is generated for an Order Line Item. |
|
ChargeNumber |
The charge number of rate plan charge object what the metrics is associated with. This field can be null if the metric is generated for an Order Line Item. |
|
RatePlanChargeId |
The id of the rate plan charge object what the metrics is associated with. This field can be null if the metric is generated for an Order Line Item. |
|
ProductRatePlanChargeId |
The id of the product plan charge object of the rate plan charge object. This field can be null if the related Order Line Item is not created from a product rate plan charge |
|
OrderLineItemId |
The id of the Order Line Item associated with the metric. This field can be null if the metric is generated for a RatePlanCharge. |
|
CreatedDate |
The date time when the metric is created. |
|
UpdatedDate |
The date time when the metric is last updated. |
|
deleted |
Whether the metric is deleted. |
Data Query Use Case
You can perform queries on the Order Line Item object through Data Query. See the following example.
Example
You create an Order O-000001 containing the following order actions:
- Add a rate plan with a recurring charge of $50 per month. The term starts on 1/1/2021 and ends on 12/31/2021. A 10% discount applies to the charge.
- Remove the discount on 4/1/2021.
In this example, Zuora creates two Tcb metrics for the same charge.
You can get a summary for the Order Delta Tcb metrics for the Order above using the following data query:
Select oa.Type, tcb.StartDate, tcb.EndDate, tcb.GrossAmount, tcb.NetAmount From OrderDeltaTcb tcb inner join OrderAction oa on tcb.orderActionId = oa.Id Where tcb.orderNumber = ‘O-000001’
The result is as in the following table:
|
Type |
StartDate |
EndDate |
GrossAmount |
NetAmount |
|
UpdateProduct |
2021-01-01 |
2021-12-31 |
600 |
540 |
|
UpdateProduct |
2021-04-01 |
2021-12-31 |
-600 |
-540 |