Preconfigured and custom metered usage

note

This topic is about Metered usage V1. Marketplaces use the metered usage V1 API, metered usage V2 API, or both, to support metered usage billing. See also: Metered usage V2.

There are two types of metered usage: preconfigured and custom. Both types require product configuration before you submit usage with the API (see Metered usage prerequisites).

Preconfigured metered usage

When you report preconfigured usage with the API, the static unit type, price, and description of the usage that are configured for the product edition or add-on product, are applied to all usage reported for the unit type.

For the edition or add-on, you can preconfigure multiple unit types and pricing for the same product edition or add-on product. For example, you could configure both of the following types for the same product edition or add-on product:

• gigabyte, with a description of Gigabytes of storage used, and price per unit of $0.15.
• hours, with a description of Hours used, and price per unit of $2.00.

Custom metered usage

With custom metered usage, you can charge users any price for usage, and change the price as needed. For example, when a customer subscribes to electricity services, you can charge a different price for electricity that they use during the day and night, or vary the price during a billing period based on demand. You can also describe the charge and units uniquely for each customer and billing period. To do so, you send the following information with the API:

• Description (required): Description of the usage or charge
• Price (required): Price for each usage event
• Unit (optional): Unit of measure for the usage quantity. If you do not include a unit, we recommend that you include the unit in the description.

How custom usage is presented and organized on invoices depends on whether you submit a unit. Scenarios and examples for market-driven electricity pricing that changes over time, follow:

Scenario 1: You send a description and price for each event

When you send a description and price for each event, usage events appear on invoices as they are submitted. There is a separate invoice line for each event and the associated description for each one. Every event description can be unique.

If the four usage events shown in the following table are submitted, the resulting invoice displays four invoice lines, each with the associated description, price, and quantity. Note that the two events for Residential electricity usage (kWh) appear on separate invoice lines.

Example custom usage submitted and displayed on invoices

Custom description (optional)	Custom price ($)	Quantity
Residential electricity usage (kWh)	0.10	1000
Residential electricity usage (kWh)	0.20	2000
Commercial electricity usage (MW)	45.00	3.0
Residential electricity usage (kWh, evening hours)	0.03	500

Scenario 2: You send a description, price, and unit for each event

When you submit a description, price, and unit for each event, the events are aggregated by unit type on invoices. Each invoice line displays the following information:

• description submitted with the first usage event for the unit type in the billing period
• total quantity of all events for the unit type
• price for the aggregated usage (the number of decimals that appear is dependent on the invoice template)

If the price is the same for all events of the same unit type, it appears on the aggregated invoice line as it was submitted.

If the prices for events of the same unit type differ, the price that appears on the aggregated invoice line is a weighted average price by quantity.

Example: If the four usage events shown in the following table are submitted, the resulting invoice displays two invoice lines, as shown in the second table.

Example custom usage submitted

Custom description (optional)	Custom price ($)	Custom unit	Quantity
Residential electricity usage	0.10	kWh	1000
Residential electricity usage	0.20	kWh	2000
Commercial electricity usage	45.00	MW	3.0
Residential electricity usage (evening hours)	0.03	kWh	500

Invoice lines for submitted custom usage

Custom description (optional)	Custom price ($)	Custom unit	Quantity
Residential electricity usage	0.1471428571	kWh	3500
Commercial electricity usage	45.00	MW	3.0

The description for the last submitted event (Residential electricity usage—Evening hours) does not appear on the invoice, because only the description submitted with the first event of that unit type in the billing period appears on invoices. The price per kWh for Residential electricity usage varied, so a weighted average price is displayed.