Invoicing overview

This document describes how Metronome produces invoices for your customer and the configuration options you have for handling those invoices. If you haven't already, we recommend reading about pricing to understand how Metronome computes a customer's spending.

What is a Metronome invoice?

For each billing period, Metronome generates invoices for each of your customers. An invoice describes how much a customer spent during a billing period. An invoice consists of line items and, optionally, adjustments. Line items are derived from prices applied to usage. Adjustments apply to the invoice as a whole and can be used to enforce minimum and maximum spending limits, among other things.

Accessing Metronome invoices

You can view a customer's Metronome invoices in the web UI by selecting the customer and then clicking on the Invoices tab.

Through the API, you can use the /invoices endpoint to list invoices in a given date range.

Invoice lifecycle

Invoices are created with the status DRAFT at the beginning of each billing period. Draft invoices are continuously updated to show what spending has occurred so far in the current billing period.

When the billing period ends, the invoice becomes FINALIZED. This means the invoice is ready for collection. Importantly, no further changes can happen to an invoice once it's reached the FINALIZED state, even if additional usage events are ingested. This guarantees that the invoice you see in Metronome is exactly what your customer sees.

Grace period

By default, invoices don't become finalized until a 24-hour grace period has elapsed beyond the end of the billing period. This is to allow for lag in usage reporting. As in the example explored in Getting usage data into Metronome, your system may send hourly summaries of usage to Metronome. If the billing period ends right before one of those hourly summaries comes in, the grace period allows that usage to still be counted.

A Metronome representative can help you configure the grace period. If your system doesn't need that extra time to send in usage events, the grace period can be disabled altogether. In that case, a draft invoice will be finalized as soon as the billing period ends.

Collecting payment

When an invoice is finalized, it's ready for collection. What happens next depends on the customer's billing configuration. Billing configuration can be set up when you first create a customer in Metronome. It can also be adjusted later by using the web UI or the /billing-config API endpoint.

If a customer is configured for external billing, then payment will be collected through the external billing provider. Stripe and AWS Marketplace are the only external billing providers currently supported. You can read more about how to use these in Invoicing with Stripe and Invoicing with AWS Marketplace.

If a customer is not configured for external billing, it is up to you to send the invoice to your customer.