---
title: "Retrieve customer current usage"
method: GET
path: "/customers/{external_customer_id}/current_usage"
tags: ["customers"]
---

# Retrieve customer current usage

`GET /customers/{external_customer_id}/current_usage`

This endpoint enables the retrieval of the usage-based billing data for a customer within the current period.

## Path parameters

- `external_customer_id` string, required

## Query parameters

- `external_subscription_id` string, required
- `apply_taxes` boolean
- `charge_id` string, uuid
- `charge_code` string
- `billable_metric_code` string
- `group` object
- `filter_by_charge_id` string, uuid
- `filter_by_charge_code` string
- `filter_by_group` object
- `full_usage` boolean
- `filter_by_presentation` string

## Response `200`

Customer usage

- CustomerUsage
  - `customer_usage` CustomerUsageObject, required
    - `from_datetime` string, date-time, required — The lower bound of the billing period, expressed in the ISO 8601 datetime format in Coordinated Universal Time (UTC).
    - `to_datetime` string, date-time, required — The upper bound of the billing period, expressed in the ISO 8601 datetime format in Coordinated Universal Time (UTC).
    - `issuing_date` string, date, required — The date of creation of the invoice.
    - `lago_invoice_id` string, uuid, nullable — A unique identifier associated with the invoice related to this particular usage record.
    - `currency` 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BRL' | 'BSD' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHF' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'CRC' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'ISK' | 'JMD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KRW' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRO' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SEK' | 'SGD' | 'SHP' | 'SLL' | 'SOS' | 'SRD' | 'STD' | 'SZL' | 'THB' | 'TJS' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'UYU' | 'UZS' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XCD' | 'XOF' | 'XPF' | 'YER' | 'ZAR' | 'ZMW'
    - `amount_cents` integer, required — The amount in cents, tax excluded.
    - `taxes_amount_cents` integer, required — The tax amount in cents.
    - `total_amount_cents` integer, required — The total amount in cents, tax included.
    - `charges_usage` CustomerChargeUsageObject[], required — Array of charges that comprise the current usage. It contains detailed information about individual charge items associated with the usage.
      - `units` string, required — The number of units consumed by the customer for a specific charge item.
      - `total_aggregated_units` string, required — The total number of units consumed by the customer for a specific charge item, aggregated across all usage events.
      - `events_count` integer, 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.
      - `amount_cents` integer, required — The amount in cents, tax excluded, consumed by the customer for a specific charge item.
      - `amount_currency` 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BRL' | 'BSD' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHF' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'CRC' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'ISK' | 'JMD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KRW' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRO' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SEK' | 'SGD' | 'SHP' | 'SLL' | 'SOS' | 'SRD' | 'STD' | 'SZL' | 'THB' | 'TJS' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'UYU' | 'UZS' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XCD' | 'XOF' | 'XPF' | 'YER' | 'ZAR' | 'ZMW', required
      - `pricing_unit_details` UsagePricingUnitDetailsObject, nullable — Details about the pricing unit used for charge usage.
        - `amount_cents` integer, required — The amount in cents in the pricing unit.
        - `short_name` string, required — The short name of the pricing unit.
        - `conversion_rate` string, required — The conversion rate from pricing units to the plan's currency.
      - `charge` object, required — Object listing all the properties for a specific charge item.
        - `lago_id` string, uuid, 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` 'standard' | 'graduated' | 'package' | 'percentage' | 'volume', required — The pricing model applied to this charge. Possible values are standard, `graduated`, `percentage`, `package` or `volume`.
        - `invoice_display_name` string, nullable — Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the actual charge will be used as the default display name.
      - `billable_metric` object, required — The related billable metric object.
        - `lago_id` string, uuid, 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` 'count_agg' | 'sum_agg' | 'max_agg' | 'unique_count_agg' | 'weighted_sum_agg' | 'latest_agg', 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[] — Array of filter object, representing multiple dimensions for a charge item.
        - `units` string — The number of units consumed for a specific charge filter related to a charge item.
        - `total_aggregated_units` string — The total number of units consumed by the customer for a specific charge item, aggregated across all usage events.
        - `amount_cents` integer — The amount in cents, tax excluded, consumed for a specific charge filter related to a charge item.
        - `events_count` integer — 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 — Specifies the name that will be displayed on an invoice.
        - `pricing_unit_details` UsagePricingUnitDetailsObject, nullable — Details about the pricing unit used for charge usage.
          - `amount_cents` integer, required — The amount in cents in the pricing unit.
          - `short_name` string, required — The short name of the pricing unit.
          - `conversion_rate` string, required — The conversion rate from pricing units to the plan's currency.
        - `values` object — List of filter values applied to the usage.
        - `presentation_breakdowns` object[] — Array of usage breakdowns split by presentation group keys without affecting pricing or aggregation.
          - `presentation_by` object — Key value list of event properties used for presentation grouping.
          - `units` string — The number of units consumed for a specific presentation group.
      - `grouped_usage` object[] — Array of aggregated fees, grouped by the event properties defined in a `standard` charge model.
        - `amount_cents` integer — The amount in cents, tax excluded, consumed for a specific group related to a charge item.
        - `events_count` integer — 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 — The number of units consumed for a specific group related to a charge item.
        - `total_aggregated_units` string — The total number of units consumed by the customer for a specific charge item, aggregated across all usage events.
        - `pricing_unit_details` UsagePricingUnitDetailsObject, nullable — Details about the pricing unit used for charge usage.
          - `amount_cents` integer, required — The amount in cents in the pricing unit.
          - `short_name` string, required — The short name of the pricing unit.
          - `conversion_rate` string, required — The conversion rate from pricing units to the plan's currency.
        - `grouped_by` object — Key value list of event properties aggregated by the charge model
        - `filters` object[] — Array of filter object, representing multiple dimensions for a charge item.
          - `units` string — The number of units consumed for a specific charge filter related to a charge item.
          - `total_aggregated_units` string — The total number of units consumed by the customer for a specific charge item, aggregated across all usage events.
          - `amount_cents` integer — The amount in cents, tax excluded, consumed for a specific charge filter related to a charge item.
          - `events_count` integer — 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 — Specifies the name that will be displayed on an invoice.
          - `pricing_unit_details` UsagePricingUnitDetailsObject, nullable — Details about the pricing unit used for charge usage.
            - `amount_cents` integer, required — The amount in cents in the pricing unit.
            - `short_name` string, required — The short name of the pricing unit.
            - `conversion_rate` string, required — The conversion rate from pricing units to the plan's currency.
          - `values` object — List of filter values applied to the usage.
          - `presentation_breakdowns` object[] — Array of usage breakdowns split by presentation group keys without affecting pricing or aggregation.
            - `presentation_by` object — Key value list of event properties used for presentation grouping.
            - `units` string — The number of units consumed for a specific presentation group.
        - `presentation_breakdowns` object[] — Array of usage breakdowns split by presentation group keys without affecting pricing or aggregation.
          - `presentation_by` object — Key value list of event properties used for presentation grouping.
          - `units` string — The number of units consumed for a specific presentation group.
      - `presentation_breakdowns` object[] — Array of usage breakdowns split by presentation group keys without affecting pricing or aggregation.
        - `presentation_by` object — Key value list of event properties used for presentation grouping.
        - `units` string — The number of units consumed for a specific presentation group.

## Other responses

- `401` — Unauthorized error
- `404` — Not Found error

---

[API](https://skmtc.dev/getlago/apis/lago-api-documentation.md) · [All operations](https://skmtc.dev/getlago/apis/lago-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/getlago/lago-api-documentation/revisions/6e969ef3bb45/schema)