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.
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).
Overview
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. Metronome listens for webhook events on the status of the invoice in Stripe and syncs that status in Metronome. Note that if you make an adjustment to the line items on an invoice in Stripe, that change will not be reflected in Metronome.
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 web 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.
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 charge_automatically is set, Stripe will attempt to pay this invoice using the default payment method attached to the customer. If send_invoice is set, Stripe will email this invoice to the customer with payment instructions.
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.
Stripe imposes a 250 line item maximum on their invoices. If a customer invoice in Metronome exceeds 250 line items, the invoice will be collapsed into one line item, labeled with your company name and with the invoice total as the associated price. You can still provide full invoice visibility (with all line items) to your customers by using our embeddable dashboards to expose invoices in your UI.
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"
}
}
Stripe invoice status sync
Metronome captures webhook events from Stripe when the status of an invoice changes. Finalized invoices in Metronome are automatically sent to Stripe. If the global configuration is set to Leave invoices as drafts Stripe does not return a status and you will not see a Stripe invoice status in Metronome. However, if the Leave invoices as drafts setting is turned off, Stripe returns an invoice.finalized event and the invoice in Metronome is marked as Stripe: Finalized. A summary of the invoice statuses that Metronome captures is below. These statuses are also part of the response when fetching invoices from the Metronome API.
| Stripe Webhook Event | external_status |
|---|---|
| invoice.finalized | FINALIZED |
| invoice.marked_uncollectible | UNCOLLECTIBLE |
| invoice.paid | PAID |
| invoice.payment_failed | PAYMENT_FAILED |
| invoice.payment_succeeded | PAID |
| invoice.voided | VOID |
| invoice.deleted | DELETED |
Downstream integrations through Stripe
Metronome offers custom fields and entity mappings to easily set up and map metadata on Metronome objects that are pushed to Stripe. This supports downstream integrations that pull information from Stripe, such as your tax platform (e.g. Anrok, Avalara).
The following Stripe entities can be mapped from Metronome entities:
| Metronome entity | Stripe entity | Notes |
|---|---|---|
| Line item | invoiceitem | Created by invoicer upon issuance |
| Invoice | invoice | Created by invoicer upon issuance |
| Sub line items (aka “charges”) | invoiceitem | Created by invoicer upon issuance |
| "Product ID" custom field on Line item | invoiceitem.price.product | Stripe product ID is stored in a line item custom field. This field is used for the Anrok integration and is passed as part of the invoice item from Stripe during invoice issuance. |
| Any custom field on Line item | invoiceitem.metadata.* | Any metadata key that's stored on a line item custom field. This field can be used for the Avalara integration, specifically to provide tax_code metadata. This metadata is also passed as part of the invoice item from Stripe during invoice issuance. |
| Any custom field on Customer | invoice.metadata.* | Any metadata key that's stored on a customer custom field. This field can be used for the Avalara integration, specifically to provide tax_code metadata. This metadata is also passed as part of the invoice from Stripe during invoice issuance. |
To set up entity mappings for Anrok and Avalara in the Metronome web UI, go to General Settings > Integrations > Stripe (card) > Edit Mapping (button). From there, set up the desired mappings that will be passed from Metronome into Stripe:
