Skip to main content

MetricsUtil Class

Zuora

MetricsUtil Class

This article describes the MetricsUtil class, its global methods and the related classes. The MetricsUtil class provides a set of global methods for programmatically fetching various metrics of a Quote. The classes described in this article were introduced in Zuora Quotes 9.6.

MetricsUtil Global Methods

The MetricsUtil class provides the following global methods.

Method Return Type Description
getExistingInvoiceItems(String quoteId) InvoiceItemsResult

Retrieves the list of invoice items associated with a specified Quote. The invoice items are generated from bill runs in Zuora.

The quoteId is the unique Salesforce Id of the Quote that you want to fetch the invoice items from.

The method returns an InvoiceItemsResult object that contains the list of invoice items. See InvoiceItemsResult Class below for the details.

The method returns at a maximum of 2000 records.

getExistingInvoiceItems(String quoteId, Date startDate, Date endDate) InvoiceItemsResult

Retrieves the list of invoice items whose serviceStartDate and serviceEndDate are between the startDate and endDate. The invoice items are generated from bill runs in Zuora. 

The quoteId is the unique Salesforce Id of the Quote that you want to fetch the invoice items from.

The method returns an InvoiceItemsResult object that contains the list of invoice items. See InvoiceItemsResult Class below for the details.

The method returns at a maximum of 2000 records.

getPreviewedInvoiceItems(String quoteId) InvoiceItemsResult

Gets a preview list of the expected invoice items through the end of the subscription term. 

This method is only applicable to Quotes that are not sent to Zuora. 

The quoteId is the unique Salesforce Id of the Quote that you want to preview the invoice items from.

The method returns an InvoiceItemsResult object that contains the list of invoice items. See InvoiceItemsResult Class below for the details.

MetricsUtil.InvoiceItem Class

MetricsUtil.InvoiceItem is a wrapper class that encapsulates a particular invoice item object. This class contains the following global properties.

Property

Type

Description

serviceStartDate String The start date of the service period associated with this invoice item. The date format is “YYYY-MM-DD”.
serviceEndDate String The end date of the service period associated with this invoice item. The date format is “YYYY-MM-DD”.
processingType String Indicates the type of the invoice item. Possible values are “Charge” and “Discount".
chargeAmount Decimal The amount being charged for the invoice item. This amount does not include taxes regardless of whether the tax mode of the charge is inclusive or exclusive.
taxAmount Decimal The amount of tax applied to the charge of the invoice item.
chargeNumber String The unique identifier of the charge of the invoice item.
productRatePlanChargeId String The Id of the product rate plan charge that is associated with this invoice item.
invoiceId String The Id of the invoice that is associated with this invoice item.
subscriptionId String The Id of the subscription that is associated with this invoice item.

MetricsUtil.InvoiceItemsResult Class

The MetricsUtil.InvoiceItemsResult encapsulates the list of invoice items along with the Boolean field of success indicator. This class contains the following global properties.

Property

Type

Description

invoiceItems List<InvoiceItem> A List of InvoiceItem objects returned by the API call. The result list is sorted by serviceStartDate and processingType fields. See InvoiceItem Class above for more information.
message String This property will be filled with an appropriate error message when the value of success field is false. Typically it contains an error code along with an error or validation message returned by the API call. You can use success and message properties to verify whether the operation is successful or not.
success Boolean An indicator for the success status of the operation.

Code Sample

Get a Preview List of Invoice Items from an Annually Billed Charge

// Assuming this quote is a two year termed quote with an annually billed charge added.
String quoteId = 'a18f4000001cjfb';
zqu.MetricsUtil.InvoiceItemsResult result = zqu.MetricsUtil.getPreviewedInvoiceItems(quoteId);
System.debug(JSON.serialize(result));
 
Output:
{
  "success": true,
  "message": null,
  "invoiceItems": [
    {
      "taxAmount": 0,
      "subscriptionId": null,
      "serviceStartDate": "2018-01-01",
      "serviceEndDate": "2018-12-31",
      "productRatePlanChargeId": "2c92c8f9632a136201632cebf6d60ce2",
      "processingType": "Charge",
      "invoiceId": null,
      "chargeNumber": "a11f4000001TV1LAAW",
      "chargeAmount": 10
    },
    {
      "taxAmount": 0,
      "subscriptionId": null,
      "serviceStartDate": "2019-01-01",
      "serviceEndDate": "2019-12-31",
      "productRatePlanChargeId": "2c92c8f9632a136201632cebf6d60ce2",
      "processingType": "Charge",
      "invoiceId": null,
      "chargeNumber": "a11f4000001TV1LAAW",
      "chargeAmount": 10
    }
  ]
}

