---
title: How invoices are generated
description: The reasons an invoice is created, from a renewal to a manual bill.
domain: invoice
status: shipped
visibility: public
last_verified: 2026-08-28
order: 20
---
Every invoice records why it exists. That reason is shown on the invoice, and it tells you at a glance whether the bill came from a renewal, a new signup, a manual charge, or something else.

## The reasons an invoice is created

| Reason | When it happens |
|---|---|
| New subscription | The first invoice for a subscription, at signup. |
| Renewal | A recurring invoice for an existing subscription, each cycle. |
| Manual | A one-off invoice you compose by hand, not tied to a subscription's cycle. |
| Subscription cancel | A final invoice when a subscription is cancelled, settling anything still owed. |
| Proration | An immediate invoice for a mid-cycle change, when you have chosen to bill changes right away. |
| Imported | A historical invoice brought in from another system by the importer. |
| Wallet top-up | A charge to buy prepaid wallet credit. |

## Automatic and manual

**Automatic.** Most invoices are generated by the billing engine on the subscription's schedule. A renewal invoice goes out each cycle without anyone touching it. A new subscription's first invoice is created when it starts. These arrive already open, waiting for payment.

**Manual.** You can also compose an invoice by hand for a one-off charge that is not part of a subscription. You build the lines, then finalize it to send it. This is the draft path from the lifecycle page.

## Mid-cycle changes usually do not invoice right away

When a subscription changes in the middle of a period, the credit and charge from proration do not become their own invoice by default. They wait and settle on the next renewal invoice. This keeps a customer from getting a small separate bill every time they adjust their plan.

If you would rather bill a change the moment it happens, you can choose to invoice it immediately. That creates an invoice with the proration reason, for just the change. The [proration chapter](/guide/proration) covers the behaviors in full.

## One invoice per subscription, or one combined

By default, each subscription bills on its own invoice. A customer with three subscriptions gets three invoices.

You can instead have a customer's subscriptions roll up into one combined invoice per cycle. Turn on consolidated invoicing for the customer, and when the billing run finds two or more of their subscriptions due together, it puts all their lines on a single invoice.

A few rules decide when subscriptions can combine:

- **At least two subscriptions** must be due together. One on its own just bills normally.
- **One currency.** Subscriptions in different currencies cannot share an invoice, so they bill separately.
- **No active coupon.** A subscription with a coupon keeps its own invoice, because the discount is worked out per subscription.

If a combined invoice would come out to a credit rather than an amount owed, for example when large mid-cycle credits outweigh the charges, the run does not consolidate and bills the subscriptions on their own instead.

## Cancellation can produce a final invoice

Cancelling a subscription immediately can create one last invoice, to settle usage the customer ran up and any charges waiting in the unbilled queue, including a one-time charge that was added but not yet billed. A clean subscription with nothing owed produces no final invoice. See [cancelling](/guide/subscriptions/cancelling) for how this fits the cancellation flow.

## In the API

Compose a one-off invoice by hand with the `POST /v1/invoices` endpoint, then finalize it to send it. The engine creates renewal and new-subscription invoices for you on the schedule, so those are not something you call. See the [API reference](/reference).

## Edge cases

- **Imported invoices stay quiet.** An invoice brought in by the importer is a historical record. It does not send emails or trigger dunning, because those already happened in the old system.
- **A mid-cycle change never carries its own "change" reason.** Either it settles on the next renewal, or, if you bill it immediately, it goes out as a proration invoice.