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

# Invoice-Based Billing

> Send an invoice first and collect payment after. Bill one-time or recurring items on payment terms, by auto-charge or through a hosted invoice page.

![The Manage Invoices page in the Dodo Payments dashboard, with tiles for drafts, open invoices, past-due invoices, and the outstanding amount](https://mintcdn.com/dodopayments/aP958i30jx5nBLqD/images/invoice-based-billing/invoice-list.png?fit=max\&auto=format\&n=aP958i30jx5nBLqD\&q=85\&s=9f268a2b5ea6b2bb58e7b34df2234317)

## Overview

Invoice-based billing lets you bill a customer before they pay. You issue an invoice with a due date. The customer reviews it, then pays on a hosted invoice page, or Dodo Payments charges their saved card on the due date. Use it for B2B sales on payment terms, such as Net 30, for annual contracts, and for customers who need an invoice before their finance team pays.

This is the opposite order to checkout. With checkout, the customer pays first and Dodo Payments generates the invoice after the payment. With invoice-based billing, the invoice comes first and the payment settles it.

Dodo Payments is the [Merchant of Record](https://docs.dodopayments.com/features/mor-introduction.md) on every invoice. The Dodo Payments legal entity is the seller, and your brand name and logo identify the sale for your customer.

> [card] [Invoice Management](https://docs.dodopayments.com/features/invoice-generation.md)
>
> Set the brand name and logo that every invoice shows.

> [card] [Subscription Payment Retries](https://docs.dodopayments.com/features/recovery/payment-retries.md)
>
> Configure the retry schedule that auto-charge invoices use.

## How It Works

An invoice goes through these steps:

**1. Draft**

You create a draft with a customer, items, a currency, a due date, and a collection method. You can change every field of a draft, or delete it.

**2. Finalize**

You finalize the draft. Dodo Payments fixes the tax, the currency, the customer address, and the tax ID, sets the due date, and the invoice becomes `open`. You can send it to the customer at the same time.

**3. Collect**

With **Auto-charge**, Dodo Payments charges the customer's saved card on the due date. With manual collection, the customer pays on the hosted invoice page. Reminder emails follow your reminder schedule.

**4. Settle**

When the payment succeeds, the invoice becomes `paid`. If the due date passes first, the invoice becomes `past_due`, and you can extend the due date, void the invoice, or mark it uncollectable.

## Invoice Statuses

An invoice always has one of these statuses:

| Status | Meaning |
| - | - |
| `draft` | The invoice is not issued. You can edit or delete it. The customer cannot see it. |
| `open` | The invoice is issued and waits for payment before its due date. |
| `past_due` | The due date passed and the invoice is not paid. |
| `paid` | A payment settled the full amount due. |
| `void` | You cancelled the invoice before payment. No payment is collected. |
| `uncollectable` | The invoice is written off after dunning ends. |

`paid`, `void`, and `uncollectable` are final statuses. A deleted draft is removed from the list.

A `paid` invoice can also carry tags. Tags do not change the status:

| Tag | Meaning |
| - | - |
| `partially_refunded` | Part of the payment is refunded. |
| `refunded` | The full payment is refunded. |
| `disputed` | The customer opened a dispute on the payment. |
| `payment_reversed` | The dispute was lost, accepted, or expired. |

## Creating an Invoice

You create invoices on the **Invoices** page of the dashboard, or with the API. The customer must have a billing address with a country, street, city, and ZIP code before you can finalize the invoice.

![The Create New Invoice form, with a selected customer, one product item, and a live PDF preview](https://mintcdn.com/dodopayments/aP958i30jx5nBLqD/images/invoice-based-billing/create-invoice.png?fit=max\&auto=format\&n=aP958i30jx5nBLqD\&q=85\&s=c668d37ebedbad767a4b1672e1da2e55)

**1. Open the invoice form**

Go to **Invoices** and click **Create Invoice**.

**2. Select the customer**

In **Select Customer**, search for a customer by name or email, or add a new customer. If the customer has no billing address, click **Add** next to **Billing Address**. A business customer also needs a tax ID. See [B2B Payments](https://docs.dodopayments.com/features/b2b-payments.md).

**3. Add items**

In **Items**, add products from your catalogue. To bill a subscription through invoices, add a subscription product.

**4. Set the payment terms**

In **Payments**, select a **Due Date**: **Today**, **Tomorrow**, **1 Week**, **2 Weeks**, or **Pick a date**. Terms count from the time you finalize the invoice. To apply a discount, select the **Apply Additional Discount** checkbox, then select a [discount code](https://docs.dodopayments.com/features/discount-codes.md).

**5. Select how to collect**

To charge the customer's saved card on the due date, turn on **Auto-charge** and select the card. Auto-charge needs a subscription item. Otherwise, leave it off, and the customer pays on the hosted invoice page.

**6. Set review and reminders**

For an invoice with a subscription item, turn on **Manual review** to review each renewal invoice before it goes to the customer. See [Reviewing Renewal Invoices](#reviewing-renewal-invoices). Keep **Reminders** on to send reminder emails on your business reminder schedule.

**7. Check the preview**

Use the **Preview** panel to see the **PDF**, the **Email Preview**, and the **Hosted Preview**.

**8. Save or finalize**

Click **Save as Draft** to keep the invoice editable. Click **Finalise Invoice** to issue it. In the **Review Invoice** dialog, click **Add Recipients** to set the **Send to** and **Additional CC recipients** addresses, then click **Finalise & Send**.

![The Payments and Reminders sections of the invoice form, with the due date, discount, Auto-charge, and Dunning and Retries controls](https://mintcdn.com/dodopayments/aP958i30jx5nBLqD/images/invoice-based-billing/create-invoice-payments.png?fit=max\&auto=format\&n=aP958i30jx5nBLqD\&q=85\&s=f7271738cb70ca0df474f66c832d6998)

### What Happens at Finalize

When you finalize an invoice, Dodo Payments does these steps:

* It calculates the tax and fixes the currency, the billing address, and the tax ID. After this, you cannot change them.
* It sets the due date from the payment terms. A manual invoice that is due on receipt gets 24 hours to be paid.
* It applies the customer's [wallet](https://docs.dodopayments.com/features/customer-wallet.md) credit to the amount due.
* It fixes the reminder schedule for the invoice.

If the amount due is zero, the invoice becomes `paid` immediately. No payment method or payment link is necessary.

A custom due date must still be in the future when you finalize. If it is not, select a new due date.

## Collecting Payment

### Auto-Charge

An auto-charge invoice charges the customer's saved card on the due date.

* If the charge on the due date fails, the invoice becomes `past_due`. If you turned on [Subscription Payment Retries](https://docs.dodopayments.com/features/recovery/payment-retries.md), Dodo Payments then retries the charge on your retry schedule. A hard decline stops the retries until the customer adds a new card.
* If the customer has no saved card on the due date, the invoice becomes `past_due`. When the customer saves a card later, Dodo Payments charges it at once. If that charge fails, retries follow your schedule.
* To charge the saved card again before the next scheduled attempt, use the [Retry Invoice API](https://docs.dodopayments.com/api-reference/invoices/retry-invoice.md). The invoice must be `open` or `past_due`, use auto-charge, and have a saved card, and its subscription must not be cancelled. You cannot retry while a payment is processing or while dunning is paused.

### Manual Collection

A manual invoice is not charged automatically. The customer pays on the hosted invoice page. If the customer does not pay by the due date, the invoice becomes `past_due`.

### Reminder Emails

Each invoice follows your business reminder schedule. Dodo Payments fixes that schedule on the invoice when you finalize it. If your business has no reminder schedule, no reminders are sent. Configure the schedule in **Settings → Recovery**. The **Configure** button next to **Dunning & Retries** on the invoice form opens that page. 

Reminders go out only for an invoice that you sent. A finalized invoice that you never send gets no reminders. On an auto-charge invoice with a saved card, only the reminders before the due date go out, because retries take the place of later reminders.

To change the schedule of one invoice, use the API:

* Send `dunning` when you create or update a draft, with `reminders_enabled` and `offsets_days`. Each offset is a number of days from the due date. A negative offset sends the reminder before the due date.
* Send `pause`, `resume`, or `reschedule` to the dunning endpoint of an open or past-due invoice. A paused invoice gets no reminders, no retries, and no automatic write-off.

### The Hosted Invoice Page

The hosted invoice page lets the customer pay without a login. It shows the amount due, the due date, the line items, and the totals. The customer can pay the amount due and download the invoice PDF. After a refund, the page also links to the refund receipt.

![A hosted invoice page with the amount due, a Pay button, the invoice number, the line items, and a Download PDF button](https://mintcdn.com/dodopayments/aP958i30jx5nBLqD/images/invoice-based-billing/hosted-invoice-page.png?fit=max\&auto=format\&n=aP958i30jx5nBLqD\&q=85\&s=df460e29f88693719e9346c6c6b6b2b1)

To get the link, use one of these methods:

* In the dashboard, copy the link from the invoice details page, or click **Copy Link** on the invoice in the list.
* In the API, read `hosted_url` on a sent invoice, or call the hosted link endpoint.

Getting the link counts as sending the invoice. Draft, void, and uncollectable invoices have no new link. The link stays valid while the invoice is open, past due, or paid. If you void the invoice or mark it uncollectable, a link that you already sent opens a read-only page until it expires.

When the invoice has a subscription item, the payment saves the customer's card for later renewals.

### Emails to the Customer

Dodo Payments sends these emails to the customer:

| Email | When |
| - | - |
| Invoice | You send the invoice, or Dodo Payments sends a renewal invoice. |
| Reminder | A reminder on the invoice schedule is due. |
| Card needed | An auto-charge invoice reaches a reminder time before its due date, and the customer has no saved card. |
| Payment confirmation | The payment succeeds. |
| Payment failed | An automatic charge fails. |
| Due date updated | You change the due date of a sent, unpaid invoice. |
| Invoice voided | You void the invoice. |

Every email except the void email has a link to the hosted invoice page. The void email goes only to the customer email of a sent invoice.

You also get emails when a renewal draft is ready for review, and when an invoice is sent, paid, past due, voided, has a failed payment, or reaches the end of dunning.

## Managing Invoices

![The Invoice Details page for an open invoice, with the hosted page link, Edit and More Actions buttons, the summary, and the activity log](https://mintcdn.com/dodopayments/aP958i30jx5nBLqD/images/invoice-based-billing/invoice-details.png?fit=max\&auto=format\&n=aP958i30jx5nBLqD\&q=85\&s=73db7655984bc292f62ee7a2d56e1394)

The invoice details page shows the summary, the line items, the payments, the subscriptions that the invoice bills, the refunds in **Credit Notes**, and an **Activity Log** of every action. Click **Add Note** to add an internal note to the activity log.

### Editing an Invoice

What you can edit depends on the status:

| Status | Editable fields |
| - | - |
| `draft` | All fields |
| `open` | Due date, collection method, recipients, and metadata |
| `past_due` | Due date, recipients, and metadata |
| `paid`, `void`, `uncollectable` | Metadata only |

A new due date must be in the future. If you move the due date of a `past_due` invoice to the future, the invoice becomes `open` again. If the invoice was sent, the customer gets an email with the new due date.

To correct an amount, an item, the currency, the customer, or the tax ID on an issued invoice, void the invoice and create a new one.

### Voiding an Invoice

To void an invoice, open it, click **More Actions**, then **Update Status**, select **Mark as Void**, and click **Continue**.

![The Update Invoice Status dialog with the Mark as Void option](https://mintcdn.com/dodopayments/aP958i30jx5nBLqD/images/invoice-based-billing/update-status.png?fit=max\&auto=format\&n=aP958i30jx5nBLqD\&q=85\&s=f3e80fff392605111d065e75cec8b0d6)

* You can void only an `open` or `past_due` invoice. To remove a draft, delete it.
* You cannot void an invoice while a payment is processing.
* Wallet credit applied to the invoice goes back to the customer's wallet.
* The hosted page and the PDF stay available, without a payment button.
* If the invoice is the first invoice of a subscription, the subscription fails.

### Marking an Invoice Uncollectable

When dunning of a `past_due` invoice ends, you get an email. You then have 7 days to extend the due date, void the invoice, or mark it uncollectable. If you do nothing, Dodo Payments marks the invoice `uncollectable` after 7 days.

Dunning ends at these times:

* **Manual collection:** at the due date plus the recovery window of your [Payment Retries](https://docs.dodopayments.com/features/recovery/payment-retries.md) settings. With no retry settings, dunning ends at the due date.
* **Auto-charge:** at the last failed retry.

If you pause dunning, the automatic write-off does not happen. Wallet credit applied to the invoice stays applied when the invoice becomes uncollectable.

To mark it yourself, open the invoice, click **More Actions**, then **Update Status**, and select **Mark as Uncollectable**. Only a `past_due` invoice can be marked uncollectable.

### Late Payments

If a payment succeeds on a `void` or `uncollectable` invoice, Dodo Payments refunds the full payment automatically. The invoice keeps its status. A second payment on a `paid` invoice is also refunded.

### Duplicating an Invoice

To create a new draft with the same details, click **Duplicate Invoice** on the invoice in the list. The copy does not keep a custom due date, the manual review setting, or usage lines. You cannot duplicate a renewal invoice or a plan change invoice.

## Recurring Invoices

When an invoice has a subscription item, it starts a subscription that invoices bill. Dodo Payments creates the subscription with the draft, in the `pending` status. The subscription becomes `active` when the customer pays the first invoice. If you delete the draft, or void the first invoice, or it becomes uncollectable, the subscription fails.

On each next billing date, Dodo Payments creates a renewal invoice with the same payment terms and collection method. If the first invoice used a custom due date, renewal invoices are due on receipt. For a usage-based subscription, the renewal invoice comes 1 hour after the billing date, so that late usage events count.

The renewal invoice controls the subscription status:

* If a renewal or plan change invoice becomes `past_due`, the subscription enters its [grace period](https://docs.dodopayments.com/features/subscription.md#grace-period), or goes `on_hold` if you have no grace period.
* When the customer pays, the subscription becomes `active` again.
* An `on_hold` subscription gets no new renewal invoice until the customer pays.

An invoice with more than one subscription cannot have one-time items. All items must use the invoice currency.

These subscription actions are not available when invoices bill the subscription: pause, on-demand charges, a change of the next billing date, and `collect_via_payment_link` on a plan change.

### Free Trials

An invoice-billed subscription can start with a free trial. Dodo Payments creates the subscription and a paid \$0 invoice for the trial. The first invoice that bills an amount comes when the trial ends.

**1. Add one subscription product**

In **Create Invoice**, select the customer and add one subscription product. The trial is available only with one product, no add-ons, no other items, and no discount.

**2. Turn on the trial**

Turn on **Start with a free trial**. **Trial days** shows the trial length of the product. You can set 1 to 730 days.

**3. Set the terms after the trial**

Select the payment terms and the collection method for the invoices after the trial. For **Auto-charge**, select a saved card. Discounts, reminders, and metadata do not apply to a trial.

**4. Start the trial**

Click **Start Trial**, check the details in the dialog, and click **Start Trial** again.

If a product has a trial and you do not turn on **Start with a free trial**, the invoice bills the full price now. The form shows a warning.

* [Preventing Trial Misuse](https://docs.dodopayments.com/features/subscription.md#preventing-trial-misuse) applies only when you keep the trial length of the product. A custom length skips the check.
* The customer gets a reminder email before the trial ends.
* You cannot change the plan during the trial.
* Paid trials are not available.
* With the API, send `POST /billing/subscriptions`. Set `trial_period_days` to change the trial length. For auto-charge, send `payment_method_id`.

### Reviewing Renewal Invoices

With **Manual review** on, each renewal invoice is saved as a draft. You get an email when the draft is ready. You have 72 hours after the billing date to review and send it. If you do not, Dodo Payments finalizes the draft and sends it to the customer automatically.

You can change the due date, the collection method, the recipients, the reminders, and the metadata of a renewal draft. You cannot change its prices or items.

### Changing Plans

Change the plan of an invoice-billed subscription from the dashboard or with the [Change Plan API](https://docs.dodopayments.com/api-reference/subscriptions/change-plan.md). The proration uses the same [proration modes](https://docs.dodopayments.com/features/subscription.md#proration-modes) as other subscriptions.

* **Change now:** Dodo Payments creates a plan change invoice. A positive total is an amount due. Use the `invoice` object to set its `payment_terms` and `collection_method`. They default to the subscription values. To review the invoice before it is issued, set `invoice.finalize` to `false`. If you do not finalize the draft in 72 hours, Dodo Payments finalizes it.
* **Change at the next billing date:** nothing is billed now. The next renewal invoice bills the new plan.
* **Downgrade credit:** set `credit` to `customer_balance` (default) to add the credit to the customer's wallet, or to `refund` to refund it to the last paid payment. The credit goes to the wallet if there is no paid payment, if the last payment uses a different currency, or if the refund fails.

You cannot change the plan while an earlier plan change invoice is unpaid. Pay, void, or delete that invoice first.

Customers cannot change the plan of an invoice-billed subscription from the [Customer Portal](https://docs.dodopayments.com/features/customer-portal.md).

### Cancelling a Subscription

* **Cancel now:** the subscription becomes `cancelled`, and renewal drafts are deleted. Open invoices stay open, and the customer can still pay them. Auto-charge stops.
* **Cancel at the next billing date:** no renewal invoice is created, and the subscription ends at the billing date.

To cancel a `pending` subscription, void its first invoice.

## Refunds and Disputes

Refund an invoice payment from the payment, the same as any other payment. On the invoice details page, click **More Actions**, then **Refund via Payment**. See [Refunds](https://docs.dodopayments.com/features/transactions/refunds.md). A refund does not change the invoice status. It adds the `refunded` or `partially_refunded` tag and a refund receipt.

A dispute on an invoice payment adds the `disputed` tag. If the dispute is lost, accepted, or expires, the tag changes to `payment_reversed`. To bill the customer again, duplicate the invoice.

## Limits

These limits apply to each invoice:

| Item | Limit |
| - | - |
| Items per invoice | 1 to 50 |
| Quantity per item | 1 to 10,000 |
| Discount codes per invoice | 20 |
| CC recipients | 10 |
| Note | 2,000 characters |

## Webhooks

Dodo Payments sends these webhook events for invoices. See [Invoice Webhooks](https://docs.dodopayments.com/developer-resources/webhooks/intents/invoice.md) for the payload schema. The payload is the invoice object, the same as the response of `GET /billing/invoices/{id}`. It shows the invoice at the time of delivery, not at the time of the event.

| Event | Fires when |
| - | - |
| `invoice.finalized` | An invoice is finalized. |
| `invoice.sent` | You send an invoice, Dodo Payments sends a renewal invoice, or the hosted link is first created. |
| `invoice.paid` | An invoice is paid, including a \$0 invoice at finalize. |
| `invoice.payment_failed` | An automatic charge fails. |
| `invoice.past_due` | An invoice becomes past due. |
| `invoice.reopened` | A past-due invoice becomes open after a due date change. |
| `invoice.voided` | An invoice is voided. |
| `invoice.marked_uncollectable` | An invoice is marked uncollectable. |

Refunds and disputes on invoice payments send the usual [refund](https://docs.dodopayments.com/developer-resources/webhooks/intents/refund.md) and [dispute](https://docs.dodopayments.com/developer-resources/webhooks/intents/dispute.md) events.

## API Management

All invoice endpoints accept your API key. Each invoice response has an `ETag` header. Send its value in the `If-Match` header when you change the invoice. If the invoice changed after you read it, the request fails, and you must read the invoice again.

> [accordion] Create and Edit Invoices
>
> Create a draft, list and read invoices, update a draft, or delete it. Send an `Idempotency-Key` header on create to prevent duplicate drafts.
>
> > [card] [Create Invoice](https://docs.dodopayments.com/api-reference/invoices/create-invoice.md)
> >
> > Create a draft invoice.
>
> > [card] [List Invoices](https://docs.dodopayments.com/api-reference/invoices/list-invoices.md)
> >
> > List invoices with filters.
>
> > [card] [Get Invoice](https://docs.dodopayments.com/api-reference/invoices/get-invoice.md)
> >
> > Get one invoice with its lines and payments.
>
> > [card] [Update Invoice](https://docs.dodopayments.com/api-reference/invoices/update-invoice.md)
> >
> > Change the editable fields of an invoice.
>
> > [card] [Delete Invoice](https://docs.dodopayments.com/api-reference/invoices/delete-invoice.md)
> >
> > Delete a draft.
>
> > [card] [Duplicate Invoice](https://docs.dodopayments.com/api-reference/invoices/duplicate-invoice.md)
> >
> > Copy an invoice to a new draft.

> [accordion] Preview Invoices
>
> Show the PDF, the email, or the data of an invoice before you issue it.
>
> > [card] [Preview Invoice Request](https://docs.dodopayments.com/api-reference/invoices/preview-invoice-request.md)
> >
> > Preview an invoice without saving it.
>
> > [card] [Preview Invoice](https://docs.dodopayments.com/api-reference/invoices/preview-invoice.md)
> >
> > Preview a saved draft.
>
> > [card] [Get Upcoming Invoice](https://docs.dodopayments.com/api-reference/subscriptions/get-upcoming-invoice.md)
> >
> > Preview the next renewal invoice of a subscription.

> [accordion] Issue and Send Invoices
>
> Finalize a draft, email it, or get the hosted invoice page link. Send `"send": true` on finalize to also send the invoice.
>
> > [card] [Finalize Invoice](https://docs.dodopayments.com/api-reference/invoices/finalize-invoice.md)
> >
> > Issue a draft.
>
> > [card] [Send Invoice](https://docs.dodopayments.com/api-reference/invoices/send-invoice.md)
> >
> > Email the invoice to the customer.
>
> > [card] [Create Hosted Link](https://docs.dodopayments.com/api-reference/invoices/create-hosted-link.md)
> >
> > Get the hosted invoice page link.

> [accordion] Collect Payment
>
> Charge the saved card now, or pause, resume, or reschedule the reminders of an invoice.
>
> > [card] [Retry Invoice](https://docs.dodopayments.com/api-reference/invoices/retry-invoice.md)
> >
> > Charge the saved card of an auto-charge invoice.
>
> > [card] [Change Dunning](https://docs.dodopayments.com/api-reference/invoices/change-dunning.md)
> >
> > Pause, resume, or reschedule reminders.

> [accordion] Close Invoices
>
> Void an unpaid invoice, or write off a past-due invoice.
>
> > [card] [Void Invoice](https://docs.dodopayments.com/api-reference/invoices/void-invoice.md)
> >
> > Cancel an open or past-due invoice.
>
> > [card] [Mark Uncollectable](https://docs.dodopayments.com/api-reference/invoices/mark-uncollectable.md)
> >
> > Write off a past-due invoice.

> [accordion] Notes and History
>
> Add an internal note, or read every action on an invoice.
>
> > [card] [Add Note](https://docs.dodopayments.com/api-reference/invoices/add-note.md)
> >
> > Add a note to the activity log.
>
> > [card] [List Invoice Events](https://docs.dodopayments.com/api-reference/invoices/list-invoice-events.md)
> >
> > Get the event history of an invoice.

## Not Supported

These items are not available for invoice-based billing:

* Marking an invoice paid for a payment made outside Dodo Payments.
* Partial payments. The customer pays the full amount due.

> [card] [Subscriptions](https://docs.dodopayments.com/features/subscription.md)
>
> Learn how subscriptions, plan changes, and grace periods work.

> [card] [Webhook Events Guide](https://docs.dodopayments.com/developer-resources/webhooks/intents/webhook-events-guide.md)
>
> See every webhook event that Dodo Payments sends.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.