Get a Preview List of Invoice Items from an Annually Billed Charge with Discount Applied

// Assuming this quote is a two year termed quote with an annually billed charge with discount applied.
String quoteId = 'a18f4000001f0arAAA';
zqu.MetricsUtil.InvoiceItemsResult result = zqu.MetricsUtil.getPreviewedInvoiceItems(quoteId);
System.debug(JSON.serialize(result));
 
Output:
{
  "success": true,
  "message": null,
  "invoiceItems": [
    {
      "taxAmount": 0,
      "subscriptionId": null,
      "serviceStartDate": "2018-01-01",
      "serviceEndDate": "2018-12-31",
      "productRatePlanChargeId": "2c92c8f9632a136201632cebf6d60ce2",
      "processingType": "Charge",
      "invoiceId": null,
      "chargeNumber": "a11f4000001TV6CAAW",
      "chargeAmount": 10
    },
    {
      "taxAmount": 0,
      "subscriptionId": null,
      "serviceStartDate": "2018-01-01",
      "serviceEndDate": "2018-12-31",
      "productRatePlanChargeId": "2c92c8f9632a130801632d574efa1043",
      "processingType": "Discount",
      "invoiceId": null,
      "chargeNumber": "a11f4000001TV6HAAW",
      "chargeAmount": -1
    },
    {
      "taxAmount": 0,
      "subscriptionId": null,
      "serviceStartDate": "2019-01-01",
      "serviceEndDate": "2019-12-31",
      "productRatePlanChargeId": "2c92c8f9632a136201632cebf6d60ce2",
      "processingType": "Charge",
      "invoiceId": null,
      "chargeNumber": "a11f4000001TV6CAAW",
      "chargeAmount": 10
    },
    {
      "taxAmount": 0,
      "subscriptionId": null,
      "serviceStartDate": "2019-01-01",
      "serviceEndDate": "2019-12-31",
      "productRatePlanChargeId": "2c92c8f9632a130801632d574efa1043",
      "processingType": "Discount",
      "invoiceId": null,
      "chargeNumber": "a11f4000001TV6HAAW",
      "chargeAmount": -1
    }
  ]
}

Get a Preview List of Invoice Items from an Annually Billed Charge with Tax

// Assuming this quote is a two year termed quote with an annually billed charge with tax added.
String quoteId = 'a18f4000001cjqX';
zqu.MetricsUtil.InvoiceItemsResult result = zqu.MetricsUtil.getPreviewedInvoiceItems(quoteId);
System.debug(JSON.serialize(result));
 
Output:
{
  "success": true,
  "message": null,
  "invoiceItems": [
    {
      "taxAmount": 5,
      "subscriptionId": null,
      "serviceStartDate": "2018-01-01",
      "serviceEndDate": "2018-12-31",
      "productRatePlanChargeId": "2c92c8f9632a1308016338a3ef9945f4",
      "processingType": "Charge",
      "invoiceId": null,
      "chargeNumber": "a11f4000001TVGTAA4",
      "chargeAmount": 10
    },
    {
      "taxAmount": 5,
      "subscriptionId": null,
      "serviceStartDate": "2019-01-01",
      "serviceEndDate": "2019-12-31",
      "productRatePlanChargeId": "2c92c8f9632a1308016338a3ef9945f4",
      "processingType": "Charge",
      "invoiceId": null,
      "chargeNumber": "a11f4000001TVGTAA4",
      "chargeAmount": 10
    }
  ]
}

Get Existing Invoice Items from an Annually Billed Charge

 // Assuming this quote is a two year termed quote with an annually billed charge added.
String quoteId = 'a18f4000001cu2r';
MetricsUtil.InvoiceItemsResult result = MetricsUtil.getExistingInvoiceItems(quoteId);
System.debug(JSON.serialize(result));
 
