Common Bill Format (CBF)

CloudZero has developed a standard data model to ingest cost data from any source, called the Common Bill Format. The CBF is modeled after the AWS CUR format, but simplier and more generic. This allows it to be used by many different cloud providers.

Data File General Guidelines

Data File Columns

CategoryColumnTypeCZ DimensionDescriptionRequired
Line Itemlineitem/idstringUniquely identifies this specific line item in this specific bill.
Line Itemlineitem/typestringLineItemTypeBroad category of this line item: Usage, Tax, Discount, etc. Values have special meaning (see below). If not provided, assumed to be Usage.
Line Itemlineitem/descriptionstringDescriptionAn optional description specifying additional information about this line item.
Timetime/usage_startdatetimeThe hour during which the charged usage applies. This value should be aligned to the start of the hour and will be treated as such. Note, the current version of the Common Billing Format does not currently use usage_end date.
Timetime/usage_enddatetimeThe end of a timespan to which the charged usage applies. Note that although this may be specified, currently all changes are treated as occurring in a single hour at usage_start. Future updates to the ingest process may take advantage of the usage_end value.
Resourceresource/idstringResourceUniquely identifies the object for which this charge applies. If not provided one will be created with available information.
Resourceresource/servicestringServiceThe category to which this resource belongs. Generally represents different kinds of services provided by the Cloud Provider for which the customer is charged.
Resourceresource/accountstringAccount (if action/account is not specified)The account or project to which this resource belongs (if applicable).
Resourceresource/regionstringRegion (if action/region is not specified)The region to which this resource belongs (if applicable).
Resourceresource/usage_familystringUsageFamilyCommonly a subdivision of resource/service
Resourceresource/tag:stringTag:Extra attributes associated with the resource. This column may appear multiple times with different values for
Actionaction/operationstringOperationThe thing that was done to the resource for which you're being charged.
Actionaction/usage_typestringUsageTypeCommonly a subdivision of action/operation
Actionaction/regionstringRegionIn what region the operation was performed. (May not match the resource/region for cross-region operations.)
Actionaction/accountstringAccountIn what account the operation was performed. (May not match the resource/account for cross-region operations.)
Usageusage/amountnumberA numeric value describing an amount consumed/used. E.g. GB stored/transferred, seconds executed, credits consumed
Usageusage/unitsstringA description of the units used for usage/amount
Costcost/costnumberThe cost associated with this line item. (May be negative for line items which represent discounts / credits.)
Costcost/discounted_costnumberThe net cost associated with this line item after any discounts, credits, or private pricing are applied.
Costcost/amortized_costnumberThe net effective cost associated with this line item after any discounts, credits, or private pricing are applied. It also includes any "committed use" purchases (e.g. AWS RIs or Savings Plans) amortized over all the "Usage" line items to which they apply.
Costcost/on_demand_costnumberWhat the cost of this line item would have been if no mechanism for reducing costs applied. In other words, it is the cost as if there were no discounts, applicable "committed use" purchases, private pricing, etc. This is often useful for determining one's effective savings rate.
Billbill/invoice_idstringInvoiceIdUniquely identifies a particular bill. A single billing data ID for a single month may include multiple invoices. Ideally this field will not be populated until an Invoice is closed.

Line Item Types

The lineitem/type column defines how each line items hould be interpreted.

The following values are supported:

Line Item TypeDescription
UsageThe most common type and the default. The line item represents a charge for the use of some cloud resource. “Real Cost” includes only Usage line items and uses the first available cost type provided from: amortized_cost, discounted_cost, or cost
TaxThis line item represents any tax charges. Columns in the time, resource, and action categories should only be populated if the tax is associated with applicable Usage changes. Otherwise these columns should be left blank.
SupportCharges for support or other human services. Columns in the time category should specify the start and end of the support contract.
PurchaseCharge for a one-time purchase or non-usage based subscription; for example, software bought from the AWS Marketplace. The time category columns should represent the span of time over which the purchase applies (for subscriptions with renewal) or the time of the purchase (for one-time charges).
CommittedUsePurchaseCharges for a "committed use" (RI, savings plan, etc.) purchase. "Committed use" includes any instrument for which payment is made to receive a reduced rate on future usage. This may include one-time upfront purchases or recurring monthly charges. The time category columns should represent the span of time over which the charge applies (for example, one month for monthly recurring charges.) The amortized_cost cost column of this line item should always be zero (if used).
DiscountA negative value cost associated with some Usage line item. Columns in the time, resource, and action categories of this line item should match those of the applicable Usage line item and the cost should be negative. The discounted_cost for this line item should be zero if this discount is fully accounted for in the discounted_cost of other Usage line items. (Please note: you must still include discounted_cost if it should be zero)
CreditA negative value cost not associated with any specific Usage line items. May represent an adjustment due to an error, rounding, refund, etc.
FeeA positive value charge for which no other line item type applies.
AdjustmentAn alteration made to the bill to correct for some error or rounding issue.

