- Documentation
- API References
- Integrations
- Templates
- Blog
- FAQ
- GitHub
- Getting started
Add-ons
Analytics
Billable metrics
Coupons
Credit notes
Customer usage
Customers
Events
Fees
Invoices
Organizations
Plans
Resources
Subscriptions
Taxes
Wallets
Webhook endpoints
Webhooks
API Reference
Retrieve past usage
Fetch historical customer usage data for closed billing periods.
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
The customer external unique identifier (provided by your own application).
Page number.
Number of records per page.
The unique identifier of the subscription within your application.
Billable metric code filter to apply to the charge usage
Number of past billing period to returns in the result
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/past_usage?external_subscription_id=$EXTERNAL_SUBSCRIPTION_ID" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json'
{
"usage_periods": [
{
"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"
}
}
],
"groups": [
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"key": "<string>",
"value": "europe",
"units": "0.9",
"events_count": 10,
"amount_cents": 1000
}
],
"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"
}
}
],
"groups": [
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"key": "<string>",
"value": "europe",
"units": "0.9",
"events_count": 10,
"amount_cents": 1000
}
]
}
]
}
]
}
}
],
"meta": {
"current_page": 2,
"next_page": 3,
"prev_page": 1,
"total_pages": 4,
"total_count": 70
}
}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
Page number.
Number of records per page.
The unique identifier of the subscription within your application.
Billable metric code filter to apply to the charge usage
Number of past billing period to returns in the result
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.
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 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 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.
Array of group object, representing multiple dimensions for a charge item.
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.
The group key, only returned for groups with two dimensions.
The group value.
The number of units 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 amount in cents, tax excluded, consumed for a specific group related to a charge item.
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.
Array of group object, representing multiple dimensions for a charge item.
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.
The group key, only returned for groups with two dimensions.
The group value.
The number of units 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 amount in cents, tax excluded, consumed for a specific group related to a charge item.
Current page.
Next page.
Previous page.
Total number of pages.
Total number of records.
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/past_usage?external_subscription_id=$EXTERNAL_SUBSCRIPTION_ID" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json'
{
"usage_periods": [
{
"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"
}
}
],
"groups": [
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"key": "<string>",
"value": "europe",
"units": "0.9",
"events_count": 10,
"amount_cents": 1000
}
],
"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"
}
}
],
"groups": [
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"key": "<string>",
"value": "europe",
"units": "0.9",
"events_count": 10,
"amount_cents": 1000
}
]
}
]
}
]
}
}
],
"meta": {
"current_page": 2,
"next_page": 3,
"prev_page": 1,
"total_pages": 4,
"total_count": 70
}
}