# Invoices

Generate an invoice to send to customers - request payments, track invoice status, and get paid all from one place.

Invoices are built directly into Moov's platform, so you can send professional, branded invoices to your customers and accept payments without relying on third‑party tools. With invoicing you can:

- Create detailed line items
- Automatically generate secure payment links
- Send directly to customers via email
- Accept one-time payments via bank transfer or card
- Manually mark invoices as paid for off-platform payments

When using the [invoice API](/api/v2026.04.00/money-movement/invoices/), provide the `customerAccountID` in the request to create an invoice. When a customer pays an invoice, funds are collected and deposited directly into the merchant's Moov wallet.

To create an invoice, use the `POST` create invoice [endpoint](/api/v2026.04.00/money-movement/invoices/post/). To send an invoice, use the `PATCH` update invoice [endpoint](/api/v2026.04.00/money-movement/invoices/patch/) and set the status to `unpaid`.

## [Invoice details](#invoice-details)

In addition to amount due, an invoice contains the following details:

| Component      | Description                                                                                         |
|----------------|-----------------------------------------------------------------------------------------------------|
| Invoice number | Automatically generated and sequential per account, for example, **INV‑1001**.                      |
| Invoice date   | The date the service or sale occurred. This can differ from when the invoice is sent.               |
| Due date       | When the payment is due to the merchant.                                                            |
| Description    | Optional notes shown to the customer, for example, job numbers or description of services provided. |

### [Line items](#line-items)

Each invoice includes one or more line items that describe what's being charged. Line items can be products from the account’s [product catalog](/guides/account-tools/product-catalog/), or free-from line items that support custom names, prices, and quantities.

When you use a `productID`, Moov attaches the associated product image from your catalog to the line item. You must still specify the `basePrice` for the line item, as the price from the product catalog is not used. You can also use the `productID` for your own reporting and tracking.

## [Invoice status](#invoice-status)

An invoice can be in any of the following stages: `draft`, `unpaid`, `payment-pending`, `paid`, `overdue`, or `canceled`. When an invoice is created but not sent, it becomes a draft. While in draft status, all fields in the invoice can be edited. An invoice must be explicitly sent to trigger the payment link and email notification. Once the invoice is sent, it is marked as unpaid.

Upon successful payment, a receipt will be sent to the customer and the merchant will be notified of payment via email. Additionally, a webhook notification is sent.

A failed payment will result in the invoice being re-sent to the payer via the same payment link to retry. The original failed payment is logged and shown to the payer in the invoice and the merchant is notified of the failed payment via email.

If an invoice is not paid by the due date and becomes overdue, Moov will notify the merchant via email.

If an invoice is canceled, the payment link will be disabled and will throw an error if interacted with: `This invoice has already been paid or is no longer valid.`

## [Payment links & transfer status](#payment-links--transfer-status)

When an invoice is sent, Moov automatically creates a secure payment link scoped to that invoice and customer. The payment link is a unique, **single-use payment link** which displays:

