Invoice with Stripe

Use Metronome’s native Stripe integration to invoice your customers with Stripe. With the Stripe integration, when an invoice finalizes at the end of the billing period, Metronome automatically creates a corresponding invoice in Stripe to collect payment.

Leveraging the advanced invoicing capabilities of Stripe helps you reduce your involuntary churn by maximizing your payment success rate for scenarios like pay-as-you-go customers.

This guide describes how to set up Stripe as your external billing provider, interact with the integration, and understand how Metronome handles Stripe limits.

Set up the Stripe integration

Setting up the Stripe integration involves connecting Metronome and Stripe and configuring invoice settings.

Connect Metronome and Stripe

When you connect your Stripe account with Metronome, Metronome can automatically create invoices in Stripe. Connecting involves granting Metronome the permissions to write and read data on your behalf to your Stripe account.

Clients commonly connect Stripe to Metronome production and sandbox environments. This enables them to test potential price changes or other invoice updates end-to-end before enabling them for production customers. When you set up the Stripe integration in Metronome Sandbox, Metronome automatically connects to your Stripe test mode so you can test your integration end-to-end with invoice creation and payment collection.

To connect Metronome and Stripe:

1. Authenticate your Stripe account from Metronome. Go to General Settings - Integrations → click Enable and complete the Stripe wizard.
2. Set up a Stripe connection from each Metronome environment you want to send invoices through, like production and sandbox environments.
3. Enable Stripe's automatic payment retry capabilities to improve invoice payment success.

Set the customer billing configuration

To determine which invoices to send to Stripe, Metronome looks at the billing_configuration for each customer. The billing_configuration is an object within the Metronome customer object that captures additional metadata necessary to support Metronome’s native integrations. This includes information like the billing provider customer.id and invoice preferences. If the customer’s billing_configuration is set to Stripe, a Stripe invoice gets issued to the corresponding Stripe customer.

Set the billing configuration for a customer in the Metronome app or with the API.

For the API, set this configuration during the customer creation process using the /customersendpoint or after the customer already exists with /billing-config setting the billing configuration.

This example payload uses the /customers endpoint to set the billing configuration:

curl https://api.metronome.com/v1/customers \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "ingest_aliases": [
      "team@example.com"
    ],
    "name": "Example, Inc.",
    "billing_config": {
      "billing_provider_type": "stripe",
      "billing_provider_customer_id": "STRIPE_CUSTOMER_ID",
      "stripe_collection_method": "charge_automatically"
    }
  }'

The billing configuration consists of two fields that dictate how the Stripe invoice is created:

• billing_provider_customer_id: The Stripe customer ID for the customer that gets issued a Stripe invoice.
• stripe_collection_method: Determines how to collect payment for the customer. Stripe supports two methods of collection:
  • charge_automatically: Stripe attempts to charge for the invoice using the default payment method attached to the customer.
  • send_invoice: Stripe emails this invoice to the customer with payment instructions. For 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 General Settings - Integrations page.

Configure optional global integration settings available

After enabling your Metronome customers to be invoiced in Stripe, you have certain options that you can configure from the General Settings - Integrations page.

Invoice settings
Set invoice due date	Stripe defaults to invoice due dates within 30 days after they're sent. You can change this option to a different value. This setting has no effect for customers configured to be charged automatically.
Leave invoices as drafts	By default, Metronome sends all invoices to Stripe with the auto_advance option set to true allowing invoices to be finalized in Stripe immediately without any action required on your side. If you prefer to leave invoices as draft so you can review and finalize manually in Stripe, mark the "leave invoices as drafts" option in Metronome. Metronome sets the Stripe auto_advance to false.
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 limits this to only send non-zero invoice. Stripe imposes limits on the minimum charge amounts. For example, with USD currency, the minimum charge allowed is $0.50. If you select "skip zero-total invoices,” Metronome skips sending invoices to Stripe that fall below the minimum charge amount for the currency.

