Invoices

Metronome supports a shared set of Invoice endpoints that allow you to retrieve, regenerate, and manage invoices associated with both Plans and Contracts. While these endpoints are shared between Plans and Contracts, note that some input and response parameters differ slightly depending on the entity you are targeting. For example, Contract invoices may include commit, credit, or usage details, whereas Plan invoices are generally scoped to plan-level billing events.

Available Endpoints

Endpoint	Description
`/customers/{customer_id}/invoices/{invoice_id}`	Retrieves a specific invoice for a given customer.
`/customers/{customer_id}/invoices`	Lists all invoices for a given customer.
`/invoices/regenerate`	Regenerates a previously issued invoice.
`/invoices/void`	Voids an existing invoice.

Associated Invoice Parameters

When using these endpoints, the associated invoices will include these parameters:

Field	Type	Description
`plan_id`	string (UUID)	The unique identifier for the plan associated with this invoice.
`plan_name`	string	The name of the plan associated with the invoice.
`plan_custom_fields`	object	A map of custom fields defined on the associated plan at the time of invoice generation.
`invoice_adjustments`	array	A list of adjustments applied to the invoice, such as credits, discounts, or manual corrections.
`sub_line_items`	array	A list of sub-line items that provide detailed breakdown of invoice charges and components.

InvoiceAdjustment Schema

The invoice_adjustments field contains an array of adjustment objects with the following structure:

Field	Type	Required	Description
`name`	string	Yes	The name of the adjustment (e.g., “Monthly minimum ($1,000)”).
`total`	number	Yes	The total amount of the adjustment.
`credit_type`	string	Yes	The type of credit associated with the adjustment.
`credit_grant_id`	string	No	The ID of the credit grant associated with the adjustment.
`credit_grant_custom_fields`	object	No	Custom fields associated with the credit grant.

InvoiceSubLineItem Schema

The sub_line_items field contains an array of sub-line item objects with the following structure:

Field	Type	Required	Description
`name`	string	Yes	The name of the sub-line item.
`price`	number	No	The unit price for this charge, present only if the charge is not tiered and the quantity is nonzero.
`quantity`	number	Yes	The quantity associated with the sub-line item.
`subtotal`	number	Yes	The subtotal amount for this sub-line item.
`charge_id`	string (UUID)	No	The ID of the charge associated with this sub-line item.
`credit_grant_id`	string (UUID)	No	The ID of the credit grant associated with this sub-line item.
`tier_period`	object	No	When the current tier started and ends (for tiered charges only).
`tiers`	array	No	Array of tier information for tiered pricing.
`custom_fields`	object	Yes	Custom fields associated with the charge.
`start_date`	string	No	The start date for the charge (for seats charges only).
`end_date`	string	No	The end date for the charge (for seats charges only).

Tier Period Object

When tier_period is present, it contains:

Field	Type	Required	Description
`starting_at`	string	Yes	RFC 3339 timestamp when the tier started.
`ending_before`	string	No	RFC 3339 timestamp when the tier ends.

Tier Object

Each item in the tiers array contains:

Field	Type	Required	Description
`starting_at`	number	Yes	At what metric amount this tier begins.
`quantity`	number	Yes	The quantity for this tier.
`price`	number	Yes	The price for this tier.
`subtotal`	number	Yes	The subtotal for this tier.

Check out the Contracts version of the documentation here →

Plans-Specific Endpoints

Plans-Contracts Shared Endpoints

Available Endpoints

Associated Invoice Parameters

InvoiceAdjustment Schema

InvoiceSubLineItem Schema

Tier Period Object

Tier Object

​Available Endpoints

​Associated Invoice Parameters

​InvoiceAdjustment Schema

​InvoiceSubLineItem Schema

​Tier Period Object

​Tier Object

Available Endpoints

Associated Invoice Parameters

InvoiceAdjustment Schema

InvoiceSubLineItem Schema

Tier Period Object

Tier Object