Manage unbillable invoices

Use unbillable_invoices_configuration to control contract invoices Metronome sends to a downstream billing provider. Invoices that are not sent are still finalized in Metronome, but they are marked unbillable during normal processing. Common use cases include:

Suppressing overage invoices for a prepaid customer.
Suppressing scheduled invoices (i.e. commit installments) billed directly in a cloud marketplace.

unbillable_invoices_configuration is set on a customer billing provider configuration. To apply a policy to a contract, first create a billing provider configuration with the rules you want, then assign that configuration to the contract. If you omit unbillable_invoices_configuration, it defaults to [] and all invoices are billable. Existing integrations are unaffected.

Define unbillable invoice rules

unbillable_invoices_configuration is an array of rules. Each rule identifies invoices that Metronome treats as unbillable.

Field	Required	Description
`invoice_type`	Yes	The invoice type the rule applies to: `USAGE` or `SCHEDULED`.
`fiat_credit_type_id`	Conditional	The fiat currency the rule applies to. Required when `max_amount` is set. Omit to create a catch-all rule that applies to every fiat currency for the `invoice_type`.
`max_amount`	No	A positive number in the units of `fiat_credit_type_id`. Invoices with a total less than or equal to this amount are unbillable. Omit to make every matching invoice unbillable regardless of amount.

An empty array, [], is valid and means all invoices are billable.

Supported billing providers

Billing provider	`USAGE` rules	`SCHEDULED` rules
Stripe	✅	✅
NetSuite	✅	✅
Marketplace (AWS / Azure / GCP)	❌	✅

Rule precedence

For a given invoice type, Metronome first looks for a rule that matches the invoice’s fiat_credit_type_id. If one exists, Metronome evaluates only that rule. If no currency-specific rule exists, Metronome evaluates the catch-all rule for that invoice type, if one is present.

Validation

Metronome validates rules when you create the billing provider configuration and returns an error if any of the following are violated:

Every rule must include invoice_type, set to USAGE or SCHEDULED.
max_amount, when present, must be a positive number.
A rule with max_amount must include fiat_credit_type_id.
For the same invoice_type, each fiat credit type can appear in at most one rule.
For the same invoice_type, at most one catch-all rule can omit fiat_credit_type_id.
Marketplace configurations only support SCHEDULED rules.

Apply rules to a new contract

Suppress all overage invoices

Let’s walk through an example for suppressing all overage invoices for a prepaid customer: Step 1: Create the billing provider configuration

curl https://api.metronome.com/v1/setCustomerBillingProviderConfigurations \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "customer_id": "8cecbf69-960f-4f66-9575-edebb7d95e88",
        "billing_provider": "stripe",
        "delivery_method": "direct_to_billing_provider",
        "configuration": {
          "stripe_customer_id": "cus_123",
          "stripe_collection_method": "charge_automatically"
        },
        "unbillable_invoices_configuration": [
          {
            "invoice_type": "USAGE"
          }
        ]
      }
    ]
  }'

Step 2: Create a contract with the configuration

curl https://api.metronome.com/v1/contracts/create \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "8cecbf69-960f-4f66-9575-edebb7d95e88",
    "starting_at": "2026-09-01T00:00:00.000Z",
    "rate_card_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
    "billing_provider_configuration": {
      "billing_provider_configuration_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }'

All usage invoices on the new contract have a billable_status of unbillable.

Send overages over a fixed amount

Make USD usage invoices with totals up to 10 unbillable. USD usage invoices above 10 and all scheduled invoices remain billable.

curl https://api.metronome.com/v1/setCustomerBillingProviderConfigurations \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "customer_id": "8cecbf69-960f-4f66-9575-edebb7d95e88",
        "billing_provider": "stripe",
        "delivery_method": "direct_to_billing_provider",
        "configuration": {
          "stripe_customer_id": "cus_456",
          "stripe_collection_method": "charge_automatically"
        },
        "unbillable_invoices_configuration": [
          {
            "invoice_type": "USAGE",
            "fiat_credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
            "max_amount": 1000
          }
        ]
      }
    ]
  }'

Example: Suppress scheduled invoices billed to a cloud marketplace

curl https://api.metronome.com/v1/setCustomerBillingProviderConfigurations \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "customer_id": "8cecbf69-960f-4f66-9575-edebb7d95e88",
        "billing_provider": "aws_marketplace",
        "delivery_method": "direct_to_billing_provider",
        "configuration": {
          "aws_customer_id": "cust_789",
          "aws_product_code": "my_product",
          "aws_region": "us-west-1"
        },
        "unbillable_invoices_configuration": [
          {
            "invoice_type": "SCHEDULED"
          }
        ]
      }
    ]
  }'

Apply rules to an existing contract

To change the policy on an existing contract, create a new billing provider configuration with the appropriate billable settings. Then, schedule a change to the customer billing provider configuration on the contract, replacing the existing configuration with the new one created.

Constraints and considerations

Draft invoice totals can switch from unbillable to billable. For rules with max_amount, Metronome evaluates the invoice’s current total, so a draft invoice’s billable_status can change as its total changes. Once an invoice is finalized, its total and billable_status are stable.

You can manually send an unbillable Stripe invoice. In the Metronome app, an authorized user can click Send to Stripe to send an individual unbillable invoice. After the invoice is sent, its billable_status is billable. This is only available for Stripe.

Voided and regenerated invoices use the original period’s configuration. When Metronome voids and regenerates an invoice, the regenerated invoice uses the billing provider configuration from the invoice’s service period.

GET STARTED

IMPLEMENT METRONOME

EVENTS

PRICING & PACKAGING

CUSTOMERS & BILLING

INVOICING

REPORTING & INSIGHTS

PLATFORM CONFIGURATION

Manage unbillable invoices

Define unbillable invoice rules

Supported billing providers

Rule precedence

Validation

Apply rules to a new contract

Suppress all overage invoices

Send overages over a fixed amount

Example: Suppress scheduled invoices billed to a cloud marketplace

Apply rules to an existing contract

Constraints and considerations

​Define unbillable invoice rules

​Supported billing providers

​Rule precedence

​Validation

​Apply rules to a new contract

​Suppress all overage invoices

​Send overages over a fixed amount

​Example: Suppress scheduled invoices billed to a cloud marketplace

​Apply rules to an existing contract

​Constraints and considerations

Define unbillable invoice rules

Supported billing providers

Rule precedence

Validation

Apply rules to a new contract

Suppress all overage invoices

Send overages over a fixed amount

Example: Suppress scheduled invoices billed to a cloud marketplace

Apply rules to an existing contract

Constraints and considerations