Product Items

Overview

Product items represent some value metric of business that customers can pay for. Product items are atomic units that describe some aspect of the business or software products they are selling. Example of product items are API calls, data storage, number of users, support plan, feature flag, transaction volume, or support plan. Product item represents how product usage occurs, can be measured, tracked, and charged.

Product Item Configuration

Product Item is a resource used with Product Plans. See Product Plans for using product items on offerings. A product item can be associated with multiple Offerings.

By associating a product items with multiple product plans, the same product item can be reused without redundant information. For example, a SaaS business has a product item of $1 per 1,000 API requests. The same product item can be associated with a public offering called Enterprise Plan as well as a private offering similar to Enterprise Plan but with additional discount terms, since the private offering is created for a specific customer's sales deal.

These properties are configurable for a product item.

• Name Display name of a product item. It shows up in dashboard, is returned by API, and appear on SaaS customer invoice. Required.

• Usage Measurement Measurement specifies how a product item is measured and collected by Paigo. Measurement is an optional property of product item. See Meter Usage Data at Scale for more details.

• Consumption Unit Unit of tracking usage of the product item. Required.

  • Count-based The usage doesn't have a unit. Such as API requests are tracked as the number of API requests without a unit.

  • Time-based The usage is tracked in the matter of time. Paigo supports second, minute and hour and day.

  • Data-based The usage is tracked in the matter of data size. Paigo supports gigabyte, megabyte, kilobyte, and byte.

• Usage Increment The chunk of consumption units that is calculated for billing. The final billable usage must be multiple of usage increment. Examples of usage increment can be 1 million API calls, 1 hour of compute time (rather than 1 minute of compute time). As an example to use usage increment, if 1 hour consumption is specified as the billing usage increment, then 1 Hour and 5 Minutes consumption may be treated as 1 Hour of Consumption or 2 Hour of Consumption, depending on the rounding algorithm. Another example is 1,000 API calls. 1,001 API calls may be treated as 1,000 API calls, or 2,000 API calls, depending on the rounding algorithm. Default 1.

• Rounding The algorithm used to calculate the total number of usage increment.

  • Ceiling: Ceiling algorithm rounds up. As an example, if 1 hour is specified as the usage increment, then 1 hour and 5 minutes consumption is calculated as 2 hours of consumption with ceiling algorithm.

  • Floor: Floor algorithm rounds down. As an example, if 1 hour is specified as the usage increment, then 1 hour and 5 minutes consumption is calculated as 1 hour of consumption with floor algorithm.

  • Rounding: Rounding algorithm rounds data point to the closest integer. As an example, if 1 hour is specified as the usage increment, then 1 hour and 5 minutes consumption is calculated as 1 hour of consumption, and 1 hour 55 minutes consumption is calculated as 2 hour of consumption.

• Usage Entitlement Numerical value represents the amount limit customers can use on a plan. Used with Fixed Subscription Offering type. SaaS customers who enrolled in a Fixed Subscription are entitled to use the amount of product in the current product item up to the value specified in this property. For example, a subscription may entitle customers to make up to 1,000,000 API requests. Entitlement can be used jointly with Allow Overage for overage usage, and Consumption Price for overage charge beyond entitlement.

• Overage Allowed The property to determine whether overage usage is allowed and taken into account in billing.

• Consumption Price The price to calculate the bill for per usage increment. Such as price for per 1,000,000 API call.

  • For usage-based offering, this property specifies the unit price of usage.

  • For fixed subscription offering, this property specifies the unit price of overage usage beyond Usage Entitlement. A usage entitlement must be specified in order to have Consumption Price take effect.

• Aggregation Interval The time period that multiple raw usage data points will be aggregated together using Aggregation Method to 1 data point that is used to calculate the bill. For example, an aggregation interval may be 1 hour so that all of the usage amount in an hour is aggregated together into one data point.

• Aggregation Method The algorithm to aggregate multiple raw usage data points into one aggregated data point.

  • Sum

  • Average

  • Maximum

  • Minimum

  • Count

Understand How Billing Aggregation Works

There are two kinds of usage data exist in Paigo: raw usage data and aggregated usage data. Raw usage data are typically more, granular, frequent, real-time or near real-time, whereas aggregated usage data are typically less, high-level, infrequent, and batch processed so that they are not real-time.

As an example, the raw usage data of a product item for GPU usage might be 187 milliseconds, 658 milliseconds, 981 milliseconds in a time sequence within an hour. An aggregated usage data point would be 1826 milliseconds for this hour, which is the sum of three values. In this case, the way to aggregate three data points into one is pretty straightforward, which is to sum up all the data. However, in real-world pricing scenarios, there could be a lot of complicated ways to aggregate usage data. The aggregation can be determined by various input. The following properties on product items are used to determine how aggregations are done for billing.

• Usage Increment

• Rounding

• Aggregate Interval

• Aggregate Method

To best illustrate how the aggregation works, we are using the following example of a product item called API call. The configuration of this product item is shown below.

• Usage Increment: 1,000,000 API Calls

• Rounding: Ceiling

• Aggregate Interval: Hour

• Aggregate Method: Count

• Consumption Price: $0.01 / 1,000,000 API calls

The SaaS business would send usage data 1 to Paigo API every time one API call is made by a customer. Those 1s are treated as raw usage data with their timestamp and other metadata. In order to calculate a customer's total usage and bill for a month, the following step is performed by Paigo:

1. For each Hour, Count the total number of usage records. (As defined in Aggregate Interval -> Hour, and Aggregate Method -> Count). Such as 1,000,001 API calls from 00:00 to 01:00, and 1,999,999 API calls from 01:00 to 02:00.

2. Divide the usage per hour by usage increment to calculate the multiplier of usage increment, such as 1,000,001 / 1,000,000 = 1.000001 for 00:00 to 01:00, and 1,999,999 / 1,000,000 = 1.999999 for 01:00 to 02:00. (As defined in Usage Increment -> 1,000,000)

3. Round the multiplier of usage increment with Ceiling algorithm. (As defined in Rounding -> Ceiling). Such as ceiling(1.000001) = 2 for 00:00 to 01:00 and ceiling(1.999999) = 2 for 01:00 to 02:00.

4. Multiply the multiplier with the usage increment. Such as 2 * 1,000,000 = 2 Million API calls from 00:00 to 01:00, and 2 * 1,000,000 = 2 Million API calls from 01:00 to 02:00.

5. Multiply the aggregated usage data with consumption price $0.01. (As defined in Consumption Price -> $0.01) to get the amount due in fiat currency for each hour. Such as 2,000,000 * ($0.01 / 1,000,000 API calls) = $0.02 for both hours 00:00 to 01:00 and 01:00 to 02:00.

6. Add the amount due together for each hour for the billing month to calculate the total final bill. In this example, the total amount due from 00:00 to 02:00 is $0.02 + $0.02 = $0.04.

For a more practical view of using different configurations of product items, read the Model Pricing Structure chapter to see how popular real world pricing strategies are implemented in Paigo.