Skip to main content
Private BetaMetronome invoicing is currently in Private Beta. Contact your Metronome representative for early access.
Metronome offers native invoicing capabilities for clients focused on simplifying their billing integrations. This capability can be broken down into a few core components:
  • Payment Collection: Choose and connect Metronome to your payment gateway of choice. Metronome uses this connection to process transactions. Each payment attempt is stored in the platform to provide robust visibility into payment history for all customers and invoices.
  • Tax Calculation: Connect Metronome to your tax provider to calculate taxes on finalized invoices.
  • Billing Experience: Embed Metronome’s billing console directly into your platform to provide your customer’s with a one-stop-shop for their invoicing needs. Leverage the Metronome billing invoice and webhooks to manage distribution workflows.
  • Dunning: Configure automated reattempts or build custom logic on top of Metronome webhooks.
  • Customer Configuration: Set up your customer so that Metronome can begin invoicing them on your behalf.

​
Payment Collection

Metronome creates payments in your payment gateway of choice for customers configured to use Metronome’s invoicing product. Payments can be triggered automatically or manually, depending on the customer’s configuration.

​
Connect your payment gateway

Today, Metronome only supports Stripe as a payment option for invoicing. To collect payment with Stripe, please follow the instructions in the Stripe integration guide. Once Metronome is connected to your Stripe account, Metronome can begin collecting payment.
INFOMetronome is planning to add support for additional payment gateways. For more information, contact your Metronome representative.

​
Understand Metronome’s payment data model

Metronome creates a payment object for each attempt to charge a customer, allowing you to see the history of all payment attempts inside of Metronome. This data can be fetched over the API via list payments or via data export. The Metronome payment status is tightly coupled to the payment gateway’s payment status, which is described below:
Payment States
StatusTerminal StateAllowed TransitionsNotes
pendingnopaid, requires_intervention, cancelledIndicates that we are attempting this payment
requires_interventionnopending, requires_intervention, cancelledIndicates an error occurred while collecting payment. If left in this state for more than 24 hours, it will be automatically canceled. A new pending payment will be created based on the dunning options.
cancelledyesnoneIndicates this payment failed.
paidyesnoneIndicates this payment was successful.

​
Payment notifications

Metronome uses webhooks for notifications. For documentation on how to sign up for webhook notifications, see the webhook guide. While examples are provided below, the schema for the properties section of the webhook matches the Payment API Schema. Payment Status This event will be triggered any time a new payment is created or an existing payment changes state. This is the primary way to monitor and react to payments. The returned payment will include the new status. 
{
  "type": "payment.payment_status",
  "properties": <Payment Schema>
}
Payment Pending Next Action This event will be triggered when the payment gateway indicates that further action is required to process payment. This notification alone does not guide you to handling the required next action. You must fetch the Payment Intent from Stripe and fetch the next_action. 
{
  "type": "payment.payment_pending_action_required",
  "properties": <Payment Schema>
}

​
Tax Calculation

Metronome integrates with providers like Avalara or Anrok to calculate tax for invoices. Metronome calculates tax at the line item level, but records the total amount on the external_invoice object on the invoice. This process occurs after the invoice is finalized in Metronome. To learn about how to set up your provider with Metronome, view the calculate tax guide.

​
Billing Experience

Metronome believes billing is a core part of your product experience, which is why we built invoicing with the intention it integrates directly to your product. Learn about the invoicing mechanics and how to configure the Metronome Billing Console - the source of truth for your customers’ historical, future, and outstanding invoices.

​
The billing invoice

When using Metronome’s invoicing product, Metronome will populate additional information within the external_invoice object on the invoice. The external_invoice object represents the “external” view of the Metronome invoice as received by your customer. We will refer to this as the billing invoice. The billing invoice is defined by the following:
  • Tax: Upon finalization of the invoice, Metronome will calculate tax for the invoice if there is a tax provider configured. Associated tax calculaton will be stored in tax object.
  • Billing invoice total: Once tax is calculated, the total before tax is captured within sub_total and the total after tax is captured within total.
  • Invoice PDF: Metronome returns a PDF file of the invoice within the pdf_url field. This will include all relevant line items for the invoice, the tax applied, and the total due. The invoice will be addressed to the customer based on the customer address stored in the payment gateway (that Metronome fetches) with your company listed as the Biller. Today, Metronome does not offer advanced PDF customization features.
  • Billing invoice status: While the Metronome invoice cycles from draft to finalized, the billing invoice cycles through several states during its lifecycle, stored in the external_status field. These are dependent on both the finalization and payment process. While related, the Metronome Invoice and the Metronome Billing Invoice can exist in separate states.
Billing Console
The billing invoice gets marked as paid once there is successful payment for the invoice, equal to the full amount owed. Today, Metronome does not support partial payments for invoices. paid and void are the two terminal states for the billing invoice. This means that if you void a Metronome invoice whose billing invoice is in a paid state, the state of the billing invoice will not change and neither will the associated PDF. If that Metronome invoice is regenerated, it will create a net new billing invoice with an updated PDF document. The billing invoice represents the external interface all billing workflows are built off of for Metronome’s native invoicing product.

