# Metronome invoice and payment reference

Understand invoice processing and payment collection for Metronome invoices in Stripe.

Use this reference to understand how Metronome invoices work in Stripe. To configure the integration, follow [Set up Metronome with Stripe](https://docs.stripe.com/billing/set-up-metronome-with-stripe.md).

## Invoice lifecycle

The invoice lifecycle is the same for both [integration patterns](https://docs.stripe.com/billing/how-metronome-works-with-stripe.md#integration-patterns):

1. **Invoice finalization**: At the end of a billing period (or on a contract schedule), Metronome computes and finalizes an invoice.
2. **Line item creation**: Metronome creates [InvoiceItem](https://docs.stripe.com/api/invoiceitems.md) objects on the Stripe Customer through the Stripe API. Metronome creates all line items before the Invoice object itself, so downstream listeners (tax providers, webhooks) see a complete invoice on creation.
3. **Invoice creation**: Metronome calls [POST /v1/invoices](https://docs.stripe.com/api/invoices/create.md) on the Stripe Customer, which automatically attaches all pending line items.
4. **Validation**: Metronome validates that the Stripe invoice total matches the Metronome invoice total within a rounding tolerance.
5. **Finalization**: Depending on configuration, Metronome either auto-finalizes invoices or leaves them in draft for manual review. If you configure a tax provider, such as Stripe Tax, Metronome might defer finalization until the tax provider applies tax.
6. **Webhook consumption**: Metronome listens for Stripe webhooks (`invoice.finalized`, `invoice.paid`, `invoice.payment_failed`, `invoice.payment_succeeded`, `invoice.voided`, `invoice.marked_uncollectible`, `invoice.deleted`) to track payment status and update invoice records. For the complete webhook-to-status mapping, see [Stripe invoice status tracking](https://docs.metronome.com/integrations/invoice-integrations/stripe#track-stripe-invoice-statuses-in-metronome).

### Invoice attributes

The following table shows which system controls each invoice attribute after Metronome pushes an invoice to Stripe:

| Invoice attribute | Controlled by |
| --- | --- |
| Line items (names, quantities, unit amounts) | Metronome |
| Sub-line item breakdowns (tiered pricing, presentation group keys) | Metronome (configurable through [group keys](https://docs.metronome.com/guides/implement-metronome/core-concepts/create-products-contracts#group-keys%E2%80%8B)) |
| Invoice metadata (`metronome_invoice_id`, `client_id`, `environment`) | Metronome ([entity mapping rules](https://docs.metronome.com/integrations/invoice-integrations/stripe#create-optional-entity-mapping-rules)) |
| Service period dates on line items | Metronome |
| Collection method (`send_invoice` or `charge_automatically`) | [Configurable per customer](https://docs.metronome.com/integrations/invoice-integrations/stripe#set-the-customer-billing-configuration) |
| Days until due (for example, Net 30) | [Account-level configuration](https://docs.metronome.com/integrations/invoice-integrations/stripe#configure-optional-global-integration-settings-available) |
| Draft or auto-finalize behavior | [Account-level configuration](https://docs.metronome.com/integrations/invoice-integrations/stripe#configure-optional-global-integration-settings-available) |
| Tax calculation | [Stripe Tax](https://docs.metronome.com/integrations/tax-integrations/stripe-tax) (applied after Metronome creates line items) |
| Payment method, Radar fraud screening, [Smart Retries](https://docs.stripe.com/billing/revenue-recovery/smart-retries.md) | Stripe |
| Invoice presentation, branding, header, and footer | Stripe |
| Invoice available payment methods | Stripe |

## Payments

After a Metronome invoice finalizes in Stripe, the following Stripe Payments features are available:

- **Collection methods**: Metronome supports both `charge_automatically` (Stripe charges the customer’s default payment method) and `send_invoice` (Stripe emails the customer) [collection methods](https://docs.metronome.com/integrations/invoice-integrations/stripe#set-the-customer-billing-configuration).
- [**Smart Retries**](https://docs.stripe.com/billing/revenue-recovery/smart-retries.md): Stripe chooses optimal retry times for failed payments.
- [**Dunning and revenue recovery**](https://docs.stripe.com/billing/revenue-recovery.md): Stripe sends failed-payment emails and handles the retry lifecycle. Enable [Stripe dunning and revenue recovery](https://docs.stripe.com/billing/revenue-recovery.md) on your Stripe account to automate failed-payment follow-up.
- **Radar**: Screens for fraud on card payments.
- **Global payment methods**: All payment methods supported by Stripe Invoicing are available (cards, ACH, SEPA, wire, and so on).
- **Payment method management**: Stripe is the system of record for customer payment methods.

### Payment-gated commits

Metronome supports [payment-gated commits](https://docs.metronome.com/guides/pricing-packaging/apply-credits-and-commits/manual-payment-gated-commits) (including [threshold billing and auto-recharge](https://docs.metronome.com/guides/customers-billing/optimize-customer-experience/prepaid-balance-thresholds)), where Metronome releases credits only after the Stripe invoice reaches `paid` status. This includes support for ACH with a 13-day payment window.

If a payment-gated auto-recharge payment fails, Metronome voids the invoice and disables the contract’s auto-recharge. You follow up with the customer and manually re-enable the contract. For the complete workflow, see [Prepaid balance threshold](https://docs.metronome.com/guides/customers-billing/optimize-customer-experience/prepaid-balance-thresholds).

### Payment failures

Metronome tracks Stripe invoice payment status through webhooks. Stripe handles payment collection and retry logic. The failure path depends on how you configure the invoice:

- **Charge automatically**: When you set the invoice’s `collection_method` to `charge_automatically`, Stripe owns the retry cycle. If you enable [Smart Retries](https://docs.stripe.com/billing/revenue-recovery/smart-retries.md), Stripe uses machine learning to choose optimal retry times (up to eight attempts within a configurable window). Metronome receives `invoice.payment_failed` and updates the invoice status to `PAYMENT_FAILED`, but takes no retry action.
- **Send invoices**: When you set the invoice’s `collection_method` to `send_invoice`, Stripe emails the invoice to the customer with payment instructions. If payment isn’t received by the due date, the invoice remains in open status in Stripe. Metronome tracks the status, but Stripe handles payment reminders and follow-up through [dunning and revenue recovery](https://docs.stripe.com/billing/revenue-recovery.md).
- **Payment-gated threshold billing**: If a payment-gated auto-recharge invoice fails, Metronome sets the contract’s `is_enabled` field to false and voids the invoice. Re-enable threshold billing on the contract to resume auto-recharge.

Metronome sends `invoice.billing_provider_error` webhooks when there’s an error sending an invoice to Stripe (for example, the Stripe customer doesn’t exist or lacks a valid payment method). Errors that occur entirely within Stripe are reported through [Stripe webhooks](https://docs.stripe.com/webhooks.md). For the full list of Metronome events, see [Metronome webhook types](https://docs.metronome.com/guides/platform-configuration/setup-webhooks).

### Post-invoice operations

After Metronome pushes an invoice to Stripe, you manage the following operations directly in Stripe or your other systems (for example, your ERP or CRM):

- **Refunds**: Process refunds in Stripe through the Dashboard or [Refunds API](https://docs.stripe.com/refunds.md), your ERP, or your CRM. To credit future billings within Metronome, see [Issue credit memos](https://docs.metronome.com/guides/invoices/invoice-optimization/issue-credit-memos).
- **Invoice adjustments**: Use the [Metronome Credits API](https://docs.metronome.com/api-reference/credits-and-commits/create-a-credit) to issue a credit, then void and regenerate the invoice in Metronome and resync it to Stripe.
- **Invoice voiding**: Metronome and Stripe maintain independent invoice records. Void the invoice in both systems (and any other downstream system) to keep records in sync.