Output:
{
  "success": true,
  "message": null,
  "invoiceItems": [
    {
      "taxAmount": 0,
      "subscriptionId": "2c92c8f96361a68b016365f64236157d",
      "serviceStartDate": "2018-01-01",
      "serviceEndDate": "2018-12-31",
      "productRatePlanChargeId": "2c92c8f96361a68b016365f6424f1582",
      "processingType": "Charge",
      "invoiceId": "2c92c8f96361a68b016365f6436f159c",
      "chargeNumber": "C-00000022",
      "chargeAmount": 10
    },
    {
      "taxAmount": 0,
      "subscriptionId": "2c92c8f96361a68b016365f64236157d",
      "serviceStartDate": "2019-01-01",
      "serviceEndDate": "2019-12-31",
      "productRatePlanChargeId": "2c92c8f96361a68b016365f6424f1582",
      "processingType": "Charge",
      "invoiceId": "2c92c8f96361a68b016365f6436f159c",
      "chargeNumber": "C-00000022",
      "chargeAmount": 10
    }
  ]
}

Get Existing Invoice Items from an Annually Billed Charge with Discount Applied

// Assuming this quote is a two year termed quote with an annually billed charge with discount applied.
String quoteId = 'a18f4000001cu44';
MetricsUtil.InvoiceItemsResult result = MetricsUtil.getExistingInvoiceItems(quoteId);
System.debug(JSON.serialize(result));
 
Output:
{
  "success": true,
  "message": null,
  "invoiceItems": [
    {
      "taxAmount": 0,
      "subscriptionId": "2c92c8f96361a68b0163664645ca1820",
      "serviceStartDate": "2018-01-01",
      "serviceEndDate": "2018-12-31",
      "productRatePlanChargeId": "2c92c8f96361a68b0163664645e51825",
      "processingType": "Charge",
      "invoiceId": "2c92c8f96361a68b0163664648991856",
      "chargeNumber": "C-00000026",
      "chargeAmount": 10
    },
    {
      "taxAmount": 0,
      "subscriptionId": "2c92c8f96361a68b0163664645ca1820",
      "serviceStartDate": "2018-01-01",
      "serviceEndDate": "2018-12-31",
      "productRatePlanChargeId": "2c92c8f96361a68b016366464625182a",
      "processingType": "Discount",
      "invoiceId": "2c92c8f96361a68b0163664648991856",
      "chargeNumber": "C-00000027",
      "chargeAmount": -1
    },
    {
      "taxAmount": 0,
      "subscriptionId": "2c92c8f96361a68b0163664645ca1820",
      "serviceStartDate": "2019-01-01",
      "serviceEndDate": "2019-12-31",
      "productRatePlanChargeId": "2c92c8f96361a68b0163664645e51825",
      "processingType": "Charge",
      "invoiceId": "2c92c8f96361a68b0163664648991856",
      "chargeNumber": "C-00000026",
      "chargeAmount": 10
    },
    {
      "taxAmount": 0,
      "subscriptionId": "2c92c8f96361a68b0163664645ca1820",
      "serviceStartDate": "2019-01-01",
      "serviceEndDate": "2019-12-31",
      "productRatePlanChargeId": "2c92c8f96361a68b016366464625182a",
      "processingType": "Discount",
      "invoiceId": "2c92c8f96361a68b0163664648991856",
      "chargeNumber": "C-00000027",
      "chargeAmount": -1
    }
  ]
}

Get Existing Invoice Items from an Annually Billed Charge with Tax

// Assuming this quote is a two year termed quote with an annually billed charge with tax added.
String quoteId = 'a18f4000001d02P';
MetricsUtil.InvoiceItemsResult result = MetricsUtil.getExistingInvoiceItems(quoteId);
System.debug(JSON.serialize(result));
 
Output:
{
  "success": true,
  "message": null,
  "invoiceItems": [
    {
      "taxAmount": 5,
      "subscriptionId": "2c92c8f963696f3601636a8b6ecd0428",
      "serviceStartDate": "2018-01-01",
      "serviceEndDate": "2018-12-31",
      "productRatePlanChargeId": "2c92c8f963696f3601636a8b6ee8042d",
      "processingType": "Charge",
      "invoiceId": "2c92c8f963696f3601636a8b70a10446",
      "chargeNumber": "C-00000034",
      "chargeAmount": 10
    },
    {
      "taxAmount": 5,
      "subscriptionId": "2c92c8f963696f3601636a8b6ecd0428",
      "serviceStartDate": "2019-01-01",
      "serviceEndDate": "2019-12-31",
      "productRatePlanChargeId": "2c92c8f963696f3601636a8b6ee8042d",
      "processingType": "Charge",
      "invoiceId": "2c92c8f963696f3601636a8b70a10446",
      "chargeNumber": "C-00000034",
      "chargeAmount": 10
    }
  ]
}