How to add a one-off fee alongside a draft subscription invoice

It is not currently possible to add a line item to an existing draft subscription invoice. The draft state allows the invoice to be refreshed or finalized, but fees cannot be injected into it after creation. This applies to both the UI and the API.

Note: PUT /invoices/{id} silently accepts a payload with a fees field and returns 200 — it just ignores the field. 

What you can do instead

The closest supported option is to create a separate one-off invoice for the customer via the API:

POST /api/v1/invoices

with a payload specifying the customer, currency, and one or more add-on fees. This creates a standalone invoice that is immediately finalized — it is not merged into the draft subscription invoice, and it does not wait for the grace period to expire.

This means the customer will receive two separate invoices: the subscription invoice when it finalizes, and the one-off invoice immediately. If your use case requires a single combined document, that is not currently supported.

When to use this

Use a one-off invoice when you need to charge a customer for something outside their subscription — a setup fee, a manual adjustment, or a custom service charge — and timing it alongside a subscription billing period is acceptable even if the documents are separate.

This article reflects guidance drawn from customer case resolutions. It is not officially supported documentation and may not apply to all situations.