Get Invoice
The following endpoint can be used to retrieve the details of an invoice within the Hyfin application.
Endpoint
The following endpoint can be used to retrieve an invoice. You must replace the {base_url} , {external_id} and {site_id} variables with the appropriate values.
GET
{base_url}/api/v3.1/site/{site_id}/invoice/{external_id}
Request
No body is required for this API call
Response
Field
Type
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.
_id
String
The id of the invoice, assigned by the system.
invoice_number
String
The unique number assigned from the source system and displayed to the customer on the invoice.
reference_number
String
The unique reference number assigned to the invoice by the system. It is also the code in the customer-facing link.
internal
Boolean
Whether the invoice is internal to the merchant and was never sent to a customer.
notifications
The notifications sent to the customer for this invoice, most recent last.
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. 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-09-25) Format = YYYY-MM-DD
Default = Today (2026-09-25) 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
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.
created_at
Date
The date the invoice was created.
updated_at
Date
The date the invoice was last updated.
Sample Response
{
"_id": "61f32dc2f62bdc6a48945067",
"external_id": "439772921",
"invoice_number": "12345",
"description": "",
"customer_memo": "",
"internal_memo": "",
"due_date": "2021-10-01",
"totals": {
"tax": 2.85,
"total": 32.85
},
"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",
"reference_number": "N7E6NFU6WZZ5-PW3A",
"gateway_transaction_id": "53912387124235234",
"payment_type": "payment_card",
"payment_sub_type": "amex",
"display_name": "Amex",
"amount": 30,
"tip": 0,
"tax": 0,
"fee": 0,
"paid_on": "2021-03-15T16:32:11Z",
"status": "captured",
"is_refund": false,
"created_at": "2025-05-30T19:19:44.143Z",
"updated_at": "2025-05-30T19:19:44.143Z"
}
],
"notifications": [
{
"error": false,
"value": "test@test.com",
"description": "Email to test@test.com sent",
"at": "2021-03-15T13:32:11Z"
},
{
"error": false,
"value": "999-123-4567",
"description": "Text to 999-123-4567 sent",
"at": "2021-03-15T13:32:11Z"
}
],
"webhook_url": "https://yourcompany.com/webhook",
"created_at": "2025-05-30T19:19:44.143Z",
"updated_at": "2025-05-30T19:19:44.143Z"
}