​
Metronome Billing Console

The Metronome Billing Console is composed of embeddable components designed to live within your product and serve as the source of truth for billing for your customers. They can:
  • View historical invoices, including all line items, tax amount, and payment status
  • Download invoice PDFs for internal record keeping
  • Attempt payment on an outstanding invoice
  • Understand usage and payment patterns
Billing Console
For details on how to embed the Billing Console into your product, follow the instructions on this page. For clients who wish to use their own components, all the relevant data and actions can be fetched via Metronome’s APIs. Specifically, reference the invoice object and the description above for the billing invoice.

​
Invoice distribution

Depending on what your billing model is, your distribution requirements may change. We can break these into two general categories: Automatically charge customer Many customers are charged automatically based on their contract terms. For these customers, once the invoice is finalized, Metronome will automatically attempt to collect payment for the invoice. You will want to send these customers a receipt for the transaction and then provide them with a link to the Billing Console for more detailed information:
  • Receipts: You can configure Stripe to send automatic receipts which will automatically email your customer a receipt for a successful transaction.
  • Send follow-up: In addition to sending a receipt, you may want to send a follow-up email linking them to their billing console where they can get more detailed information. While Metronome does not offer automated email services, this workflow can automated off Metronome webhooks which notify you of payment events and provide the information necessary to send.
Manually charge customer Other customers may not be subject to automated payments. For these customers, once the invoice is finalized, Metronome will calculate tax and generate an invoice PDF but will not charge them in the configured payment gateway. You will need to:
  • Listen for invoice finalization: Listen to the finalized invoice webhook.
  • Pull invoice PDF: For invoices set to manually_charge_payment_intent, download the invoice PDF.
  • Send email: While Metronome does not provide automated emailing, it provides you with the information needed to write one. Using the stripe_customer_id, query Stripe for the customer’s email. Generate an email, using AWS SES for example, that includes the PDF downloaded in the last step and a link to the Billing Console.
  • Attempt payment: From the Billing Console, clients can simply select the relevant invoice and click Pay Invoice.
The Pay Invoice button triggers an API request to the /payments/attempt end-point. This will initiate a new transaction in the payment gateway, using the default payment method on file.

​
Dunning

Metronome provides two capabilities to assist with the dunning process: automated retries and payment webhooks that can be used to trigger customer outreach.

​
Automated retries

When configuring your customer_billing_configuration (described in the next section) you can specify how frequently you would like failed payments to be retried. Specifically, you can specify payment_intent_retry_days which dictates the number of days Metronome will reattempt payment. By default, Metronome will reattempt payment everyday for 7 days after the first failed payment, starting 24 hours after the first payment attempt finishes. Given that the customer_billing_configuration is set on a per contract basis, this setting will apply to all invoices on the associated contract.

​
Customer outreach

As mentioned in the prior section, Metronome does not provide support for automated emailing. However, clients can facilitate customer outreach workflows using Metronome payment status webhooks as triggers:
  • Build a webhook handler: Build a handler to consume Metronome’s webhooks. This handler should consume both the payment.payment_status and payment.payment_pending_action_required webhooks. Webhooks with the status requires_intervention should trigger your outreach workflows.
  • Notify customers of failed payments: If payment fails, a payment.payment_status will fire that has a properties.status field set to requires_intervention. To understand how to manage the failure, look at the properties.error.type field. This will provide the type code reason for failure. Most commonly, this will be a card_error which indicates there is an issue with your customer’s credit card. For these failures, send an email to the customer notifying them of the failure and directing them to the Billing Console. From the Billing Console, they can update their card information and reattempt payment.
  • Execute authentication steps: In some cases, banks will require follow-up action before approving a payment. For example, a bank might initiate a 3DS challenge to verify the customer. If a follow-up action is required, Metronome will fire a payment.payment_pending_action_required webhook. Upon receipt of this webhook, look up the payment in the payment gateway which will contain the action required. From there, send a notification to your customer prompting them to complete the action.

​
Customer configuration

In Metronome, billing settings are first configured on the customer via a customer_billing_configuration. Once the customer level options are defined, on contract creation you must associate one configuration to the contract which defines how Metronome will bill the contract’s invoices. This flexibility allows the same customer to be billed out of different destinations. For instance, one contract might be billed via AWS marketplace and the other through Metronome’s invoicing product. For more details, please refer to this guide. To configure a customer to be billed from Metronome’s invoicing product, create the customer_billing_configuration as follows: 
    {
		"billing_provider": "stripe",
		"delivery_method": "direct_to_billing_provider",
        "tax_provider": "avalara",
		"configuration": {
		    "stripe_customer_id": "cus_T4uJnLBmxYGdcL",
		    "stripe_collection_method": "auto_charge_payment_intent",
            "avalara_customer_code": "cctest"
      }
    }
⌘I