- Your business name and logo
- The [invoice details](#invoice-details)
- Total amount due

A transfer is created for record keeping. The `transferID` can be found in `invoicePayments.transfer` within the [create an invoice](/api/v2026.04.00/money-movement/invoices/post/) response. The table below shows the mapping of invoice status to payment link and transfer status.

| Invoice status    | Payment link status | Transfer status |
|-------------------|---------------------|-----------------|
| `draft`           | N/A                 | N/A             |
| `unpaid`          | `active`            | N/A             |
| `payment-pending` | `disabled`          | `pending`       |
| `paid`            | `disabled`          | `completed`     |
| `overdue`         | `active`            | N/A             |
| `canceled`        | `disabled`          | N/A             |

## [Email notifications](#email-notifications)

Invoices are attached to an email in PDF format and are sent in a variety of scenarios. Moov sends an email to the payer when the invoice status is updated to one of the following:

- Unpaid
- Paid (receipt)
- Overdue
- Payment failed
- Canceled

Additionally, an email is sent if the transaction has been refunded.

Moov sends an email to the merchant when an invoice status is updated to paid, or if it's manually marked as paid. Moov also notifies merchants if the invoice is overdue, or the payment transaction is disputed.

If a logo has been added to the merchant's settings, the logo will be automatically added to the email. Below is an example of an email someone will receive for a payment request.

![Invoice email](../images/invoice_due_email.png)

## [Create and manage invoices](#create-and-manage-invoices)

Follow the steps below to create and manage invoices via the [invoice API](/api/v2026.04.00/money-movement/invoices/). Most of the endpoints in the invoice API will require you to pass the `invoiceID` which is returned in the [create an invoice](/api/v2026.04.00/money-movement/invoices/post/) response.

### [Create invoice](#create-invoice)

Use the `POST` create invoice [endpoint](/api/v2026.04.00/money-movement/invoices/post/) to create an invoice. You'll need to send the `customerAccountID` in the request body as well as create at least one line item.

```zsh
curl -X POST "https://api.moov.io/accounts/{accountID}/invoices" \
  -H "Authorization: Bearer {token}" \
  -H "x-moov-version: v2026.04.00" \
  --data '{
    "customerAccountID": "d8b40343-5784-4096-8d40-9f3b4a834066",
    "description": "string",
    "lineItems": {
      "items": [
        {
          "name": "string",
          "basePrice": {
            "currency": "USD",
            "valueDecimal": "12.987654321"
          },
          "quantity": 1,
          "options": [
            {
              "name": "string",
              "quantity": 1,
              "priceModifier": {
                "currency": "USD",
                "valueDecimal": "12.987654321"
              },
              "group": "string"
            }
          ],
          "productID": "dbb08e34-cbbb-47d7-824b-bc71f5b00e6c"
        }
      ]
    },
    "dueDate": "2025-08-24T14:15:22Z",
    "invoiceDate": "2025-08-24T14:15:22Z",
    "taxAmount": {
      "currency": "USD",
      "valueDecimal": "12.987654321"
    }
  }'\
```

### [Optional: Update invoice](#optional-update-invoice)

Use the `PATCH` update invoice [endpoint](/api/v2026.04.00/money-movement/invoices/patch/) to update an invoice's line items, tax amount, due date, invoice date, description, or status. Only invoices in the `draft`, `unpaid` or `overdue` status can be updated and the `dueDate` can only be updated if the invoice status is `draft`.

Note that setting an invoice's status to `unpaid` finalizes the invoice and sends an email with a payment link to the customer.

```zsh
curl -X PATCH "https://api.moov.io/accounts/{accountID}/invoices/{invoiceID}" \
  -H "Authorization: Bearer {token}" \
  -H "x-moov-version: v2026.04.00" \
  --data '{
    "description": "string",
    "lineItems": {
      "items": [
        {
          "name": "string",
          "basePrice": {
            "currency": "USD",
            "valueDecimal": "13.987654321"
          },
          "quantity": 2,
          "options": [
            {
              "name": "string",
              "quantity": 1,
              "priceModifier": {
                "currency": "USD",
                "valueDecimal": "1.00"
              },
              "group": "string"
            }
          ],
          "productID": "dbb08e34-cbbb-47d7-824b-bc71f5b00e6c"
        }
      ]
    },
    "dueDate": "2025-08-24T14:15:22Z",
    "invoiceDate": "2025-08-24T14:15:22Z",
    "status": "draft",
    "taxAmount": {
      "currency": "USD",
      "valueDecimal": "12.987654321"
    }
  }'\
```

### [Send invoice](#send-invoice)

To send an invoice, you'll use the same `PATCH` update invoice [endpoint](/api/v2026.04.00/money-movement/invoices/patch/) as mentioned in the previous step. To send an invoice, set the status to `unpaid`. Setting an invoice's status to `unpaid` finalizes the invoice and sends an email with a payment link to the customer.

```
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
```

```zsh
curl -X PATCH "https://api.moov.io/accounts/{accountID}/invoices/{invoiceID}" \
  -H "Authorization: Bearer {token}" \
  -H "x-moov-version: v2026.04.00" \
  --data '{
    "description": "string",
    "lineItems": {
      "items": [
        {
          "name": "string",
          "basePrice": {
            "currency": "USD",
            "valueDecimal": "13.987654321"
          },
          "quantity": 1,
          "productID": "dbb08e34-cbbb-47d7-824b-bc71f5b00e6c"
        }
      ]
    },
    "dueDate": "2025-08-24T14:15:22Z",
    "invoiceDate": "2025-08-24T14:15:22Z",
    "status": "unpaid",
    "taxAmount": {
      "currency": "USD",
      "valueDecimal": "12.987654321"
    }
  }'
```

### [Get invoices](#get-invoices)

Use the `invoiceID` to view a specific invoice, or retrieve a list of all invoices.

[Get invoice](#tab-945813267-0-0) [List invoices](#tab-945813267-0-1)

Use the `GET` retrieve invoice [endpoint](/api/v2026.04.00/money-movement/invoices/get/) and pass the `invoiceID`.

```zsh
curl -X GET "https://api.moov.io/accounts/{accountID}/invoices/{invoiceID}" \
  -H "Authorization: Bearer {token}" \
  -H "x-moov-version: v2026.04.00" \
```

Use the `GET` list invoices [endpoint](/api/v2026.04.00/money-movement/invoices/list/).

```zsh
curl -X GET "https://api.moov.io/accounts/{accountID}/invoices" \
  -H "Authorization: Bearer {token}" \
  -H "x-moov-version: v2026.04.00" \
```

### [Optional: Manually mark as paid](#optional-manually-mark-as-paid)

Create an external payment invoice resource and mark an invoice as paid outside of Moov's system with the payment resource [endpoint](/api/v2026.04.00/money-movement/invoices/post-payments/).

```zsh
curl -X POST "/accounts/{accountID}/invoices/{invoiceID}/payments" \
  -H "Authorization: Bearer {token}" \
  -H "x-moov-version: v2026.04.00" \
  --data '{
    "amount": {
      "currency": "USD",
      "valueDecimal": "12.987654321"
    },
    "description": "string",
    "foreignID": "d8b40343-5784-4096-8d40-9f3b4a834066",
    "paymentDate": "2025-08-24T14:15:22Z"
  }'\
```

Note - invoices that are paid via payment link will be automatically marked as paid.

### [List payments](#list-payments)

Pass the `invoiceID` to retrieve all payments made toward an invoice with the `GET` payments [endpoint](/api/v2026.04.00/money-movement/invoices/get-payments/).

```zsh
curl -X GET "/accounts/{accountID}/invoices/{invoiceID}/payments" \
  -H "Authorization: Bearer {token}" \
  -H "x-moov-version: v2026.04.00" \
```

## [Receive funds](#receive-funds)

Once the transfer completes, the invoice is marked as paid and the funds are available in the senders wallet.

### [Manually mark as paid](#manually-mark-as-paid)

Invoices that are paid via payment link will be automatically marked as paid, however, you can manually mark an invoice as paid with the `POST` payment resource [endpoint](/api/v2026.04.00/money-movement/invoices/post-payments/). Manually marking an invoice as paid notifies the merchant via email, sends a receipt to the customer, and cancels the corresponding payment link. Additionally, a webhook event is sent and a `foreignID` is added to the invoice.

You can only mark an invoice as paid if the status is `unpaid` or `overdue`.

```zsh
curl -X POST "/accounts/{accountID}/invoices/{invoiceID}/payments" \
  -H "Authorization: Bearer {token}" \
  -H "x-moov-version: v2026.04.00" \
  --data '{
    "amount": {
      "currency": "USD",
      "valueDecimal": "12.987654321"
    },
    "description": "string",
    "foreignID": "d8b40343-5784-4096-8d40-9f3b4a834066",
    "paymentDate": "2025-08-24T14:15:22Z"
  }'\
```

## [Payment failures & refunds](#payment-failures--refunds)

If a payment attempt fails, the invoice will automatically return to an `unpaid` status. The original payment link remains active, allowing the customer to retry the payment using the same link.

If a payment is refunded or disputed, the invoice will continue to show a `paid` status. Any refunded or disputed amounts are reflected directly on the invoice so you can see how much has been returned. [Refunds](/guides/money-movement/accept-payments/card-acceptance/reversals/) and [disputes](/guides/money-movement/accept-payments/card-acceptance/disputes/) follow Moov’s standard payment flow, meaning the refunded or disputed amount is deducted from the account’s wallet.

## [Delete an invoice](#delete-an-invoice)

In a scenario where an invoice was accidentally or mistakenly created, you can delete it using the delete invoice [endpoint](/api/v2026.04.00/money-movement/invoices/delete/). Deleted invoices will be hidden from results lists by default, but can still be retrieved through the get invoice [endpoint](/api/v2026.04.00/money-movement/invoices/get/).

If you need to void an invoice that was already sent or recorded, cancel it instead by updating its status to `canceled` with the update invoice [endpoint](/api/v2026.04.00/money-movement/invoices/patch/).

Only invoices in a `draft` status can be deleted.

## [Webhooks](#webhooks)

Subscribe to the following [webhook events](/guides/webhooks/webhook-events/#invoices), which will provide you with relevant invoice updates:

- `invoice.created` notifies you when an invoice was successfully created
- `invoice.updated` notifies you when an invoice was updated