# Invoices

An invoice represents a billed amount a merchant sends to a customer for payment.

An invoice lets the merchant establish the amount owed first.
The customer can act on it separately.
The customer reviews an itemized total.
Then the customer pays by card or ACH, on their own schedule.

This is in contrast to a normal collection, where an amount is received immediately at the point of sale.
A direct transaction captures a customer's card or bank details right away.

This guide covers building invoicing into a business application with Flute's Invoices API.
It covers creating an invoice and associating it with a customer.
It also covers delivering the invoice to the customer.
Finally, it covers tracking payment status and modifying or canceling invoices.

The following steps are available:

* Creating an Invoice
* Adding Line Items
* Checking Invoice Defaults
* Publishing an Invoice
* Tracking Invoices and Status Updates
* Editing Invoices
* Canceling Invoices
* Deleting Invoices


## Creating an Invoice

[TOC](#following-steps) | [Next](#adding-line-items)

Creating an invoice requires the customer being billed and the line items that make up the charge.

To create an invoice, use: 
[`POST /pay-int-api/invoices`](/api-reference/invoices/flute-v1-post-pay-int-api-invoices)

Some request fields are also stored as the default.
For details of these values, see [Checking Invoice Defaults](#checking-invoice-defaults).

The following example represents a common request.

```json
{
    "customerId": "fd9198a4-eb6f-4620-9603-4f4638289de5",
    "merchantContactInfoId": "bdf4b5c6-7d8e-4f9a-0b1c-2d3e4f5a6b92",
    "additionalNotes": "Extension permitted for 30 days.",
    "lineItems": 
    [
        {
            "lineItemId": "b2c1d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d69",
            "unitTypeId": 1,
            "quantity": 3
        },
        {
            "lineItemId": "c3d2e5f6-7a8b-4c9d-0e1f-2a3b4c5d6e70",
            "unitTypeId": 1,
            "quantity": 1,
            "unitPrice": 15.00
        }
    ]
}
```

This request includes two line items.
For more information about line items, see [Adding Line Items](#adding-line-items).

An invoice bills a specific customer.
Passing `customerId` bills an existing customer record.

Not passing `customerId` works differently.
Supply the customer's details instead.
Flute then creates a new customer record from that information.
It attaches the new record to the invoice.

The following is an example of not including a `customerId`.

```json
"customer": {
    "name": "Jordan Alvarez",
    "email": "jordan.alvarez@example.com",
    "phone": "+15551234567",
    "billingAddress": {
      "line1": "482 Birchwood Ave",
      "city": "Austin",
      "state": "TX",
      "postalCode": "78701",
      "country": "US"
    }
}
...
  "merchantContactInfoId": "bdf4b5c6-7d8e-4f9a-0b1c-2d3e4f5a6b92"
```

The invoice also carries `merchantContactInfoId`.
This identifies which of the merchant's own stored contact records appears on the invoice.
That record holds the address, phone, and similar details for the biller.

The response only includes the `id` field, also called the invoiceId.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

Specific information is retrieved from [`GET /pay-int-api/invoices/{{invoiceId}}`](/api-reference/invoices/flute-v1-get-pay-int-api-invoices-invoiceid).
This includes identifiers and totals Flute calculates based on the `lineItems` listing.
The following is an example from that call.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "number": "INV-1042",
  "status": 1,
  "subTotalAmount": 3219.45,
  "totalAmount": 3219.45,
  "merchantId": "46063d32-10fa-44cb-b118-20ddd085ce3f",
  "customerId": "fd9198a4-eb6f-4620-9603-4f4638289de5",
  "dueDate": "2026-09-15"
}
```

The `id` field is the invoice identifier.

All invoices begin in the `Draft` (1) status.
While an invoice is in `Draft`, it can be freely edited or deleted.
Editing uses [`PUT /pay-int-api/invoices/{invoiceId}`](/api-reference/invoices/flute-v1-put-pay-int-api-invoices-invoiceid). 
Deleting uses [`DELETE /pay-int-api/invoices/{invoiceId}`](/api-reference/invoices/flute-v1-delete-pay-int-api-invoices-invoiceid).

Nothing has been sent to the customer yet, so nothing is locked.
That changes once the invoice is published.
For details of publishing an invoice, see [Publishing an Invoice](#publishing-an-invoice).

## Adding Line Items

[TOC](#following-steps) | [Previous](#creating-an-invoice) | [Next](#checking-invoice-defaults)

A line item is a single billable product or service on an invoice.
An invoice's total is built from one or more line items.

Line items come from a separate catalog or source.
Each catalog entry has a name, description, SKU, unit price, unit type, and tax rate.
Building a line items catalog lets the merchant reuse existing items, rather than re-entering them on each invoice.
A line item can reference an existing catalog entry by the `lineItemId` field.
It can optionally belong to a category to help organize the catalog.

This applies equally to creating an invoice and editing a draft one.
Both [`POST /pay-int-api/invoices`](/api-reference/invoices/flute-v1-post-pay-int-api-invoices) and [`PUT /pay-int-api/invoices/{invoiceId}`](/api-reference/invoices/flute-v1-put-pay-int-api-invoices-invoiceid) accept a `lineItems` array.
See the code example below.

```json
{
  "customerId": "fd9198a4-eb6f-4620-9603-4f4638289de5",
  "dueDate": "2026-09-15",
  "lineItems":
  [
    {
      "lineItemId": "b2c1d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d69", // Adding a predefined line item
      "quantity": 3,
      "unitTypeId": 1
    },
    {
      "lineItemId": "c3d2e5f6-7a8b-4c9d-0e1f-2a3b4c5d6e70", // Adding a predefined line item...
      "unitPrice": 15.00,                                   // ...but overriding the predefined price
      "quantity": 1,
      "unitTypeId": 1
    }
  ]
}
```

In this example:
The first entry bills three units of a catalog item at its stored price. 
The second overrides that catalog item's price for this invoice only. 
This option is available only if `canOverWriteInvoiceLineItemPrice` is `true`.
This value can be verified using [`GET /pay-int-api/merchants/{{merchantId}}/invoices/settings`](/api-reference/invoices-settings/flute-v1-get-pay-int-api-merchants-merchantid-invoices-settings). 
It can be set with [`PUT /pay-int-api/merchants/{{merchantId}}/invoices/settings`](/api-reference/invoices-settings/flute-v1-put-pay-int-api-merchants-merchantid-invoices-settings).

## Checking Invoice Defaults

[TOC](#following-steps) | [Previous](#adding-line-items) | [Next](#publishing-an-invoice)

Creating an invoice uses some fields that are also stored as defaults.

Those defaults live at the merchant level, separate from any individual invoice.
[`GET /pay-int-api/merchants/{merchantId}/invoices/settings`](/api-reference/invoices-settings/flute-v1-get-pay-int-api-merchants-merchantid-invoices-settings) retrieves them.
This includes the default number of days until an invoice is due, `dueDateAfterDays`.
It also includes whether tax, discount, shipping, and processing fees are enabled, and at what rate.
It includes the merchant's chosen payment method type and processors.
It includes staff permissions, such as whether a team member can override a line item's price.
It also covers whether a team member can manually enter line items.
Use: 
[`PUT /pay-int-api/merchants/{merchantId}/invoices/settings`](/api-reference/invoices-settings/flute-v1-put-pay-int-api-merchants-merchantid-invoices-settings) 
This updates the full set.
This replaces the whole settings object.
The request must resend every field, not just the ones changing.

## Publishing an Invoice

[TOC](#following-steps) | [Previous](#checking-invoice-defaults) | [Next](#tracking-invoices-and-status-updates)

Publishing is what makes an invoice real for the customer.
Use: 
[`POST /pay-int-api/invoices/publish`](/api-reference/invoices/flute-v1-post-pay-int-api-invoices-publish).

The following example represents a common request.
The `invoiceId` is the `id` returned from creating the invoice.

```json
{
    "invoiceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

This moves its status from `Draft` (`1`) to `Published` (`2`).
From that point, the invoice can no longer be edited or deleted.

Publishing alone doesn't notify anyone.
Delivery is a separate, explicit step. 
Use [`POST /pay-int-api/invoices/{invoiceId}/send-email-notification`](/api-reference/invoices/flute-v1-post-pay-int-api-invoices-invoiceid-send-email-notification) to email the customer a link to review and pay the invoice. 
Use [`POST /pay-int-api/invoices/{invoiceId}/send-published-sms-notification`](/api-reference/invoices/flute-v1-post-pay-int-api-invoices-invoiceid-send-published-sms-notification) to send the customer an SMS text message with a link to review and pay the invoice.

The merchant's invoice settings also control automatic notifications after a payment attempt.
These are independent of the merchant-triggered sends above.
`isSmsNotificationAfterPaymentEnabled` and `isSmsNotificationAfterPaymentFailedEnabled` control these automatic texts.
They toggle whether the customer gets a text when payment succeeds or fails.

Every invoice also carries `fullUrl` and `shortUrl`.
These are generated by Flute and are the hosted page the customer opens to pay.
An application can link to either directly.
This can be instead of, or in addition to, Flute's built-in notifications.

Some cases call for a document rather than a link.
One example is attaching the invoice to an existing email or filing system.
[`GET /pay-int-api/invoices/{invoiceId}/download-pdf`](/api-reference/invoices/flute-v1-get-pay-int-api-invoices-invoiceid-download-pdf) returns a PDF copy for these cases.

## Tracking Invoices and Status Updates

[TOC](#following-steps) | [Previous](#publishing-an-invoice) | [Next](#editing-invoices)

An invoice's `status` field indicates where it stands in its lifecycle.
It only moves in the directions the API defines:

| Value | Status | Meaning |
|  --- | --- | --- |
| 1 | Draft | The invoice has been created but not yet published, and it's still fully editable. |
| 2 | Published | The invoice has been sent to the customer, and it can no longer be deleted. |
| 3 | Paid | The invoice's payment has been collected. |
| 4 | Expired | The invoice passed its due date without payment. |
| 5 | Canceled | The merchant canceled a published, unpaid invoice. |
| 6 | ProcessingPayment | The ACH invoice's payment submission is in progress. |
| 7 | Refunded | A paid invoice was refunded. |


Once an invoice is `Published`, payment is collected by submitting it.

[`POST /pay-int-api/invoices/{invoiceId}/submit`](/api-reference/invoices/flute-v1-post-pay-int-api-invoices-invoiceid-submit) submits a card payment. 
Upon successful payment, the status becomes `Paid`.

[`POST /pay-int-api/invoices/{invoiceId}/ach/submit`](/api-reference/invoices/flute-v1-post-pay-int-api-invoices-invoiceid-ach-submit) submits an ACH payment. 
The ACH clearing process sets the status to `ProcessingPayment` first.
If the payment is successful, the status becomes `Paid`.
However, an ACH payment may also be declined or fail, which reverts it to `Published`.
In addition, it may also become `Refunded`.

Ultimately, the intent is to move the invoice to `Paid`.

Sometimes payment happens outside the API entirely.
One example is a check received in person.
A check received in person doesn't flow through the invoice payment API.
There is no card or ACH transaction to process.
Instead, it's handled with [`PUT /pay-int-api/invoices/{{invoiceId}}/mark-as-paid`](/api-reference/invoices/flute-v1-put-pay-int-api-invoices-invoiceid-mark-as-paid).
This distinguishes it from a payment collected through Flute.
This endpoint moves the invoice directly to `Paid` without processing any payment.
It only works on invoices currently marked as `Published`.
This implies the invoice is due or past due and that it is not already paid.

[`GET /pay-int-api/invoices/{invoiceId}/calculations`](/api-reference/invoices/flute-v1-get-pay-int-api-invoices-invoiceid-calculations) recomputes an invoice's totals on demand.
This is useful for confirming the final amount before submitting payment.
Sometimes it helps to check status across many invoices at once. 
[`GET /pay-int-api/invoices`](/api-reference/invoices/flute-v1-get-pay-int-api-invoices) lists a merchant's invoices for this. 
It supports filtering by the query parameters the endpoint accepts.
Flute also keeps a `history` on each invoice.
This records the events the invoice has passed through.
It's returned as part of the invoice detail from [`GET /pay-int-api/invoices/{invoiceId}`](/api-reference/invoices/flute-v1-get-pay-int-api-invoices-invoiceid).

## Editing Invoices

[TOC](#following-steps) | [Previous](#tracking-invoices-and-status-updates) | [Next](#canceling-invoices)

Existing invoices can be edited but only while they are in `Draft` status.

Once an invoice is published, it can no longer be edited.
To edit an invoice, use: 
[`PUT /pay-int-api/invoices/{invoiceId}`](/api-reference/invoices/flute-v1-put-pay-int-api-invoices-invoiceid).

This endpoint updates the invoice's customer, line items, and payment terms.
The request must include the invoice's complete set of fields, not just the ones that changed.
This holds true even when only one field needs to change.
Leaving out a field can clear or overwrite its existing value.
Sending the full invoice each time helps avoid accidental data loss.

A published invoice can be canceled, but it cannot be edited or deleted.
To change a published invoice, cancel it and create a new invoice with the correct details.

## Canceling Invoices

[TOC](#following-steps) | [Previous](#editing-invoices) | [Next](#deleting-invoices)

Existing invoices can be canceled, but only while they are in `Published` status and still unpaid.

This applies whether or not the invoice is already past its due date.
Canceling an invoice moves it to `Canceled` status.
A paid invoice cannot be canceled.

To cancel an invoice, use: 
[`PUT /pay-int-api/invoices/{invoiceId}/cancel`](/api-reference/invoices/flute-v1-put-pay-int-api-invoices-invoiceid-cancel) 
This moves it to the `Canceled` status.

Once canceled, an invoice cannot be reopened or paid again.

To reverse a payment, refund the transaction the invoice produced instead.
The invoice itself is not canceled, only the payment is refunded.
To refund payments:

* For a card-paid invoice, see [`POST /pay-api/v1/transactions/return`](/api-reference/transactions/pay_api_v1_transactions_return)
* For an ACH-paid invoice, see [`POST /pay-api/v1/transactions/ach/{transactionId}/refund`](/api-reference/ach-transactions/flute-v1-post-pay-api-transactions-ach-id-refund)


## Deleting Invoices

[TOC](#following-steps) | [Previous](#canceling-invoices) | [Next](#endpoint-reference)

Existing invoices can be deleted but only while they are in `Draft` status.

Deleting an invoice permanently removes it from the merchant's records.
To delete an invoice, use: 
[`DELETE /pay-int-api/invoices/{invoiceId}`](/api-reference/invoices/flute-v1-delete-pay-int-api-invoices-invoiceid) 
A successful call confirms the invoice was deleted.
This action cannot be undone.

Once an invoice is in `Published` status, it can no longer be deleted.
To stop a published invoice, cancel it instead.

## Endpoint Reference

[TOC](#following-steps) | [Previous](#deleting-invoices)

This section lists every endpoint covered in this guide.
For detailed information about each endpoint, see [Invoices API Reference](/api-reference/invoices)

| Explanation | Method | Endpoint |
|  --- | --- | --- |
| Retrieves the merchant's invoice settings, including defaults like due-date offset, tax/discount/shipping options, and line-item permissions. | GET | [`/pay-int-api/merchants/{merchantId}/invoices/settings`](/api-reference/invoices-settings/flute-v1-get-pay-int-api-merchants-merchantid-invoices-settings) |
| Lists invoices for the current merchant, filterable by query parameters — useful for tracking status across many invoices at once. | GET | [`/pay-int-api/invoices`](/api-reference/invoices/flute-v1-get-pay-int-api-invoices) |
| Updates the merchant's invoice settings. Replaces the full settings object, so every field must be resent. | PUT | [`/pay-int-api/merchants/{merchantId}/invoices/settings`](/api-reference/invoices-settings/flute-v1-put-pay-int-api-merchants-merchantid-invoices-settings) |
| Creates a new invoice in `Draft` status, including its customer and line items. | POST | [`/pay-int-api/invoices`](/api-reference/invoices/flute-v1-post-pay-int-api-invoices) |
| Retrieves a single invoice's details. | GET | [`/pay-int-api/invoices/{invoiceId}`](/api-reference/invoices/flute-v1-get-pay-int-api-invoices-invoiceid) |
| Updates a draft invoice's customer, line items, or terms. Requires resending the invoice's complete set of fields. | PUT | [`/pay-int-api/invoices/{invoiceId}`](/api-reference/invoices/flute-v1-put-pay-int-api-invoices-invoiceid) |
| Deletes a draft invoice outright. Only works while the invoice is still in `Draft`. | DELETE | [`/pay-int-api/invoices/{invoiceId}`](/api-reference/invoices/flute-v1-delete-pay-int-api-invoices-invoiceid) |
| Retrieves the invoice's calculated totals, useful for confirming the final amount before publishing or submitting payment. | GET | [`/pay-int-api/invoices/{invoiceId}/calculations`](/api-reference/invoices/flute-v1-get-pay-int-api-invoices-invoiceid-calculations) |
| Publishes an invoice, moving it from `Draft` to `Published` and locking it from further edits or deletion. | POST | [`/pay-int-api/invoices/publish`](/api-reference/invoices/flute-v1-post-pay-int-api-invoices-publish) |
| Sends the invoice to the customer by email with a link to review and pay it. | POST | [`/pay-int-api/invoices/{invoiceId}/send-email-notification`](/api-reference/invoices/flute-v1-post-pay-int-api-invoices-invoiceid-send-email-notification) |
| Sends the invoice to the customer by SMS with a link to review and pay it. | POST | [`/pay-int-api/invoices/{invoiceId}/send-published-sms-notification`](/api-reference/invoices/flute-v1-post-pay-int-api-invoices-invoiceid-send-published-sms-notification) |
| Downloads a PDF copy of the invoice, for cases like attaching it to an email or filing system. | GET | [`/pay-int-api/invoices/{invoiceId}/download-pdf`](/api-reference/invoices/flute-v1-get-pay-int-api-invoices-invoiceid-download-pdf) |
| Submits a published invoice for card payment processing. | POST | [`/pay-int-api/invoices/{invoiceId}/submit`](/api-reference/invoices/flute-v1-post-pay-int-api-invoices-invoiceid-submit) |
| Submits a published invoice for ACH payment processing. | POST | [`/pay-int-api/invoices/{invoiceId}/ach/submit`](/api-reference/invoices/flute-v1-post-pay-int-api-invoices-invoiceid-ach-submit) |
| Marks a published, unpaid invoice as paid directly, for payment collected outside the API, such as a check received in person. | PUT | [`/pay-int-api/invoices/{invoiceId}/mark-as-paid`](/api-reference/invoices/flute-v1-put-pay-int-api-invoices-invoiceid-mark-as-paid) |
| Cancels a published, unpaid invoice. | PUT | [`/pay-int-api/invoices/{invoiceId}/cancel`](/api-reference/invoices/flute-v1-put-pay-int-api-invoices-invoiceid-cancel) |