Xero settings

Every setting on the Xero Configurations (invoices, credit notes, purchase orders, journals, supplier bills, bank transactions and statements), with values, defaults and when to change each one.

The Xero connector has one Configuration per Xero record type: Xero Invoice, Xero Credit, Xero Purchase Order, Xero Journal, Xero Purchase Invoice, Xero Bank Transaction and Xero Statement. Almost all of them send to Xero; the Xero Invoice Configuration can also receive (import invoices from Xero). Many settings are shared, so the shared line settings are listed once under the invoice and the other record types refer back to them.

Xero Invoice: numbering, status and contact

Setting	What it does	Values / default	When to change it
Use source invoice number `useSourceInvoiceNumberAsInvoiceNumber`	Uses the source system's invoice number as the Xero invoice number.	On or off. Off: Xero numbers the invoice.	When both systems should show the same number.
Order number as reference `useSourceOrderNumberAsReference`	Puts the source order number in the invoice's reference field.	On or off.	For traceability back to the order.
Status for unpaid invoices `statusUnpaid`	The status unpaid invoices are created in.	`DRAFT`, `SUBMITTED` or `AUTHORISED`. Default `DRAFT`.	When invoices should arrive approved rather than for review.
Status for paid invoices `statusPaid`	The status paid invoices are created in.	Default `DRAFT`.	When paid invoices should be approved straight away.
Mark as sent `markAsSent`	Marks the invoice as sent in Xero. Sends no email; it only sets the flag.	On or off. Only applied when the invoice is created `AUTHORISED` or `PAID`; ignored on a `DRAFT`.	So approved invoices don't show as awaiting action.
Mark as sent by tag `markAsSentMap`	Per-invoice override of `markAsSent` by tag, in either direction.	Tag map to true or false. Same approval rule.	When one customer or channel differs from the rest.
Prefer person's name for contact `preferNameForContact`	Prefers the individual's name over the company name for the Xero contact.	On or off.	Consumer sales.

Xero Invoice: lines and accounts

Setting	What it does	Values / default	When to change it
Line account codes `lineAccountCodeMap`	Maps order tags to Xero account codes for line items. First matching tag wins.	Tag map.	When channels or customers should post to different sales accounts.
Charges account `adjustmentLineAccountCodeForCharges`	Account code for charge adjustments (fees, surcharges).	Account code.	To post charges to their own account.
Discounts account `adjustmentLineAccountCodeForDiscounts`	Account code for discount adjustments.	Account code.	To post discounts to their own account.
Additional lines account `additionalLineAccountCode`	Account code for any extra lines the integration adds.	Account code.	When you use `additionalLineCalculations`.
Shipping account `shippingLineAccountCode`	Account code for shipping lines.	Account code.	To record shipping in a dedicated account.
Description-only lines `createLinesAsDescriptionsOnly`	Creates lines with no ItemCode; the SKU goes into the description instead.	On or off.	When your products aren't set up as Items in Xero.
Description-only account `descriptionLineAccountCode`	The account code for description-only lines.	Account code. Default `200`.	With `createLinesAsDescriptionsOnly`.
Tracking categories `lineTrackingCategories`	Xero tracking category configurations applied to line items.	List.	To split figures by project, cost centre and so on.
Invoice note as a line `includeInvoiceNoteAsDescriptionLine`	Adds the invoice note as a description-only line at the end.	On or off.	So memos and instructions are visible in Xero.
Additional line calculations `additionalLineCalculations`	Rules for adding extra calculated lines (computed fees or adjustments), each with conditions and a calculation.	List of rules.	When invoices need computed extra lines.

Xero Invoice: tax

Setting	What it does	Values / default	When to change it
Set tax type on lines `setTaxTypeOnLineItems`	Writes the resolved tax type to each line's TaxType field.	On or off. Off: Xero derives the tax type from the product.	When Supply Lens, not Xero, should decide the tax.
Exclude tax on lines `excludeTaxOnLines`	Records line amounts net of tax.	On or off.	When amounts should go in without tax.
Exclude tax by tag `excludeTaxOnLinesMap`	Per-order override of the above by tag.	Tag map to true or false.	When it depends on the order.

Xero Invoice: payments and dates

