Add/Update Invoice

Use this when an invoice is ready in your system and you want the customer to get it and pay it, or when it changes.


The following endpoint can be used to add or update an invoice within the Hyfin application. When an invoice is added to Hyfin, a payment request will be automatically generated and the customer will be notified via text message, email or both, as described under Who gets notified below.

If you choose to omit the customer info, a payment link will be provided in the API response. The payment link can be used on a self-checkout system or kiosk.

If the customer is viewing the invoice on their device and the invoice is updated, a message will display letting the customer know the invoice has been updated and the new version of the invoice will automatically be displayed on the customers device.

Who gets notified

Each customer is under exactly one notification control, worked out from the site and the customer. It is never stored and cannot be set directly.

  • Contact control : each email address and phone number on the customer's contacts carries its own do_not_contact flag, and that flag is the only thing that stops automatic messages to it. This is the control for customers created in the app, for every customer on a QuickBooks site that does not map payment methods to notifications, and for integrations on API v4.
  • Customer control : the customer's notification_options (one choice each for email, text message and WhatsApp) decide for every address of every contact. A missing choice means notify. This is the control for every customer on a QuickBooks site that maps payment methods to notifications, and for customers whose integration set those options on a version before 4.0.

On this version:

  • A customer write with any notification_options.notify_* value places the customer under customer control, including a customer created in the app. For a customer already under customer control, an option you leave out keeps its stored choice. For a customer this write moves to customer control, an option you leave out takes the site's default for new customers, and is on when the site has none. An omitted, null or empty notification_options changes nothing. On a QuickBooks site that does not map payment methods, the options are ignored and the customer stays under contact control.
  • On an invoice write, the notification_options.notify_* values become that invoice's recipients when it is written: a channel set to false is off for the invoice, and every other channel is filled from the customer's contacts at that moment. A channel set to true wins over a customer-control option of false for that invoice, but never reaches an address flagged do-not-contact under contact control. An update that leaves the values out keeps the recipients the invoice already has.

Endpoint

The following endpoint can be used to add or update an invoice. You must replace the {base_url} and {site_id} variable with the site id that was provided when the site was created.

POST
{base_url}/api/v3.1/site/{site_id}/invoice/addUpdate

Request
Field
Type
Description
external_id
String
Your own id for this invoice, from your software. Send the same external_id again to update this invoice instead of adding a new one. We match on this value but do not stop duplicates, so keep it unique within the site.
invoice_number
String
The number assigned from the source system and displayed to the customer on the invoice. Two invoices on a site can share a number, and a payment applied by number goes to the first match found, so keep it unique within the site.
totals
The total amounts on the invoice. When lines are supplied, total is validated against them and must equal the sum of every lines[].total, plus tax, minus discounts. A request whose totals do not reconcile is rejected. Omit lines and no such check is made.
customer
A reference to the customer record.
invoice_term_name
String
The name of an invoice term set up for the site, such as Net 30. When sent, the due date is calculated from the term and the invoice date, replacing any due_date you send. A name that matches no term is rejected with Invoice term "" not found. When left out of a new invoice, the customer's invoice term is used if it has one.
lines
A list of line items on the invoice. Required if description is not passed in.
description
String
A short description of the products/services on the invoice. Required if lines are not passed in.
invoice_date
Date
The date of the invoice. If set in the future, the invoice is not texted or emailed to the customer until that date. Defaults to today if left blank. A date without a time. A time or time zone sent with it is dropped, not converted, so the date stays as written. Format = YYYY-MM-DD
due_date
Date
The date the invoice is due. Ignored when invoice_term_name is sent, because the term sets the due date. A date without a time. A time or time zone sent with it is dropped, not converted, so the date stays as written.
Default = Today (2026-11-21)
Format = YYYY-MM-DD
expire_at
Date
The date the invoice expires. On that date, an invoice with a balance and no payments is cancelled and the customer can no longer pay it. An invoice that has received any payment does not expire. A date without a time. A time or time zone sent with it is dropped, not converted, so the date stays as written. Format = YYYY-MM-DD
po_number
String
The purchase order number assigned from the source system and displayed to the customer on the invoice. It does not need to be unique.
customer_memo
String
A note presented to the customer on the bottom of the invoice.
internal_memo
String
A memo added to the bottom of the invoice. Only visible to internal staff, never displayed to customers.
active
Boolean
This flag represents whether the invoice record is active and available to be used or not.
Default = true
payments
A list of payments made on the invoice.
webhook_url
String
The url to post to when certain actions are performed on the invoice. A webhook is sent when a payment reaches a new status, and when a text message, email or WhatsApp message is sent, delivered, read, delayed or fails, or the customer clicks the payment link.
attachments
String [ ]
A list of attachment urls.
options
Options to set on the invoice.
			
{
  "external_id": "439772921",
  "invoice_number": "12345",
  "description": "Merchandise Bundle",
  "totals": {
    "total": 45.99
  },
  "customer": {
    "external_id": "39772634",
    "first_name": "John",
    "last_name": "Doe",
    "mobile_phone": "111-222-3333",
    "email": "johndoe@abc.com"
  },
  "options": {
    "tipping_enabled": false
  },
  "webhook_url": "https://yourcompany.com/webhook"
}


		
Response
Field
Type
Description
success
Boolean
Whether the record was added or updated successfully.
action
String
Informs whether the record was added or updated. Will only be returned if success is true.
One of added, updated
_id
String
The id we assign to the record.
id
String
The same id as _id, kept for backwards compatibility. Not returned on 4.0 and later.
errors
String [ ]
A list of errors. Will only be returned if success is false.
link
String
The customer-facing payment page for the invoice. Returned on every successful add or update, so you can send it to the customer yourself.
missing_customer
Boolean
Whether the invoice references a customer that has not been synced yet, so the customer will be attached once it arrives.
			
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "id": "60f720d248f143332af022e0",
  "link": "https://site.url/KA39T1A45JL",
  "missing_customer": false
}


		

Related