Skip to main content

Invoicing with Stripe

Metronome can be configured to collect payment through Stripe. This guide covers how to set up Stripe integration and how the two services work together.

Currencies only

Metronome allows you to price in terms of arbitrary pricing units. For example, you might price in terms of "phone call minutes" or "text messages." Collecting through Stripe doesn't make sense for these kinds of credits. Stripe invoices will only show charges in supported currencies such as "USD" (U.S. dollars).

Stripe invoicing is one-way

When using Stripe as an external billing provider, invoices exist in both Metronome and Stripe. First, Metronome prepares a draft invoice, updating it throughout the billing period. Then, when the invoice is finalized at the end of the billing period, a corresponding invoice is created in Stripe. This is a one-time, one-way operation. If you make an adjustment to the invoice in Stripe, that change will not be reflected in Metronome.

You can use the Metronome invoice's external_invoice.invoice_id field to find the corresponding Stripe invoice to see whether an invoice has been paid.

Setting up your Stripe integration

To use Stripe as an external billing provider, you'll first need to grant Metronome read/write permission to your Stripe account via OAuth. This level of access is necessary for Metronome to be able to create Stripe invoices on your behalf. The first time you set up a customer to be billed with Stripe in the Metronome UI, you'll be prompted to grant Metronome access. You can also visit the Billing configuration page to set up Stripe access in advance.

Stripe billing configuration options

Stripe invoicing is configurable through a number of global and per-customer options. You can access the global options in the Metronome UI by visiting the Billing configuration page. The per-customer configuration can be found in the Settings tab when viewing an individual customer.

Global configuration

The following options are available from the Billing configuration page.

Customize days until invoices are due

Stripe defaults to setting invoices to be due 30 days after they're created. You can use this option to change that to a custom value. This setting has no effect for customers configured to be charged automatically. (See Stripe collection method below.)

Leave invoices as drafts

By default, Metronome sends all invoices to Stripe using the auto_advance option set to true. This means invoices will immediately be eligible for collection. If you would prefer to review invoices first, you can select the "leave invoices as drafts" option to set auto_advance to false. Invoices in Stripe will then stay in the draft state until you update them.

Skip zero-total invoices

By default, if Stripe invoicing is enabled for a customer, then all invoices that are finalized in Metronome are sent to Stripe. The "skip zero-total invoices" option instead only sends Stripe invoices when there's a non-zero total due.

Maximum and minimum amounts

Stripe imposes limits on the total amount you can bill on an invoice. For USD, the minimum allowed invoice total is $0.50, and the maximum is $999,999.99. Metronome will skip sending invoices to Stripe that fall outside this range. (The invoices will still exist in Metronome.) For more on Stripe's invoice total limits, see their documentation.

Display sub-line items on invoices

Metronome invoices have line items and sub-line items. The line items are products, e.g. "Cloud database," while the sub-line items are the charges within that product, e.g. "CPU hours" or "base charge." Stripe invoices only have line items, so by default Metronome just adds a line item per product, e.g. "Cloud database" with a price that reflects the overall subtotal for that product.

If you would like Stripe invoices to display the breakdown of sub-line items, you can select the "enable sub-line items" option. Metronome will include each individual charge (sub-line item) as a line item in Stripe. These line items use a description that combines the name of the product with the name of the charge. Given the example above, the Stripe invoice would have two line items: "Cloud database - CPU hours" and "Cloud database - base charge."

This setting also enables displaying quantities on Stripe invoices. Sub-line items that are based on metrics will also display a quantity and unit price. If the quantity is an integer, this will be displayed using Stripe's native support for quantities. Stripe, however, doesn't support non-integer quantities, so when a metric has a non-integer amount, Metronome instead includes the quantity in the line item name. For example, "Cloud database - CPU hours (12.34)." By default, Metronome uses Stripe's quantity field if all quantities on an invoice are integers. If any are not, Metronome includes the quantity in the line item name instead.

Always display quantities in sub-line items

By default, Metronome displays quantities in line items only if at least one quantity on an invoice is not an integer. This can lead to inconsistency if quantities are integers in some billing periods and not in others. For example, a Stripe invoice in one billing period might read "Cloud database - CPU hours (719.5)," and the next billing period it might read "Cloud database - CPU hours" with a quantity field of 720 because it happened to be an integer amount.

You can override this dynamic behavior by specifying that quantities should always appear in line item names instead. This setting is called "always display quantities in line items" on the Billing configuration page.

Per-customer billing configuration

When a Metronome invoice is finalized, it checks the customer's billing configuration to see if Stripe should be used. If so, a Stripe invoice is issued against the corresponding Stripe customer. Billing configuration can be set in the Metronome web UI or via the /billing-config API endpoint. The billing configuration consists of two fields that dictate how the Stripe invoice is created:

{
"billing_provider_customer_id": "cus_QMKlhKasvthHeY",
"stripe_collection_method": "charge_automatically"
}

Stripe customer ID

In order for Metronome to issue a Stripe invoice, it needs to know the Stripe ID for the customer. In the API, this is the billing_provider_customer_id field.

Stripe collection method

Stripe supports two methods of collection: sending an email invoice or charging a payment method directly. Choose which method will be used by setting the stripe_collection_method field to either send_invoice or charge_automatically.

If you choose the send_invoice option, you also need to specify how many days a customer has until payment is due. This corresponds with the days_until_due field in the Stripe API. For now, the Metronome API doesn't allow you to set this value directly, but you can update this setting on the Billing configuration page. By default, Stripe invoices are due 30 days after creation.

Leave as draft

By default, Stripe invoices are created with auto_advance: true, which means they're immediately sent to customers. Let your Metronome representative know if you would prefer to leave the Stripe invoice as a draft. This can be useful if you want to double-check an invoice and optionally adjust them before sending them to customers. If you choose this option, it's up to you to finalize the Stripe invoice when it's time for collection.

Useful metadata

Metronome sets custom metadata on Stripe invoices that it creates. If you use Stripe to send multiple kinds of invoices, this metadata can be used to determine the source of an invoice and to perform proper revenue recognition.

Metronome uses the metronome_id field on the invoice and its line items to help prevent duplicates from being created in the case of network errors. Although the ID itself is arbitrary, you can use the existence of this metadata field to recognize that a Stripe invoice was created by Metronome.

Metronome also sets a service_period metadata field on invoices that identifies the date range an invoice represents. The following is an example of metadata for a Stripe invoice created by Metronome:

{
// ...
"metadata": {
"metronome_id": "c2016fdd-cfe8-415b-874a-5a2c8014046c",
"service_period": "Feb 01 2021 - Feb 28 2021"
}
}