Field
Type
Description
_id
The id we assign to this invoice. Leave it out when creating an invoice, and send it when updating one.
externalId
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
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.
term
The invoice term, by its Hyfin _id or your externalId. Send either one. Sets the due date and adds the term's early payment discounts and late fees. Defaults to the customer's invoice term if it exists.
lines
A list of line items on the invoice. Required if description is not passed in.
invoiceDate
The date of the invoice. Returned as a timestamp at midnight UTC on that date. A moment in time in ISO 8601, with a time zone. Format = YYYY-MM-DDTHH:mm:ss.SSSZ
dueDate
The date the invoice is due. Returned as a timestamp at midnight UTC on that date. A moment in time in ISO 8601, with a time zone. Format = YYYY-MM-DDTHH:mm:ss.SSSZ
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
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
A note presented to the customer on the bottom of the invoice.
internalMemo
A memo added to the bottom of the invoice. Only visible to internal staff, never displayed to customers.
webhookUrl
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.
createdAt
The date the invoice was created. A moment in time in ISO 8601, with a time zone. Format = YYYY-MM-DDTHH:mm:ss.SSSZ
attachmentRefs
A list of attachments.
customerUrl
The customer-facing link to view and pay the invoice. This is the same link the customer receives when the invoice is sent to them.
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
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".
customer
The _id of the customer
billToCustomer
The _id of the customer who receives and pays the invoice.
billTo
Optional overrides for the Bill To section of the invoice. If billToCustomer is provided, this object will be merged with the customer's information and can be used to override specific fields. If billToCustomer is not provided, the fields in this object will be used as the Bill To information on the invoice.
soldTo
Optional overrides for the Sold To / Customer section of the invoice.
payments
The _ids of the payments associated with this invoice.
deleted
This flag represents whether the record is deleted and no longer available to be used.