Invoice header: numbers, contacts, dates and status
Lesson 5 of 12 8 min read
Decide how each Xero invoice is numbered and referenced, who it's addressed to, which dates it carries, and what state it arrives in.
The header is the part of an invoice your finance team looks at first: the number, the reference, the contact, the dates and whether it's a draft. In this lesson you'll work through the Xero Invoice settings that control the header, grouped by the decision each one answers. You change them in the Xero Invoice configuration's JSON.
Who numbers the invoice, and what's the reference?
| useSourceInvoiceNumberAsInvoiceNumber | On: the invoice number from the source system becomes the Xero invoice number. Off: Xero numbers it with its own sequence. Choose on when customers or other systems quote the source number; choose off when finance wants Xero's numbering unbroken. |
|---|---|
| useSourceOrderNumberAsReference | On: the source order number goes in the Xero invoice's reference. Turn this on almost always, because it's how finance traces an invoice back to the order. |
Tip
If the source system doesn't produce invoice numbers of its own, leave Xero to number the invoice and rely on the order number in the reference for traceability.
Who is the invoice addressed to?
| preferNameForContact | On: the individual's name is preferred over the company name when filling in the Xero contact. Choose on for consumer-style orders where there's no meaningful company; leave off for business customers so invoices go to the company. |
|---|
Which dates does it carry?
| setInvoiceDateFromShipDate | When set, the invoice date comes from the shipment date instead of the order date. The value chooses which ship date to use, for example actual or expected. Use it when you invoice on despatch and want the date to match. |
|---|---|
| setDueDateToInvoiceDatePlusDays | Sets the due date to the invoice date plus this many days. For example, 30 gives 30-day terms. |
| defaultDueDateToInvoiceDate | On by default. If no due date rule gives a value, the due date is the invoice date. Turn it off if you'd rather have no due date than a same-day one. |
What state does the invoice arrive in?
| statusUnpaid | The Xero status for unpaid invoices: DRAFT, SUBMITTED or AUTHORISED. If not set, DRAFT. |
|---|---|
| statusPaid | The Xero status for paid invoices. If not set, DRAFT. |
| markAsSent | On: the invoice is flagged as Sent in Xero. It emails nothing. Xero only accepts the flag on an approved invoice, so it only applies when the status is AUTHORISED or PAID; on a DRAFT it's ignored without an error. |
| markAsSentMap | Tag-based override of markAsSent, invoice by invoice. Use it to mark one customer or channel as sent while leaving the rest, or the other way round. The same approval rule applies. |
How to choose:
DRAFTgives finance a review step inside Xero. Good while you're testing and for the first weeks of live running.SUBMITTEDputs the invoice into Xero's awaiting-approval state, for teams that approve invoices in Xero.AUTHORISEDposts the invoice to the ledger straight away. Choose it once you trust the data, and when you want markAsSent to work.
markAsSent does nothing on drafts
If you turn on markAsSent but leave statusUnpaid at its default of DRAFT, nothing will be
marked as sent. That's expected, not a fault.
Which invoices should be processed?
| referenceIncludeRegex | A pattern the invoice's reference must match to be processed. |
|---|---|
| referenceExcludeRegex | A pattern that, if the reference matches it, stops the invoice being processed. |
| referenceRegexOptions | Options for the patterns, such as IgnoreCase. |
| referenceRegexLogLevel | How prominently a skipped invoice is logged. |
A regular expression (regex) is a text pattern. For example, a pattern of ^EDI- matches
references that start with EDI-. These filters are an implementer tool: use them when only
some invoices should reach Xero and there's no simpler way, such as a Mapping filter, to pick
them out.
Hilltop Coffee's header settings
Hilltop's cafés quote the EDI order number, so the implementer turns on
useSourceOrderNumberAsReference and leaves Xero to number invoices. Invoice date comes from
the actual ship date, with 30-day terms. For the first month statusUnpaid stays DRAFT. After
sign-off they switch to AUTHORISED and turn on markAsSent, so approved invoices no longer sit
in Xero's awaiting-action list.
Recap
- Number and reference: source invoice number or Xero's; source order number as reference for traceability.
preferNameForContactaddresses invoices to the person rather than the company.- Dates: invoice date from the ship date, due date as invoice date plus days, and a fallback to the invoice date.
- Status defaults to
DRAFT;markAsSentonly applies to approved invoices and never emails. - Reference regex filters pick which invoices are processed.
Quick guides for this topic
Your progress is saved in this browser. Create a free account to keep it everywhere, take quizzes and earn certificates.