Skip to main content

Order Delta Tcv

Zuora

Order Delta Tcv

This article introduces the concept and calculation of the Order Delta Tcv metric, and how to access the Order Delta Tcv object and fields through Data Query.

The Order Delta Tcv 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.

This feature is only available if you have the Orders feature enabled. Orders is now generally available as of Zuora Billing Release 284 (August 2020). If you are an existing Zuora Subscribe and Amend customer and want to adopt Orders, see What is Orders Harmonization and join the Orders Harmonization community group for more information. If you want to enable Orders, submit a request at Zuora Global Support. You can still keep the existing Subscribe and Amend API integrations to create and manage subscriptions.

Order Delta Tcv

The value of an Order Delta Tcv metric is the change in TCV of a RatePlanCharge as the result of an Order. 

Order Delta Tcv will be generated asynchronously when an Order causes a change to the TCV of one-time or charges. The metrics will be associated with the Order Action that causes the change, and the rate plan charges that the action impacts. If there are also Order Line Items in the Order, Order Delta Tcv will be generated for the Order Line Items as well, representing the total contracted value for the Order Line Items.

Tcv model.jpeg

Order Delta Tcv is not generated for evergreen subscriptions.

Calculation

When calculating Order Delta Tcv for RatePlanCharges, Zuora compares the differences in TCV between the subscription version before and after the order is placed. For Order Line Items, the delta TCV grossAmount equals the grossAmount of the associated Order Line Item.

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.

The delta of TCV before and after the Order is $50 per month for an additional 3 months and therefore OrderDeltaTcv = $150 from 2022-01-01 to 2022-03-31.

Order Delta Tcv .jpg

Order Delta Tcv for this example is shown in the table below:

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 is 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 Tcv generated for the Order Line Item.

Order Delta Tcv2 .jpg

Order Delta Tcv for this example is shown as in the table below:

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 12 months, with a monthly billing period and a list price of $5.00 per unit per month. The corresponding Rate Plan Charge (actually the charge segment RPC-1)  will have a TCV of $600 ($5 per unit per month × 10 units × 12 months) from 2021-01-01 to 2021-12-31.

After 3 months, you place an order and increase the quantity to 13 units, so that the TCV of the Rate Plan Charge becomes $735 = ($5 per unit per month × 10 units × 3 months)  + ($5 per unit per month × 13 units × 9 months). 

The above changes are interpreted as an OrderDeltaTcv of -$450 for RPC-1 between 04-01 to 12-31, due to the fact that the duration of RPC-1 has shrunk; and an OrderDeltaTcv of $585 for RPC-2  between 04-01 to 12-31, because Zuora creates a new RatePlanCharge object for the new price from 04-01 to 12-31, as shown below.

Order Delta Tcv3 .jpg

StartDate

EndDate

RatePanChargeId

GrossAmount

NetAmount

2021-04-01

2022-01-01

4028fc827a0e48c1017a0e4dccc60002
(for RPC-2)

$585

$585

2021-04-01

2022-01-01

4028fc827a0e48c1017a0e58b9330014 

(for RPC-1)

-$450

-$450

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 TCV before and after an order is placed, and uses the NetAmount field to store the delta of TCV net of discounts.

When calculating the metrics, Zuora tries to apply discounts to those regular charges that have overlaps with the discount charges.

With the above example, if there is also a 20% discount applied to the regular charge, the OrderDeltaTcv becomes:

StartDate

EndDate

RatePanChargeId

GrossAmount

NetAmount

2021-04-01

2022-01-01

4028fc827a0e48c1017a0e4dccc60002
(for RPC-2)

$65

$52

2021-04-01

2022-01-01

4028fc827a0e48c1017a0e58b9330014 

(for RPC-1)

-$50

-$40

The calculation is as shown in the following diagram:

Order Delta Tcv4 .jpg

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

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 metric 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 that 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 TCV metrics for the same charge.

You can get a summary for the Order Delta Tcv metrics for the Order above using the following data query:

Select oa.Type, tcv.StartDate, tcv.EndDate, tcv.GrossAmount, tcv.NetAmount
From OrderDeltaTcv tcv 
inner join OrderAction oa on mrr.orderActionId = oa.Id
Where tcv.orderNumber = ‘O-000001’

The result is as in the following table:

Type

Start Date

End Date

Gross Amount

Net Amount

AddProduct

2021-01-01

2022-01-01

600

540

RemoveProduct

2021-04-01

2022-01-01

-600

-540