Cost Category Columns

There are four cost category columns cost, discounted_cost, on_demand_cost, and amortized_cost. Only cost is required, but the others may be used to help “smooth out” charges not directly associated with the use of cloud services.
If amortized_cost is not provided, discounted_cost will be used. If discounted_cost is not provided, cost will be used. To avoid this “fallback” behavior specify a value of 0 rather than leaving a field blank.

The total value across all line items for each of cost, discounted_cost, and amortized_cost should be the same. Each represents a redistribution of charges (discounts and purchases, respectively) not the inclusion or exclusion of charges. This equivalence will be validated by the billing ingest system and a billing drop will be rejected if it fails.

Cost Types

CloudZero cost types are defined in terms of the lineitem/type and different cost category columns.

  • Real Cost - Only Usage line item types are included. The amortized_cost column is used, if present, with “fallback” logic to the other cost categories if it is not.
  • Discounted Amortized Cost - All line item types are included. The amortized_cost column is used, if present, with “fallback” logic to the other cost categories if it is not.
  • Discounted Cost - All line item types are included. The discounted_cost column is used, if present, with “fallback” to cost if not.
  • On-Demand Costs - All line item types are included. The on_demand_cost column is used, if present, with “fallback” to cost if not.
  • Billed Cost - All line item types are included. The cost column is used.

Examples

Simple

In this example we purchased some Compute from “Simple Cloud”. We also made an up-front “committed use” which lowered the normal hourly rate by 50%. We received the “SpecialCompute” discount for using certain Compute instance type (Simple Cloud is running a promotion.) We also received the “MVP Discount” because we are so cool.

This first version of the bill just includes the actual charges. The cost for our Compute instances is at the reduced rate because of the “committed use” purchase. (For example, instance-0000 would have otherwise cost $24 during that hour.) The sum of the values in the cost/cost column should equal exactly what I see on my bill for March: $105.30

lineitem/typebill/providerresource/serviceresource/idtime/usage_startcost/cost
UsageSimpleCloudComputeinstance-00002022-03-16T13:00:00Z12
UsageSimpleCloudComputeinstance-00012022-03-16T13:00:00Z20
UsageSimpleCloudComputeinstance-00022022-03-16T13:00:00Z15.3
PurchaseSimpleCloudCommitedUsecommit-111-222-3332022-03-01T00:00:00Z90
DiscountSimpleCloudSpecialComputespecial-010101012022-03-16T13:00:00Z-12
DiscountSimpleCloudMVPDiscountmvp-aaa-123452022-03-01T00:00:00Z-20

Discounted Cost

It would be helpful if the discount we received for using the promoted Compute instances was actually represented in the cost of those instances. In this example we’ll include the cost/discounted_cost

lineitem/typebill/providerresource/serviceresource/idtime/usage_startcost/costcost/discounted_cost
UsageSimpleCloudComputeinstance-00002022-03-16T13:00:00Z128
UsageSimpleCloudComputeinstance-00012022-03-16T13:00:00Z2016
UsageSimpleCloudComputeinstance-00022022-03-16T13:00:00Z15.311.3
PurchaseSimpleCloudCommitedUsecommit-111-222-3332022-03-01T00:00:00Z9090
DiscountSimpleCloudSpecialComputespecial-010101012022-03-16T13:00:00Z-120
DiscountSimpleCloudMVPDiscountmvp-aaa-123452022-03-01T00:00:00Z-20-20

The SpecialCompute discount was distributed evenly over the individual instances. We also zeroed out the cost for the SpecialCompute line item because that discount has already been accounted for. We chose not to distribute the MVPDiscount since it was unrelated to the Compute instances. We copied over the values for the CommitedUse purchase and MVPDiscount, but we could have also left them blank and the cost/cost value would have been used by default.

Amortized Cost

To help our engineers better understand the real cost of those Compute instances we also want to include what we payed for the CommitedUse purchase.

lineitem/typebill/providerresource/serviceresource/idtime/usage_startcost/costcost/discounted_costcost/amortized_cost
UsageSimpleCloudComputeinstance-00002022-03-16T13:00:00Z12838
UsageSimpleCloudComputeinstance-00012022-03-16T13:00:00Z201646
UsageSimpleCloudComputeinstance-00022022-03-16T13:00:00Z15.311.341.3
PurchaseSimpleCloudCommitedUsecommit-111-222-3332022-03-01T00:00:00Z90900
DiscountSimpleCloudSpecialComputespecial-010101012022-03-16T13:00:00Z-120
DiscountSimpleCloudMVPDiscountmvp-aaa-123452022-03-01T00:00:00Z-20-20

The cost of the CommitedUse purchase was evenly distributed over all the Compute instances to which it applied (which in this case was all of them.) We left the cost/amortized_cost for the Discounts blank. We could have also copied over the values from the discounted_cost (0 and -20). The important this is the the sum of the values in the cost/amortized_cost column (including the default values for the blank cells) is still: $105.30


Did this page help you?