# Invoice item creation and routing

Configure Stripe-authored scripts to customize invoice item creation and routing behavior.

Invoice item creation and routing scripts allow you to decide how subscriptions create invoice items, when they assign them to invoices, and how they group line items onto one or more invoices.

You can use the following scripts that Stripe provides, or [author your own script](https://docs.stripe.com/billing/scripts/item-handling.md#author-your-own-script).

> You’re responsible for ensuring your configuration is correct. Stripe doesn’t take responsibility for any issues that arise as a result of your configuration.
> 
> If your script raises an error (for example, returns an invalid result, throws an exception, or times out), Stripe defaults to standard functionality for the operation that caused the failure.

[Set up real-time failure notifications](https://docs.stripe.com/extensions/scripts/monitor-and-debug.md#receive-failures-in-real-time) to understand when and why Billing scripts fail.

## Separate invoice for metered items 

By default, when a subscription contains both metered usage items and licensed items, Stripe puts them all on a single invoice. This script routes them to separate invoices based on the item’s usage type. The invoice with licensed items becomes the latest invoice for the subscription.

Use this script when your finance team needs to reconcile usage charges separately from recurring seat or license fees, or when your customers expect different invoices for them.

[View the source code on GitHub](https://github.com/stripe/billing-extensions/tree/main/extensions/separate_invoice_for_metered_items).

### Configuration options 

In the Dashboard, go to **Settings** > **Billing** > [Billing customizations](https://dashboard.stripe.com/settings/billing/customizations).

1. Select **Customize** next to **Invoice item creation and routing**.
2. Select **Separate invoice for metered items**.
3. Select **Save** and confirm activation.

This script has no additional parameters. It automatically routes items based on their usage type.

### Example 

A subscription includes a “Pro Plan” licensed at 20 USD per month and metered API usage totaling 15 USD this billing cycle.

**Default behavior**

One invoice with both items.

- Invoice total: 35 USD (20 USD license + 15 USD usage)

**After activating the script**

Two separate invoices.

- Invoice 1 (licensed): 20 USD for Pro Plan. This invoice becomes the subscription’s latest invoice.
- Invoice 2 (metered): 15 USD for API usage.

To see the change in the Dashboard, go to the subscription details page and check the **Invoices** tab to see two invoices for the billing period instead of one.

## Skip creating a partial period proration item 

By default, Stripe creates proration items for partial billing periods. This script skips creating matching partial-period credits and debits. It doesn’t replace prorated amounts with full-price charges or route items to separate invoices. It keeps the remaining items together on one invoice.

Use this script when you don’t want to invoice partial-period prorations for specific products, but still want to invoice full periods for those products.

An item qualifies when:

- Its product metadata matches your configuration.
- It’s marked as a proration.
- Its proration factor isn’t a whole number. Whole-number factors such as `0`, `1`, `-1`, and `2` remain invoiced, even on items marked as prorations. Fractional factors such as `0.5` and `2.5` qualify for suppression.

The script also skips credits associated with a debit that it suppresses in the same input, even if the credit doesn’t independently match the metadata or partial-period rule. This association rule doesn’t automatically skip future credits for previously suppressed debits.

The script checks metadata on the product associated with a `Price`, not metadata on the `Price` or a rate-card rate. Metadata keys must match exactly. Values ignore case and surrounding whitespace.

[View the source code on GitHub](https://github.com/stripe/billing-extensions/tree/main/extensions/skip_creating_partial_period_proration_item).

### Configuration options 

In the Dashboard, go to **Settings** > **Billing** > [Billing customizations](https://dashboard.stripe.com/settings/billing/customizations).

1. Select **Customize** next to **Invoice item creation and routing**.
2. Select **Skip creating partial period proration item**.
3. Set **Product metadata key** to the metadata key to check on each product.
4. Set **Product metadata value** to the value that identifies products with partial-period prorations you want to skip.
5. Select **Save** and confirm activation.

Before activating, add the same metadata key-value pair to each applicable product:

1. In the Dashboard, go to **Product catalog**.
2. Open the product.
3. Go to **Metadata** > **Add metadata** and enter the key-value pair you configured in the script.
4. Select **Save**.

Repeat for each applicable product.

### Example 

A product has the metadata key `suppress_prorations` set to `true`. A subscription produces a partial-period debit marked as a proration with factor `0.5` and a full-period item with factor `1` for that product.

**Default behavior**

Stripe creates both items and invoices the partial-period debit at its prorated amount and the full-period item at its full amount.

**After activating the script**

With **Product metadata key** set to `suppress_prorations` and **Product metadata value** set to `true`:

- The partial-period debit with factor `0.5` isn’t created.
- The full-period item with factor `1` remains invoiced at its full amount.

To check the result in the Dashboard, select **Invoices** on the subscription details page and open the generated invoice.

## Remove zero-quantity metered items before creation 

By default, zero-quantity metered items can appear on subscription invoices. This script skips creating metered credits and debits with a quantity of exactly zero. Without a product metadata matcher, it applies to metered `Prices`, rate-card rates, and custom-pricing-unit overage rates. Licensed items and nonzero quantities, including negative quantities, remain invoiced.

Use this script to omit unused metered items from invoices. The criterion is quantity, not the calculated amount, so it doesn’t remove every zero-amount item. It doesn’t delete existing invoice items or change subscription quantities. It keeps the remaining items together on one invoice.

The optional **Product metadata** matcher restricts suppression to matching products associated with `Prices`. It checks product metadata, not `Price` metadata. Keys must match exactly, and values ignore case and surrounding whitespace. With a matcher configured, rate-card and overage-rate items remain invoiced because they don’t expose the product metadata this script checks.

[View the source code on GitHub](https://github.com/stripe/billing-extensions/tree/main/extensions/remove_zero_quantity_metered_items_before_creation).

### Configuration options 

In the Dashboard, go to **Settings** > **Billing** > [Billing customizations](https://dashboard.stripe.com/settings/billing/customizations).

1. Select **Customize** next to **Invoice item creation and routing**.
2. Select **Remove zero-quantity metered items before creation**.
3. Configure the optional **Product metadata** matcher:
   - Leave it unset to skip all qualifying zero-quantity metered items.
   - Set its key and value to restrict suppression to matching products associated with `Prices`. Before activating, add that same key-value pair to each applicable product in **Product catalog** > **Metadata** > **Add metadata**, then select **Save**.
4. Select **Save** and confirm activation.

### Example 

A subscription includes two per-unit metered usage items and a recurring licensed fee:

- API usage: 0 units at 0.01 USD per unit.
- Storage usage: 10 units at 1 USD per unit.
- Licensed fee: 20 USD per month.

**Default behavior**

The invoice includes the zero-quantity API usage item, the storage usage item, and the licensed fee.

**After activating the script**

With **Product metadata** left unset:

- The zero-quantity API usage item isn’t created.
- The storage usage item remains invoiced at 10 USD.
- The licensed fee remains invoiced at 20 USD.

To check the result in the Dashboard, select **Invoices** on the subscription details page and open the generated invoice.

## See also

- [Stripe-authored scripts](https://docs.stripe.com/billing/scripts/stripe-authored.md)
- [Configure a script in the Dashboard](https://docs.stripe.com/billing/scripts/configure.md)
- [Control which items appear on subscription invoices](https://docs.stripe.com/billing/scripts/item-handling.md)