API Reference
- Getting started
- Add-ons
- Analytics
- Billable metrics
- Coupons
- Credit notes
- Customer usage
- Customers
- Events
- Fees
- Invoices
- Organizations
- Payment requests
- Plans
- Resources
- Subscriptions
- Taxes
- Wallets
- Webhook endpoints
- Webhooks
Retrieve current usage
Retrieve real-time customer usage data for the current open billing period.
LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"
EXTERNAL_CUSTOMER_ID="__EXTERNAL_CUSTOMER_ID__"
EXTERNAL_SUBSCRIPTION_ID="__EXTERNAL_SUBSCRIPTION_ID__"
curl --location --request GET "$LAGO_URL/api/v1/customers/$EXTERNAL_CUSTOMER_ID/current_usage?external_subscription_id=$EXTERNAL_SUBSCRIPTION_ID" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json'
{
"customer_usage": {
"from_datetime": "2022-07-01T00:00:00Z",
"to_datetime": "2022-07-31T23:59:59Z",
"issuing_date": "2022-08-01",
"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": {},
"filters": [
{
"units": "0.9",
"amount_cents": 1000,
"events_count": 10,
"invoice_display_name": "AWS eu-east-1",
"values": {
"region": "us-east-1"
}
}
]
}
]
}
]
}
}LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"
EXTERNAL_CUSTOMER_ID="__EXTERNAL_CUSTOMER_ID__"
EXTERNAL_SUBSCRIPTION_ID="__EXTERNAL_SUBSCRIPTION_ID__"
curl --location --request GET "$LAGO_URL/api/v1/customers/$EXTERNAL_CUSTOMER_ID/current_usage?external_subscription_id=$EXTERNAL_SUBSCRIPTION_ID" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json'
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
The customer external unique identifier (provided by your own application).
Query Parameters
The unique identifier of the subscription within your application.
Optional flag to determine if taxes should be applied. Defaults to true if not provided or if null.
Response
The lower bound of the billing period, expressed in the ISO 8601 datetime format in Coordinated Universal Time (UTC).
The upper bound of the billing period, expressed in the ISO 8601 datetime format in Coordinated Universal Time (UTC).
The date of creation of the invoice.
The amount in cents, tax excluded.
The tax amount in cents.
The total amount in cents, tax included.
Array of charges that comprise the current usage. It contains detailed information about individual charge items associated with the usage.
The number of units consumed by the customer for a specific charge item.
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.
The amount in cents, tax excluded, consumed by the customer for a specific charge item.
The currency of a usage item consumed by the customer.
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, 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 Object listing all the properties for a specific charge item.
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.
The pricing model applied to this charge. Possible values are standard, graduated, percentage, package or volume.
standard, graduated, package, percentage, volume 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.
The related billable metric object.
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.
The name of the billable metric used for this charge.
The code of the billable metric used for this charge.
The aggregation type of the billable metric used for this charge. Possible values are count_agg, sum_agg, max_agg or unique_count_agg.
count_agg, sum_agg, max_agg, unique_count_agg, weighted_sum_agg, latest_agg Array of filter object, representing multiple dimensions for a charge item.
The number of units consumed for a specific charge filter related to a charge item.
The amount in cents, tax excluded, consumed for a specific charge filter related to a charge item.
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.
Specifies the name that will be displayed on an invoice.
Array of aggregated fees, grouped by the event properties defined in a standard charge model.
The amount in cents, tax excluded, consumed for a specific group related to a charge item.
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.
The number of units consumed for a specific group related to a charge item.
Key value list of event properties aggregated by the charge model
Array of filter object, representing multiple dimensions for a charge item.
The number of units consumed for a specific charge filter related to a charge item.
The amount in cents, tax excluded, consumed for a specific charge filter related to a charge item.
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.
Specifies the name that will be displayed on an invoice.
List of filter values applied to the usage.
A unique identifier associated with the invoice related to this particular usage record.
The currency of the customer's current usage.
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, 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 Was this page helpful?
LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"
EXTERNAL_CUSTOMER_ID="__EXTERNAL_CUSTOMER_ID__"
EXTERNAL_SUBSCRIPTION_ID="__EXTERNAL_SUBSCRIPTION_ID__"
curl --location --request GET "$LAGO_URL/api/v1/customers/$EXTERNAL_CUSTOMER_ID/current_usage?external_subscription_id=$EXTERNAL_SUBSCRIPTION_ID" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json'
{
"customer_usage": {
"from_datetime": "2022-07-01T00:00:00Z",
"to_datetime": "2022-07-31T23:59:59Z",
"issuing_date": "2022-08-01",
"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": {},
"filters": [
{
"units": "0.9",
"amount_cents": 1000,
"events_count": 10,
"invoice_display_name": "AWS eu-east-1",
"values": {
"region": "us-east-1"
}
}
]
}
]
}
]
}
}