List invoices

curl --request GET \
  --url https://api.metronome.com/v1/customers/{customer_id}/invoices \
  --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",
      "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"
        }
      ],
      "total": 14392,
      "status": "FINALIZED"
    }
  ],
  "next_page": null
}

Invoices

List invoices

Retrieves a paginated list of invoices for a specific customer, with flexible filtering options to narrow results by status, date range, credit type, and more. This endpoint provides a comprehensive view of a customer’s billing history and current charges, supporting both real-time billing dashboards and historical reporting needs.

Use this endpoint to:

Display historical invoice details in customer-facing dashboards or billing portals.
Retrieve current month draft invoices to show customers their month-to-date spend.
Access finalized invoices for historical billing records and payment reconciliation.
Validate customer pricing and credit applications for customer support queries.
Generate financial reports by filtering invoices within specific date ranges

Key response fields:

Array of invoice objects containing:

Invoice ID and status (DRAFT, FINALIZED, VOID)
Invoice type (USAGE, SCHEDULED)
Billing period start and end dates
Issue date and due date
Total amount, subtotal, and amount due
Applied credits summary
Contract ID reference
External billing provider status (if integrated with Stripe, etc.)
Pagination metadata next_page cursor

Usage guidelines:

The endpoint returns invoice summaries; use the Get Invoice endpoint for detailed line items
Draft invoices are continuously updated as new usage is reported and will show real-time spend
Results are ordered by creation date descending by default (newest first)
When filtering by date range, the filter applies to the billing period, not the issue date
For customers with many invoices, implement pagination to ensure all results are retrieved External billing provider statuses (like Stripe payment status) are included when applicable
Voided invoices are included in results by default unless filtered out by status

GET

customers

{customer_id}

invoices

List invoices

curl --request GET \
  --url https://api.metronome.com/v1/customers/{customer_id}/invoices \
  --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",
      "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"
        }
      ],
      "total": 14392,
      "status": "FINALIZED"
    }
  ],
  "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

limit

integer

Max number of results that should be returned

Required range: 1 <= x <= 100

next_page

string

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

status

string

Invoice status, e.g. DRAFT, FINALIZED, or VOID

skip_zero_qty_line_items

boolean

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

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>

RFC 3339 timestamp (inclusive). Invoices will only be returned for billing periods that start at or after this time.

ending_before

string<date-time>

RFC 3339 timestamp (exclusive). Invoices will only be returned for billing periods that end before this time.

Response

Success

The response is of type object.

Get an invoice

List invoice breakdowns

GET STARTED

API REFERENCE

List invoices

Use this endpoint to:

Key response fields:

Usage guidelines:

Authorizations

Path Parameters

Query Parameters

Response