Setting	What it does	Values / default	When to change it
Generate payment `generatePaymentForInvoice`	Creates a Xero payment when the invoice is created.	On or off.	When orders are already paid at invoice time.
Generate payment by tag `generatePaymentForInvoiceMap`	Per-order override of the above by tag.	Tag map to true or false.	When only some channels are prepaid.
Payment equals created total `setPaymentAmountToCreatedInvoiceTotal`	Sets the payment to the invoice total as created in Xero, not the source amount.	On or off.	So the payment matches what Xero recorded.
Bank account by tag `bankAccountTagMap`	Maps order tags to the Xero bank account for payments. First match wins.	Tag map.	When channels pay into different accounts.
Due date in days `setDueDateToInvoiceDatePlusDays`	Sets the due date to the invoice date plus this many days.	Number, for example `30`.	To apply payment terms.
Due date defaults to invoice date `defaultDueDateToInvoiceDate`	Uses the invoice date as the due date when no rule gives one.	On or off. Default on. Off: no due date is set by default.	Turn off if you don't want a default due date.
Invoice date from ship date `setInvoiceDateFromShipDate`	Takes the invoice date from the shipment date rather than the order date.	The ship date type, for example `actual` or `expected`.	When you invoice on dispatch.

Xero Invoice: which invoices are sent

Setting	What it does	Values / default	When to change it
Include references `referenceIncludeRegex`	Only invoices whose reference matches this pattern are processed.	Regex.	To send only some invoices.
Exclude references `referenceExcludeRegex`	Invoices whose reference matches this pattern are skipped.	Regex.	To skip some invoices.
Reference pattern options `referenceRegexOptions`	Options for the two patterns, for example `IgnoreCase`.	Regex options.	To make matching case-insensitive.
Skipped log level `referenceRegexLogLevel`	The log level used when a Document is skipped by the reference filters.	Log level.	To make skips more or less prominent in logs.

Xero Invoice: importing from Xero (`receive`)

Setting	What it does	Values / default	When to change it
Setup date `receive.setupDate`	Only invoices on or after this date are imported.	Date. Set automatically when the integration is first configured.	Rarely.
Last import date `receive.lastImportDate`	The most recently imported invoice; updated after each run.	Managed by the system.	Don't edit it by hand.
Item code separator `receive.descriptionItemCodeSeparator`	Extracts the item code from the description by splitting on this character.	A separator character.	When products are held in the description, not the ItemCode.
Statuses to import `receive.includeInvoiceStatuses`	The Xero invoice statuses to import.	`DRAFT`, `SUBMITTED`, `DELETED`, `AUTHORISED`, `PAID`, `VOIDED`. Empty: all statuses.	To import only approved invoices, for example.
Contacts to import `receive.includeContactNames`	When not empty, only invoices for these Xero contact names are imported.	List of names.	To import one customer's invoices.

Xero Credit

Credit notes use these settings, plus the invoice settings shown.

Setting	What it does	Values / default	When to change it
Status `status`	The status the credit note is created in.	For example `DRAFT` or `AUTHORISED`.	When credits should arrive approved.
Generate payment `generatePaymentForCreditNote`	Creates a Xero payment (refund) when the credit note is created.	On or off.	When refunds are already made.
Payment equals created total `setPaymentAmountToCreatedCreditTotal`	Sets the payment to the credit note total as created in Xero.	On or off.	So the payment matches the credit.
Bank account by tag `bankAccountTagMap`	Maps tags to the bank account for credit note payments.	Tag map.	When refunds come from different accounts.

Also available on Xero Credit, working as on the invoice: setTaxTypeOnLineItems, createLinesAsDescriptionsOnly, descriptionLineAccountCode, lineAccountCodeMap, adjustmentLineAccountCodeForCharges, adjustmentLineAccountCodeForDiscounts, shippingLineAccountCode, excludeTaxOnLines, excludeTaxOnLinesMap and lineTrackingCategories.

Xero Purchase Order

Setting	What it does	Values / default	When to change it
Adjustments account `adjustmentLineAccountCode`	Account code for adjustment lines (charges and discounts).	Account code.	To post adjustments to their own account.
Shipping account `shippingLineAccountCode`	Account code for shipping lines.	Account code.	To post shipping separately.
Buyer order number as PO number `useSourceBuyerOrderNumberAsPurchaseOrderNumber`	Uses the source buyer's purchase order number as the Xero PO number.	On or off. Off: Xero numbers it.	When PO numbers should match.
Create in status `createInStatus`	The status the purchase order is created in.	For example `DRAFT` or `SUBMITTED`.	When POs should skip review.
Mark as sent `markAsSent`	Marks the PO as sent. Sends no email.	On or off. Only applied when `createInStatus` is `AUTHORISED` or `BILLED`.	So approved POs show as sent.
Mark as sent by tag `markAsSentMap`	Per-PO override of `markAsSent` by tag.	Tag map. Same approval rule.	When suppliers differ.

