List invoice breakdowns

curl --request GET \
  --url https://api.metronome.com/v1/customers/{customer_id}/invoices/breakdowns \
  --header 'Authorization: Bearer <token>'

{
  "data": [
    {
      "id": "6a37bb88-8538-48c5-b37b-a41c836328bd",
      "customer_id": "617e39d8-68f4-4592-b8d2-c2bf26a76989",
      "type": "USAGE",
      "start_timestamp": "2021-01-01T00:00:00Z",
      "end_timestamp": "2021-02-01T00:00:00Z",
      "breakdown_start_timestamp": "2021-01-01T00:00:00Z",
      "breakdown_end_timestamp": "2021-01-02T00:00:00Z",
      "credit_type": {
        "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
        "name": "USD (cents)"
      },
      "contract_id": "9de042a1-b955-43ce-9ab4-e3c2004570d1",
      "line_items": [
        {
          "credit_type": {
            "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
            "name": "USD (cents)"
          },
          "name": "CPU hours",
          "type": "usage",
          "quantity": 1488,
          "total": 14392,
          "product_id": "5c1f40cd-9ff8-4e90-ae53-5f81b0e9d1e8"
        }
      ],
      "status": "DRAFT",
      "subtotal": 14392,
      "total": 14392
    },
    {
      "id": "6a37bb88-8538-48c5-b37b-a41c836328bd",
      "customer_id": "617e39d8-68f4-4592-b8d2-c2bf26a76989",
      "type": "USAGE",
      "start_timestamp": "2021-01-01T00:00:00Z",
      "end_timestamp": "2021-02-01T00:00:00Z",
      "breakdown_start_timestamp": "2021-01-02T00:00:00Z",
      "breakdown_end_timestamp": "2021-01-03T00:00:00Z",
      "credit_type": {
        "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
        "name": "USD (cents)"
      },
      "contract_id": "9de042a1-b955-43ce-9ab4-e3c2004570d1",
      "line_items": [
        {
          "credit_type": {
            "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
            "name": "USD (cents)"
          },
          "name": "CPU hours",
          "type": "usage",
          "quantity": 1488,
          "total": 14392,
          "product_id": "5c1f40cd-9ff8-4e90-ae53-5f81b0e9d1e8"
        }
      ],
      "status": "DRAFT",
      "subtotal": 14392,
      "total": 14392
    }
  ],
  "next_page": null
}

Invoices

List invoice breakdowns

Retrieve granular time-series breakdowns of invoice data at hourly or daily intervals. This endpoint transforms standard invoices into detailed timelines, enabling you to track usage patterns, identify consumption spikes, and provide customers with transparency into their billing details throughout the billing period.

Use this endpoint to:

Build usage analytics dashboards showing daily or hourly consumption trends
Identify peak usage periods for capacity planning and cost optimization
Generate detailed billing reports for finance teams and customer success
Troubleshoot billing disputes by examining usage patterns at specific times
Power real-time cost monitoring and alerting systems

Key response fields:

An array of BreakdownInvoice objects, each containing:

All standard invoice fields (ID, customer, commit, line items, totals, status)
Line items with quantities and costs for that specific period
breakdown_start_timestamp: Start of the specific time window
breakdown_end_timestamp: End of the specific time window
next_page: Pagination cursor for large result sets

Usage guidelines:

Time granularity: Set window_size to hour or day based on your analysis needs
Response limits: Daily breakdowns return up to 35 days; hourly breakdowns return up to 24 hours per request
Date filtering: Use starting_on and ending_before to focus on specific periods
Performance: For large date ranges, use pagination to retrieve all data efficiently
Backdated usage: If usage events arrive after invoice finalization, breakdowns will reflect the updated usage
Zero quantity filtering: Use skip_zero_qty_line_items=true to exclude periods with no usage

GET

customers

{customer_id}

invoices

breakdowns

List invoice breakdowns

curl --request GET \
  --url https://api.metronome.com/v1/customers/{customer_id}/invoices/breakdowns \
  --header 'Authorization: Bearer <token>'

{
  "data": [
    {
      "id": "6a37bb88-8538-48c5-b37b-a41c836328bd",
      "customer_id": "617e39d8-68f4-4592-b8d2-c2bf26a76989",
      "type": "USAGE",
      "start_timestamp": "2021-01-01T00:00:00Z",
      "end_timestamp": "2021-02-01T00:00:00Z",
      "breakdown_start_timestamp": "2021-01-01T00:00:00Z",
      "breakdown_end_timestamp": "2021-01-02T00:00:00Z",
      "credit_type": {
        "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
        "name": "USD (cents)"
      },
      "contract_id": "9de042a1-b955-43ce-9ab4-e3c2004570d1",
      "line_items": [
        {
          "credit_type": {
            "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
            "name": "USD (cents)"
          },
          "name": "CPU hours",
          "type": "usage",
          "quantity": 1488,
          "total": 14392,
          "product_id": "5c1f40cd-9ff8-4e90-ae53-5f81b0e9d1e8"
        }
      ],
      "status": "DRAFT",
      "subtotal": 14392,
      "total": 14392
    },
    {
      "id": "6a37bb88-8538-48c5-b37b-a41c836328bd",
      "customer_id": "617e39d8-68f4-4592-b8d2-c2bf26a76989",
      "type": "USAGE",
      "start_timestamp": "2021-01-01T00:00:00Z",
      "end_timestamp": "2021-02-01T00:00:00Z",
      "breakdown_start_timestamp": "2021-01-02T00:00:00Z",
      "breakdown_end_timestamp": "2021-01-03T00:00:00Z",
      "credit_type": {
        "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
        "name": "USD (cents)"
      },
      "contract_id": "9de042a1-b955-43ce-9ab4-e3c2004570d1",
      "line_items": [
        {
          "credit_type": {
            "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
            "name": "USD (cents)"
          },
          "name": "CPU hours",
          "type": "usage",
          "quantity": 1488,
          "total": 14392,
          "product_id": "5c1f40cd-9ff8-4e90-ae53-5f81b0e9d1e8"
        }
      ],
      "status": "DRAFT",
      "subtotal": 14392,
      "total": 14392
    }
  ],
  "next_page": null
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

customer_id

string<uuid>

required

Query Parameters

next_page

string

Cursor that indicates where the next page of results should start.

status

string

Invoice status, e.g. DRAFT or FINALIZED

skip_zero_qty_line_items

boolean

If set, all zero quantity line items will be filtered out of the response

limit

integer

Max number of results that should be returned. For daily breakdowns, the response can return up to 35 days worth of breakdowns. For hourly breakdowns, the response can return up to 24 hours. If there are more results, a cursor to the next page is returned.

Required range: 1 <= x <= 100

window_size

enum<string>

The granularity of the breakdowns to return. Defaults to day.

Available options:

hour,

day,

HOUR,

DAY,

Hour,

Day

sort

enum<string>

Invoice sort order by issued_at, e.g. date_asc or date_desc. Defaults to date_asc.

Available options:

date_asc,

date_desc

credit_type_id

string

Only return invoices for the specified credit type

starting_on

string<date-time>

required

RFC 3339 timestamp. Breakdowns will only be returned for time windows that start on or after this time.

ending_before

string<date-time>

required

RFC 3339 timestamp. Breakdowns will only be returned for time windows that end on or before this time.

Response

Success

data

object[]

required

Show child attributes

next_page

string | null

required

Get an invoice PDF

Preview events

⌘I