Invoicing with Stripe
Learn how to set up and configure a Stripe integration with Metronome to collect payments.
When using Stripe as an external billing provider, invoices exist in both Metronome and Stripe. First, Metronome prepares a draft invoice and updates it throughout the billing period. When the invoice is finalized at the end of the billing period, a corresponding invoice is created in Stripe.
Stripe invoices only show charges in supported currencies such as "USD" (U.S. dollars), not arbitrary pricing units, such as "phone call minutes" or "text messages".
Set up your Stripe integration
- Grant Metronome read/write permission to your Stripe account via OAuth. This level of access is necessary for Metronome to create Stripe invoices on your behalf.
- The first time you set up a customer to be billed with Stripe in the Metronome app, you'll be prompted to grant Metronome access.
To set up Stripe access in advance, visit the Billing configuration page and click Enable. Fill in information about your business to add Stripe as a billing provider.
Enable Stripe's automatic payment retry capabilities to improve invoice payment success.
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 app by visiting the Billing configuration page. The per-customer configuration is in the Settings tab when viewing an individual customer.
Global configuration
The following options are available from the Billing configuration page after enabling your Stripe integration.
Customize invoice due date
Stripe defaults to invoice due dates within 30 days after they're sent. You can change this option to a custom value. This setting has no effect for customers configured to be charged automatically. (See Stripe collection method below.)
Auto-advance invoices
By default, Metronome sends all invoices to Stripe with the auto_advance option set to false. This enables you to review all invoices before finalization and payment collection happens in Stripe.
If you prefer to immediately finalize invoices in Stripe, de-select the "leave invoices as drafts" option in Metronome to set auto_advance to true.
If you make an adjustment to the line items on an invoice in Stripe, that change is not reflected in Metronome.
Skip zero-total invoices
If Stripe invoicing is enabled for a customer, all invoices finalized in Metronome are sent to Stripe by default. The "skip zero-total invoices" option 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 skips sending invoices to Stripe that fall outside this range. (The invoices still exist in Metronome.)
Display sub-line items on invoices
Metronome invoice line items are products, such as "Cloud database," while the sub-line items are the charges within that product, such as "CPU hours." Stripe invoices only have line items, so by default Metronome adds a line item per product with a price that reflects the overall subtotal for that product.
To display the breakdown of sub-line items on Stripe invoices, select "enable sub-line items". Each individual charge (sub-line item) becomes a line item in Stripe. These line items use a description that combines the name of the product with the name of the charge, for example, "Cloud database - CPU hours" and "Cloud database - base charge."
Stripe imposes a maximum of 250 line items on their invoices. If a customer invoice in Metronome exceeds 250 line items, the invoice is collapsed into one line item, labeled with your company name with the invoice total as the associated price. Provide full invoice visibility (with all line items) to your customers using our embeddable dashboards to expose invoices in your UI.
Display quantities
The "enable sub-line items" setting also enables displaying quantities on Stripe invoices. Sub-line items based on metrics also display a quantity and unit price. If the quantity is an integer, this is displayed using Stripe's native support for quantities. Stripe 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. It 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 with the "always display quantities in line items" setting on the Billing configuration page.
Per-customer billing configuration
When a Metronome invoice is finalized, it checks the customer's billing configuration for Stripe. If the customer is set to use Stripe, a Stripe invoice is issued against the corresponding Stripe customer.
Set the billing configuration in the Metronome app or through the /customers/{customer_id}/billing-config/{billing_provider_type} 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
Metronome requires the Stripe ID for the customer to issue a Stripe invoice. In the API, this is the billing_provider_customer_id field.
Stripe collection method
Stripe supports two methods of collection with the stripe_collection_method field:
charge_automatically, Stripe attempts to pay this invoice using the default payment method attached to the customersend_invoice, Stripe emails this invoice to the customer with payment instructions
If you choose the send_invoice option, you must specify how many days a customer has until payment is due. This corresponds with the days_until_due field in the Stripe API. By default, Stripe invoices are due 30 days after creation. The Metronome API doesn't allow you to set this value directly, but you can update this setting on the Billing configuration page.
Leave as draft
By default, Stripe invoices are created with auto_advance: true and are immediately sent to customers.
This is useful if you want to double-check an invoice and adjust them before sending them to customers. If you choose this option, you must 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 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"
}
}
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 do not see a Stripe invoice status in Metronome.
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. See a summary of the invoice statuses that Metronome captures below. These statuses are also part of the response when fetching invoices from the /customers/{customer_id}/invoices endpoint.
| 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 |
When invoicing with Stripe, you can optionally have Stripe dynamically calculate sales tax for your invoices.
