The customer usage object

This object represents the usage-based charges associated with one of your customers for a defined billing period. It allows you to monitor customer usage throughout the period.

The customer usage object

{
  "customer_usage": {
    "from_datetime": "2022-07-01T00:00:00Z",
    "to_datetime": "2022-07-31T23:59:59Z",
    "issuing_date": "2022-08-01T23:59:59Z",
    "lago_invoice_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "currency": "EUR",
    "amount_cents": 123,
    "taxes_amount_cents": 200,
    "total_amount_cents": 123,
    "charges_usage": [
      {
        "units": "1.0",
        "events_count": 10,
        "amount_cents": 123,
        "amount_currency": "EUR",
        "charge": {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "charge_model": "graduated",
          "invoice_display_name": "Setup"
        },
        "billable_metric": {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "name": "Storage",
          "code": "storage",
          "aggregation_type": "sum_agg"
        },
        "filters": [
          {
            "units": "0.9",
            "amount_cents": 1000,
            "events_count": 10,
            "invoice_display_name": "AWS eu-east-1",
            "values": {
              "region": "us-east-1"
            }
          }
        ],
        "grouped_usage": [
          {
            "amount_cents": 1000,
            "events_count": 10,
            "units": "0.9",
            "grouped_by": {
              "additionalProp1": "string",
              "additionalProp2": "string",
              "additionalProp3": "string"
            },
            "filters": [
              {
                "units": "0.9",
                "amount_cents": 1000,
                "events_count": 10,
                "invoice_display_name": "AWS eu-east-1",
                "values": {
                  "region": "us-east-1"
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

Attributes

customer_usage · object

Hide object

from_datetime · string · required

The lower bound of the billing period, expressed in the ISO 8601 datetime format in Coordinated Universal Time (UTC).

to_datetime · string · required

The upper bound of the billing period, expressed in the ISO 8601 datetime format in Coordinated Universal Time (UTC).

issuing_date · string · required

The date of creation of the invoice.

amount_cents · integer · required

The amount in cents, tax excluded.

amount_currency · string · required

The currency of the customer’s current usage amount excluding tax.

total_amount_cents · integer · required

The total amount in cents, tax included.

total_amount_currency · string · required

The currency of the customer’s current usage amount including tax.

vat_amount_cents · integer · required

The tax amount in cents.

vat_amount_currency · string · required

The currency of the customer’s current usage tax.

lago_invoice_id · string

A unique identifier associated with the invoice related to this particular usage record. In cases where no invoice has been generated for this particular usage, the field value will be null.

charges_usage · array · required

Show charges_usage

units · string · required

The number of units consumed by the customer for a specific charge item.

amount_cents · integer · required

The amount in cents, tax excluded, consumed by the customer for a specific charge item.

amount_currency · string · required

The currency of a usage item consumed by the customer.

events_count · string · required

The quantity of usage events that have been recorded for a particular charge during the specified time period. These events may also be referred to as the number of transactions in some contexts.

charge · object · required

Show charge

lago_id · string · required

Unique identifier assigned to the charge within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the charge’s record within the Lago system.

charge_model · string · required

The pricing model applied to this charge. Possible values are standard, graduated, percentage, package or volume.

billable_metric · object · required

Show billable_metric

lago_id · string · required

Unique identifier assigned to the billable metric within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the billable metric’s record within the Lago system.

name · string · required

The name of the billable metric used for this charge.

code · string · required

The code of the billable metric used for this charge.

aggregation_type · string · required

The aggregation type of the billable metric used for this charge. Possible values are count_agg, sum_agg, max_agg or unique_count_agg.

filters · object · required

Show filters

units · string · required

The number of units consumed for a specific group related to a charge item.

amount_cents · integer · required

The amount in cents, tax excluded, consumed for a specific group related to a charge item.

events_count · integer · required

The quantity of usage events that have been recorded for a particular charge filter during the specified time period. These events may also be referred to as the number of transactions in some contexts.

invoice_display_name · string · required

Specifies the name that will be displayed on an invoice.

values · string · required

List of filter values applied to the usage.

grouped_usage · object · required

Show grouped_usage

amount_cents · integer · required

The amount in cents, tax excluded, consumed for a specific group related to a charge item.

events_count · string · required

The quantity of usage events that have been recorded for a particular charge during the specified time period. These events may also be referred to as the number of transactions in some contexts.

units · string · required

The number of units consumed by the customer for a specific charge item.

grouped_by · string · required

Key value list of event properties aggregated by the charge model

group · object · required

Show group

lago_id · string · required

Unique identifier assigned to the group within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the group record within the Lago system.

key · string · required

The group key, only returned for groups with two dimensions.

value · string · required

The group value.

units · string · required

The number of units consumed for a specific group related to a charge item.

amount_cents · integer · required

The amount in cents, tax excluded, consumed for a specific group related to a charge item.