Get Invoice

Use this when you need the current state of one invoice, such as its balance and payments, by its external_id.


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
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.
_id
String
The id of the invoice, assigned by the system.
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.
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.
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.
created_at
Timestamp
The date the invoice was created. A moment in time in ISO 8601, with a time zone. Format = YYYY-MM-DDTHH:mm:ss.SSSZ
updated_at
Timestamp
The date the invoice was last updated. A moment in time in ISO 8601, with a time zone. Format = YYYY-MM-DDTHH:mm:ss.SSSZ
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"
}


		

Related