> ## Documentation Index
> Fetch the complete documentation index at: https://docs.staging.metronome.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage unbillable invoices

> Prevent select invoices from being sent to a billing provider.

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**

```bash theme={null}
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**

```bash theme={null}
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.

```bash theme={null}
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

```bash theme={null}
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

> [!NOTE]
>
> **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.

> [!NOTE]
>
> **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.

> [!NOTE]
>
> **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.