Hyfin Logo
API Docs 3.0API Docs 3.1API Docs 4.0 SimpleAPI Docs 4.0

Add/Update Invoice

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 based on the notification options set on the customer record.

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.

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

The same endpoint is used to add or update an invoice. If an invoice already exists with the {external_id} , the invoice will be updated otherwise it will be inserted.
Request
Field
Type
Required
Description
external_id
String
The unique invoice id from the source system/database. If we detect a record with the same `external_id`, it will be updated, otherwise it will be added.
invoice_number
String
The unique number assigned from the source system and displayed to the customer on the invoice.
totals
The total amounts on the invoice. Validated against the sum of the line items found in `lines`.
customer
--
A reference to the customer record. Omit this field to receive a link to the invoice.
invoice_term_name
String
--
The invoice term name for the invoice. Defaults to the customer invoice term if it exists, unless `null` is passed in.
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 request will not be sent until that date. Defaults to today if left blank. Format = YYYY-MM-DD
due_date
Date
--
The date the invoice is due. Will be overwritten if `invoice_term_name` is set and returns a different due date.
Default = `Today (2026-05-11)` Format = YYYY-MM-DD
expire_at
Date
--
The date the invoice will expire. The request will be cancelled if it hasn't been completed. Format = YYYY-MM-DD
po_number
String
--
The unique purchase order number assigned from the source system and displayed to the customer on the invoice.
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. Notifications will be sent when a text/email fails, a customer clicks a link, or they make a payment.
attachments
String [ ]
--
A list of attachment urls.
options
--
Options to set on the invoice.
Sample Request (Simple)
			
				{
  "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": {
    "tippingEnabled": false
  },
  "webhook_url": "https://yourcompany.com/webhook"
}
Sample Request (Advanced)
			
				{
  "external_id": "439772921",
  "invoice_number": "12345",
  "description": "",
  "customer_memo": "Thank you for your business!",
  "internal_memo": "",
  "invoice_date": "2022-12-01",
  "invoice_term_name": null,
  "expire_at": "2023-01-01",
  "totals": {
    "taxes": 2.85,
    "total": 30
  },
  "customer": {
    "external_id": "39772634",
    "first_name": "John",
    "last_name": "Doe",
    "mobile_phone": "111-222-3333",
    "email": "johndoe@abc.com"
  },
  "lines": [
    {
      "description": "",
      "product": {
        "external_id": "62331255",
        "name": "Mens Large T-shirt",
        "unit_price": 15
      },
      "unit_price": 15,
      "qty": 2,
      "total": 30
    }
  ],
  "payments": [
    {
      "external_id": "72345322",
      "payment_type": "payment_card",
      "payment_sub_type": "amex",
      "display_name": "AMEX ****** 3422",
      "amount": 20,
      "gateway_transaction_id": 1234,
      "paid_on": "2021-03-15T16:32:11Z",
      "active": true
    }
  ],
  "options": {
    "tippingEnabled": false
  },
  "webhook_url": "https://yourcompany.com/webhook",
  "attachments": [
    "https://url.to.your/attachment"
  ]
}
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 auto generated id assigned to the record.
errors
String [ ]
A list of errors. Will only be returned if `success` is `false`.
link
String
The link to the invoice. Only returned if a `customer` is not passed in.
Sample Response (Successful)
			
				{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "link": "https//site.url/KA39T1A45JL"
}
Sample Response (Failed)
			
				{
  "success": false,
  "errors": [
    "invalid field2",
    "missing field_name"
  ]
}