Common Bill Format (CBF) Reference

Common Bill Format (CBF) is CloudZero's standard format for ingesting cost data from any source. When you connect a Custom Cost Data Source, your Adaptor converts your source data into CBF before sending it to CloudZero.

CBF works with both connection methods:

• REST API: Send CBF data as JSON objects in the request body.
• S3 Bucket: Write CBF data as gzipped CSV files (.csv.gz), encoded in UTF-8.

Mapping your data to CBF

Each record in your cost data maps to a set of CBF fields, organized into four categories:

Field reference

Field details

The following fields have specific rules or behaviors beyond what the field reference table covers.

lineitem/type

Supported values for lineitem/type:

resource/id

Uniquely identifies the resource being charged. Required when resource/tag:<key> or resource/tags columns are included. Tags are time-independent, so CloudZero uses only the most recent set of tags for each unique resource ID.

CloudZero splits resource/id on the first colon (:) or forward slash (/) to extract two parts:

Avoid using colons and forward slashes in resource/id values except to separate the type and name. Additional segments after the first separator are dropped.

resource/tag:<key>

Custom attributes associated with a resource.

• Requires resource/id to be populated.
• The <key> is case sensitive and can contain letters, numbers, and the characters _ . : / = + - @. No spaces, tabs, or returns.
  • Valid: resource/tag:team, resource/tag:Product-Type
  • Invalid: resource/tag:Team Name, resource/tag:Product&Dev
• Tags appear as Tag Dimensions in CloudZero and can be used to filter or group costs.
• You can include as many unique resource/tag:<key> columns as needed.
• Only one value is stored per resource/tag:<key> per resource/id:
  • If multiple values exist, the value with the latest time/usage_start is used.
  • If all instances have identical time/usage_start dates, one is selected arbitrarily.
• The latest value is retroactively applied to all historical data in CloudZero for that resource/id.

Alternatively, you can send all tags for a record as a single JSON object using the resource/tags column instead of individual resource/tag:<key> columns. Pick one approach per file. The same key rules apply.

{"team": "Alpha", "environment": "production"}

Cost columns

If you leave an optional cost column blank, CloudZero fills it using a fallback chain. A value of 0 is not treated as blank and is used as-is.

• discounted_amortized_cost → amortized_cost → discounted_cost → cost
• amortized_cost → cost
• discounted_cost → cost
• on_demand_cost → cost

The total value across all line items for cost, discounted_cost, amortized_cost, and discounted_amortized_cost should be the same. Each column represents a different way of distributing the same charges, not the addition or removal of charges. CloudZero does not reject mismatches, but inconsistent totals produce inaccurate cost breakdowns.

cost/amortized_cost

Amortization spreads an upfront payment across the resources and time periods that benefit from it. The cost/amortized_cost field represents the effective cost after committed use purchases (for example, Reserved Instances, Savings Plans, GCP CUDs) are amortized across the Usage line items they apply to.

CloudZero does not automatically amortize based on start and stop dates you send. The cost is applied on the start date.

Examples

These examples build on each other, starting with a basic bill and progressively adding cost columns to show how discounts and committed use purchases are represented.

Basic bill

A company purchases Compute from "Simple Cloud." They made an upfront committed use purchase that lowered the hourly rate by 50%. They also received a SpecialCompute discount for using a certain instance type, and an MVP Discount. The cost/cost column totals the bill for March: $105.30.

Adding discounted cost

Adding cost/discounted_cost distributes the SpecialCompute discount across the individual instances. The SpecialCompute discount line item is zeroed out because it is already accounted for in the instance costs. The MVPDiscount is kept separate because it is unrelated to the Compute instances.

Adding amortized cost

Adding cost/amortized_cost distributes the committed use purchase across the Compute instances it applies to. The purchase line item is zeroed out. The SpecialCompute discount is also zeroed out because the discount is already reflected in the reduced amortized costs of the instances. The total across cost/amortized_cost is $105.30.

Adding Kubernetes columns

Adding Kubernetes columns provides context about which clusters, namespaces, and deployments are associated with each charge.