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

TOC | Next

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

Some request fields are also stored as the default. For details of these values, see Checking Invoice Defaults.

The following example represents a common request.

{
    "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.

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.

"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.

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

Specific information is retrieved from 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.

{
  "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}.
Deleting uses 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.

TOC | Previous | Next

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 and PUT /pay-int-api/invoices/{invoiceId} accept a lineItems array. See the code example below.

{
  "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.
It can be set with PUT /pay-int-api/merchants/{{merchantId}}/invoices/settings.

TOC | Previous | Next

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 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
This updates the full set. This replaces the whole settings object. The request must resend every field, not just the ones changing.

TOC | Previous | Next

Publishing is what makes an invoice real for the customer. Use:
POST /pay-int-api/invoices/publish.

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

{
    "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 to email the customer a link to review and pay the invoice.
Use 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 returns a PDF copy for these cases.

TOC | Previous | Next

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

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

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 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. 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 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 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}.

TOC | Previous | Next

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}.

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.

TOC | Previous | Next

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
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
• For an ACH-paid invoice, see POST /pay-api/v1/transactions/ach/{transactionId}/refund

TOC | Previous | Next

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}
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.

TOC | Previous

This section lists every endpoint covered in this guide. For detailed information about each endpoint, see Invoices API Reference