Invoice Presentation
Display line items with zero quantity on Stripe invoices	If selected, Metronome creates a Stripe line item on the Stripe invoices for all charges, including the ones that have zero quantity.
Always display price and quantity information in Stripe invoice line item descriptions	Because Stripe doesn’t support decimal quantities, by default, Metronome displays quantities in line items if at least one quantity on an invoice is not an integer. 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.

info

These settings are enforced at the environment level. You cannot configure customer specific preferences.

Create optional entity mapping rules

By default, Metronome sets metadata on Stripe invoices objects that it creates. One item it sets is ametronome_id, which is the Metronome invoice ID that lets you map a Stripe invoice to its corresponding Metronome invoice.

You may want to add additional metadata to Stripe entities. For example:

• Add attributes like the contract name or contract ID to the Stripe invoice (visible to customers) by mapping Metronome contract or rate card custom fields to Stripe invoice custom fields.
• Add metadata like invoice line item and invoice line item price objects to the Stripe invoice for your internal audits or for downstream integrations like tax calculation.

To configure Metronome to automatically add your own additional metadata to Stripe entities, edit the Stripe integration mapping rules between Metronome custom fields and Stripe entities on the General Settings - Integrations page.

Assign line items to Stripe products example

A very common use case for adding metadata to Stripe entities is to assign line items on a Metronome invoice to an existing product in Stripe. The benefit is that Metronome always uses the same Stripe product for all your invoices line items for a Metronome product. To do this:

1. Create a custom field key on the Metronome product entity: stripe_product_id.
2. Set the value for the custom field key you just created for each of your products in Metronome.
3. Go to the General Settings - Integrations page and edit the mapping rules to map the Metronome custom field key stripe_product_id to Stripe invoiceitem.price .

Interact with the Stripe integration

After connecting Stripe with Metronome, use the Metronome API and app to interact with your integration.

Track Stripe invoice statuses in Metronome

Metronome captures Stripe webhook events when the status of an invoice changes.

The Stripe invoices statuses are accessible in Metronome as part of the response when fetching invoices from the list invoices API endpoint.

{
  "id": "INVOICE_ID",
  ...
  "external_invoice": {
    "billing_provider_type": "stripe",
    "invoice_id": "in_123",
    "issued_at_timestamp": "2024-09-30T16:40:40.30184+00:00",
    "external_status": "PAID"
  },
  ...
}

These statuses are accessible in your data warehouse through the Metronome data export. They include:

Stripe Webhook Event	external_status in Metronome
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

info

If the global configuration is set to Leave invoices as drafts, Stripe does not return a status and you won’t see a Stripe invoice status in Metronome.

Calculate dynamic sales tax

Metronome’s native Stripe integration supports Anrok, Avalara, and Stripe Tax providers to add tax to an invoice created in Stripe. To learn more, read calculate taxes.

When integrating with tax providers, the integration waits an hour for tax to be applied to an invoice by default. If no tax has been applied after an hour, the invoice is finalized without tax in stripe. If you prefer to leave these invoices in a draft state, contact your Metronome representative.

Listen for Errors

Invoicing errors can happen. For example, errors happen when Stripe customers don’t exist. To receive notifications from Metronome when an error sending an invoice to Stripe occurs, listen for the webhook type invoice.billing_provider_error . When receiving those webhooks, trigger internal notifications and actions to ensure proper invoicing of your customers.

How Metronome handles Stripe limitations

Stripe enforces certain limits on invoices that may cause discrepancies or issues when billing customers. This table describes how Metronome handles these limitations.

Stripe limitation	Metronome approach
Stripe does not support decimal quantities	If the quantity is a decimal for at least on line item on the invoice, Metronome sets the quantity as 1 for all the Stripe line items on the invoice. Metronome and provides the true quantity as part of each line item description.
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 and the invoice total as the associated price. Provide full invoice visibility (with all line items) to your customers with dashboards that expose invoices in your UI.
Stripe does not allow a charge above 999,999.99 USD	Metronome generates an error when creating an invoice with an amount above the Stripe maximum. Contact your Stripe representative and Metronome representative to increase the limit if you need invoices with amounts above $999,999.99.
No native support for issuing credit memos with Metronome	The Metronome integration does not natively support issuing credit memos in Stripe. Learn more how to issue credit memos.