Also available, working as on the invoice: setTaxTypeOnLineItems, createLinesAsDescriptionsOnly and descriptionLineAccountCode.

Xero Journal

A journal is posted as a Xero manual journal. Each line is worth its quantity times its unit cost, rounded to two decimal places: positive is a debit, negative a credit. The journal must already sum to zero, which the balance-journal plugin ensures; use its line rounding level so the rounded lines still balance.

Setting	What it does	Values / default	When to change it
Line account codes `lineAccountCodeMap`	Maps tags to the account each line posts to, matched on the line's tags first and then the journal's.	Tag map. A line that matches nothing fails translation.	Always: every line needs an account.
Narration `narrationFormat`	The journal's narration, where `{0}` is the journal's number.	For example `{0} goods received`. Default: the number itself.	For clearer narrations.
Create as draft `createAsDraft`	Creates the journal as a draft instead of posting it.	On or off. Default off.	To review journals before posting.
Skip zero-value journals `skipZeroValueJournals`	Doesn't send a journal whose every account nets to zero, such as a transfer between two warehouses on the same stock account.	On or off. Default on.	Turn off only if you want such journals in Xero.

Xero Purchase Invoice (supplier bills)

A purchase invoice is raised as a Xero supplier bill (ACCPAY). Each line is a description (product code and name) at its quantity and net value, with no item code. A line with a tax code carries the Xero tax type that code is cross-referenced to; a tax code with no Xero tax type fails translation, so every tax code in use needs mapping. A Document with no tax on any line is sent with no tax. The bill is in the Document's currency, its reference is the order number and its date is the receipt's. The supplier is matched by a cross-referenced Xero contact id, account number or contact number, otherwise by name, and Xero creates a new contact for a name it doesn't recognise.

Setting	What it does	Values / default	When to change it
Line account `lineAccountCode`	The account every bill line posts to unless the map chooses another. For a bill raised on receipt, your goods received not invoiced account.	Account code. A line with neither fails translation.	Always set one or the map.
Line account codes `lineAccountCodeMap`	Maps tags to the account a line posts to, matched on the line's tags first and then the Document's.	Tag map. Beats `lineAccountCode`.	When lines post to different accounts.
Create in status `createInStatus`	The status the bill is created in.	`DRAFT` (default) or `SUBMITTED` for approval.	To send bills for approval.
Use document currency rate `useDocumentCurrencyRate`	Converts a foreign-currency bill at the rate recorded on the Document, so a bill raised on receipt clears goods received not invoiced exactly.	On or off. Default off: Xero uses its own rate for the bill date, leaving the rate difference on the clearing account.	When foreign bills should clear exactly. With it on, a foreign Document with no rate fails.

Xero Bank Transaction

Bank transactions use these settings, all working as on the invoice:

Setting	What it does
`adjustmentLineAccountCodeForCharges` / `adjustmentLineAccountCodeForDiscounts`	Account codes for charge and discount lines.
`createLinesAsDescriptionsOnly` / `descriptionLineAccountCode`	Lines without ItemCodes, and their account.
`lineAccountCodeMap`	Tag map of account codes for transaction lines.
`setTaxTypeOnLineItems`	Whether the tax type is set on lines.
`shippingLineAccountCode`	Account code for shipping lines.
`excludeTaxOnLines` / `excludeTaxOnLinesMap`	Whether tax is excluded from lines.
`bankAccountTagMap`	Tag map choosing the bank account the transaction is recorded against.

Xero Statement

Setting	What it does	Values / default	When to change it
Line amount types `lineAmountTypes`	How Xero reads line amounts.	`EXCLUSIVE`, `INCLUSIVE` or `NOTAX`.	To match whether amounts include tax.
Contact by tag `contactIdTagMap`	Maps tags to a Xero contact ID. The first match decides who the statement is raised for.	Tag map.	Always, to choose the contact.
Statement lines `lines`	The lines on the statement and which amounts each includes (fields below).	List.	To build the statement layout.

Each entry in lines has these fields:

Field	What it is
`name`	The display name of the statement line.
`addTags`	Tag patterns whose amounts are added to this line.
`subtractTags`	Tag patterns whose amounts are subtracted from this line.
`accountCode`	The Xero account code for this line.