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 doNotContact 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 notificationOptions (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 API v4:

  • A customer or subscription write that carries notificationOptions is refused with a 400 and the message "notification_options is not accepted on API v4. Set do_not_contact on the contact emails and phone_numbers instead."
  • On an invoice write, notificationOptions is deprecated and will be refused in a future release. It is still applied, exactly as on 3.1: it becomes the invoice's send.to recipients, and the response succeeds with a warnings entry. Sent together with send.to it is refused with a 400. Move to send.to now.
  • A customer write on a site that is not connected to QuickBooks moves that customer to contact control. Its notification options are copied onto doNotContact on every address once, then removed, and the doNotContact values in the request are applied after that.
  • On a QuickBooks site with mapPaymentMethodsToNotifications on, QuickBooks payment methods decide notifications for every customer, so a customer write that carries doNotContact is refused with a 400 that names that setting. Leave the flag out, or have the merchant turn the setting off.
  • onHold: false on an invoice write does not release an invoice that is held because it reaches nobody. Give it a recipient to let it send.
  • The customer read never returns notificationOptions .

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/v4/site/{site_id}/invoice/addUpdate

Request
Field
Type
Description
externalId
String
Your own id for this invoice, from your software. Send the same externalId 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.
invoiceNumber
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 taxes, 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.
invoiceTermName
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 dueDate 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.
invoiceDate
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
dueDate
The date the invoice is due. Ignored when invoiceTermName 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
expireAt
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
poNumber
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.
customerMemo
String
A note presented to the customer on the bottom of the invoice.
internalMemo
String
A memo added to the bottom of the invoice. Only visible to internal staff, never displayed to customers.
payments
A list of payments made on the invoice.
webhookUrl
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.
options
Options to set on the invoice.
attachmentRefs
A list of attachments.
send
Who the invoice is sent to, per channel. A channel you list is used as given, and an empty list ([]) turns that channel off. A channel you omit keeps the recipients the invoice already has, or is filled from the customer's contacts, following the customer's notification control, when it has none yet. On a create, leave send out to let the customer's contacts decide every channel when the invoice is sent. On an update, leaving it out keeps the recipients already chosen. A read returns send.to as null until recipients have been chosen. billTo.emails and billTo.sms stay the override for who receives those channels, but never turn back on a channel send turned off.
onHold
Boolean
Whether the first unpaid installment is held, so its payment request is not sent until the hold is released. On a read it is true when that installment is held and false otherwise. On a write, set it to true to hold that installment, or to false on an update to release it. Omit it to leave the hold as it is. The hold lives on the installment, not on the invoice.
false releases a hold you or the merchant placed. It does not release the hold an invoice gets when it reaches nobody and will not be charged automatically: send.to turns every channel off, or every address of the customer is do-not-contact and there is no billTo override. That invoice stays held and the write still succeeds, also when you supply installments yourself or set installments[].onHold to false. Give it a recipient to let it send.
A write that sends both onHold and installments[].onHold on the first unpaid installment must give them the same value. Otherwise it is refused with a 400 and the message "Invalid on_hold, it conflicts with on_hold on the first unpaid installment. Send one of them, or the same value in both". A value that is not a boolean is refused with "Invalid on_hold, must be a boolean".
deleted
Boolean
This flag represents whether the record is deleted and no longer available to be used.
			
{
  "externalId": "439772921",
  "invoiceNumber": "12345",
  "description": "Merchandise Bundle",
  "totals": {
    "total": 4599
  },
  "customer": {
    "externalId": "39772634",
    "firstName": "John",
    "lastName": "Doe",
    "mobilePhone": "111-222-3333",
    "email": "johndoe@abc.com"
  },
  "options": {
    "tippingEnabled": false
  },
  "webhookUrl": "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.
updatedAt
The date the record was last updated. A moment in time in ISO 8601, with a time zone. Format = YYYY-MM-DDTHH:mm:ss.SSSZ
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.
missingCustomer
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",
  "updatedAt": "2025-05-30T19:19:44.143Z",
  "link": "https://site.url/KA39T1A45JL",
  "missingCustomer": false
}


		

Related