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.

​
Connecting Metronome to Multiple Stripe Accounts​

Metronome supports multi-entity billing with Stripe so you can connect your Metronome environment to many Stripe accounts. This feature enables complex enterprises to manage their billing and finances as distinct business units. To set up multiple Stripe accounts:
  1. Go to Connections - > Integrations
  2. Select Stripe - > Add another
  3. Select the appropriate Stripe account
Once complete, you will see a row in Active Integrations for each Stripe account that Metronome is connected to. You can create an alias for each account to identify them. For example: Stripe NA and Stripe EU . This alias will appear wherever the Stripe account is referenced in the Metronome App.
WARNINGIf using multi-entity billing, you must use delivery_method_id when setting the customer billing configuration. Ensure that your customer sign-up flow uses this field before setting up multi-entity billing. See set customer billing configuration for more details.

​
Configure optional global integration settings available

After connecting Metronome to Stripe, you have certain options that you can configure from the General Settings - Integrations page. If connected to multiple Stripe accounts, you will need to configure the settings for each account independently.
Invoice settings
Set invoice due dateStripe 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 draftsBy 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 invoicesIf 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.
Align effective_at with last day of periodBy default, Stripe populates the “Invoice Date” field on PDF invoices and effective_at in the API with the date the invoice is finalized. Use this setting to populate the effective_at field with the last date of the invoice’s service period (like Oct 31 for an Oct 1-31 invoice). This can help ensure usage invoices are tracked against the correct accounting period, aligning with revenue recognition practices in downstream finance systems.
This setting isn’t supported with Stripe Tax due to a Stripe limitation that causes invoice syncing to fail.
Invoice Presentation
Display line items with zero quantity on Stripe invoicesIf 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 descriptionsBecause Stripe doesn’t support decimal quantities, by default, Metronome displays quantities in line item descriptions if at least one quantity on an invoice is not an integer. By selecting “always display quantities in line items”, quantities will always appear in line item names, regardless of whether the invoice has any non-integer quantities.
INFOThese settings are enforced per Stripe account 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 a metronome_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. If connected to multiple Stripe accounts, you will need to configure each of these mappings individually. Assign line items to Stripe products example A common use case for adding metadata to Stripe entities is assigning line items on a Metronome invoice to an existing product in Stripe. 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 .
Stripe mapping

​
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.
INFOIf connected to multiple Stripe accounts, you can only set the billing configuration via the API.
For the API, set this configuration during the customer creation process using the /customersendpoint or after the customer already exists with /setCustomerBillingProviderConfigurations setting the billing configuration. To set the a billing configuration, Metronome requires you to either specify a delivery_method or delivery_method_id. If you are only connecting to a single Stripe account, use the delivery_method. If connecting to multiple Stripe accounts, you must use delivery_method_id. Metronome uses this ID to determine which Stripe account each invoice should be sent to.
INFOYou can find the delivery_method_id by using the /listConfiguredBillingProviders endpoint to fetch configured Stripe accounts in the Metronome environment.
This example payload uses the /customers endpoint to set the billing configuration using delivery_method: 
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.",
    "customer_billing_provider_configurations": [{
      "billing_provider": "stripe",
      "configuration": {
        "stripe_customer_id": "cus_456",
        "stripe_collection_method": "charge_automatically"
      },
      "delivery_method": "direct_to_billing_provider"
    }]
  }'
This next example payload uses the /setCustomerBillingProviderConfigurations to set the billing configuration of an existing client using delivery_method_id: 
curl https://api.metronome.com/v1/setCustomerBillingProviderConfigurations \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "customer_id": "4db51251-61de-4bfe-b9ce-495e244f3491",
        "billing_provider": "stripe",
        "configuration": {
          "stripe_customer_id": "cus_1234",
          "stripe_collection_method": "charge_automatically"
        },
        "delivery_method_id": "5b95d955-b705-41c8-9d2e-34ccbdee5193"
      }
    ]
  }'
The billing configuration consists of two fields that dictate how the Stripe invoice is created:
  • stripe_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.

​
Set the contract billing configuration​

Metronome supports configuring the billing on the contract level. This allows you to optimize the billing for each contract: you may send pay-as-you-go contracts through Stripe but enterprise-level contracts through AWS. This example payload uses the /contracts/create endpoint to set the billing configuration: 
curl https://api.metronome.com/v1/contracts/create \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "6ae46ff3-a73e-4553-a139-346eafcea608",
    "rate_card_id": "cfe45e46-0277-42e0-b66a-45ccbd028913",
    "starting_at": "2025-01-01T00:00:00.000Z",
    "billing_provider_configuration": {
      "billing_provider": "stripe",
      "delivery_method": "direct_to_billing_provider"
    }
  }'
If connected to multiple Stripe accounts, one customer may be mapped to multiple Stripe accounts. When creating the contract, use the billing_configuration_id which can be fetched from the /getCustomerBillingProviderConfigurations endpoint: 
curl https://api.metronome.com/v1/contracts/create \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "6ae46ff3-a73e-4553-a139-346eafcea608",
    "rate_card_id": "cfe45e46-0277-42e0-b66a-45ccbd028913",
    "starting_at": "2025-01-01T00:00:00.000Z",
    "billing_provider_configuration": {
      "billing_provider_configuration_id": "561ea579-e830-41d9-9161-d35313c061c5"
    }
  }'

​
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 Eventexternal_status in Metronome
invoice.finalizedFINALIZED
invoice.marked_uncollectibleUNCOLLECTIBLE
invoice.paidPAID
invoice.payment_failedPAYMENT_FAILED
invoice.payment_succeededPAID
invoice.voidedVOID
invoice.deletedDELETED
INFOIf 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 limitationMetronome approach
Stripe does not support decimal quantitiesIf the quantity is a decimal for at least one 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 invoicesIf 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 USDMetronome 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 MetronomeThe Metronome integration does not natively support issuing credit memos in Stripe. Learn more how to issue credit memos.