Mapping Fields Between Salesforce and Xero

Updated 19 Sept 2026

Out of the box, TwoCanConnect maps the standard Opportunity and Opportunity Product fields onto a Xero invoice, and the standard Account and Contact fields onto a Xero contact. Custom Object / Field Mapping is where you change those defaults, carry custom fields across, or raise documents from an object other than Opportunity.

Configuration → Advanced → Custom Object / Field Mapping.

The Custom Object / Field Mapping screen showing the Invoice & Line Item mapping sets table with the TCC set, and the Custom Object Button Creation Tool beneath it — The Invoice card. One mapping set, TCC, mapping Opportunity and Opportunity Product. The New button adds a set; the menu on the row edits or deletes it.

The screen

The page is a stack of cards, one per document type, plus one for contacts. Each document card has the same shape: a short explanation, a mapping sets table, and a Custom Object Button Creation Tool panel.

Card	Default set	Allowance
Invoice & Line Item	TCC	10 sets
Repeating Invoice & Line Item	TCR	10 sets
Quote & Line Item	TCQ	10 sets
Purchase Order & Line Item	TCP	10 sets
Salesforce Account and Contact to Xero Contact	one set	1 only

Quote and Purchase Order cards appear only when your plan includes them. The default sets are provided and already map Opportunity and Opportunity Product, so a fresh install works without touching this screen.

The Repeating Invoice card with its TCR set, and the top of the Purchase Order card below it — Each document type has its own card. The counter in the card header shows how many of the ten sets are used.

The mapping sets table

Column	Meaning
Field Mapping Set ID	The name a button passes to pick this set. The defaults are TCC, TCR, TCQ and TCP
Object Name	The master object the document is raised from
Child Object Mapping	The child object that feeds line items, usually Opportunity Product
Active	An inactive set is ignored by the wizard
Object Default	The set the wizard uses for that object when a button doesn't name one. One default per object
Edit / Del	Opens the editor, or deletes the set

Use the right card's set

A quote needs a set from the Quote card, a purchase order a set from the Purchase Order card. Pointing a quote button at the invoice set fails in ways that don't mention mapping: "No line items came from the source record", or every unit price showing A$0.00. If a wizard shows no lines or zero prices, check which set the button passes first.

The mapping set editor

New, or Edit from a row's menu, opens the Custom Object Field Mapping editor. It's one long form in three parts.

1. Master object and invoice fields

The editor's first section: Choose Object to Map set to Opportunity, then invoice-level fields — Invoice Date from Close Date, Invoice Due Date from Created Date with Default to customer payment terms ticked, and Custom Invoice Number, Custom Reference Number and Default Xero Organization unmapped — Top of the editor. The master object, then the invoice header fields it feeds.

Choose Object to Map is the master object: the record you raise the invoice from. Every other dropdown in this section then lists that object's fields.

Invoice field	What it does
Invoice Date	The date on the Xero invoice. Default Close Date
Invoice Due Date	The due date. With Default to customer payment terms ticked, the due date is calculated from the Xero contact's payment terms and this field is only the fallback when the contact has none. See Customer payment terms
Custom Invoice Number	A field whose value becomes the Xero invoice number. Leave unmapped and Xero numbers it
Custom Reference Number	A field for the Xero Reference
Default Xero Organization	For multi-organisation orgs, a field that names which Xero organisation the invoice goes to
Matching Invoice Lookup Field	The lookup on the TCC Xero Invoice object that points back at the master object, so the invoice is related to the record it was raised from. For Opportunity it's set for you; for any other object, create a lookup field on the Invoice object first and pick it here

Below those, Dynamic Reference lets you build the reference from a field, and Additional Product Line adds one extra line item to every invoice from a field on the master object, at a position you choose. Useful for a delivery fee or a fixed charge that isn't a product.

2. Child object and line item fields

The editor's line item section: Quantity, Unit Price, Discount, Total, Sort Order, Category Name 1, Category Option 1, Category Name 2 and Category Option 2, each mapped from an Opportunity Product field — Line item fields. Each Xero line item field on the left takes a field from the child object on the right.

The child object is what becomes the line items, one record per line. The defaults map Opportunity Product.

Line item field	What it does
Quantity, Unit Price, Discount, Total	The numbers on each line
Sort Order	A field that decides the order lines appear in on the invoice
Product Name	The field used as the line description when there's no product lookup
Product Id	A lookup to Product. Set it and the line is tied to the matching Xero item, with its account and tax rate
Xero Account, Xero Tax Rate	Lookups on the child object, if you want a line to override the product's defaults
Category Name 1 / Option 1, Category Name 2 / Option 2	Tracking categories. The values must match Xero exactly

3. Line item description

The Invoice Line Item Description Field Mapping section: Product Name Format set to Product Name, a Product Separator, and an optional custom field — How the description on each Xero line is built.

Product Name Format decides what the line's description is built from, Product Separator the character between parts, and Custom Field an extra field from the child object to append. That's how you get a description like Golf balls - white 6-pack | Spring promo from the product name and a custom field.

Click Done to save. Changes apply to invoices raised from then on; existing invoices aren't touched.

Account and Contact to Xero Contact

This mapping is a different shape. Each Xero Contact field can be fed from either the Salesforce Account or the Contact. Choosing one side greys out the other, so a Xero field can't be fed from two places at once.

The Account and Contact mapping editor: three columns — Xero Contact Field, Salesforce Account Field, Salesforce Contact Field — with First Name, Last Name and Email from the Contact and Xero Customer Name and address fields from the Account — The defaults: company name and address from the Account; the person's name and email from the Contact.

That's how a Xero contact ends up with the company name and billing address from the Account and the person's name, email and phone from the primary Contact. Add Tax Number and Account Number here if you hold an ABN or customer number on the Account; both then feed the Matching Tool as exact-match signals.

Raising documents from another object

Out of the box, invoices are raised from Opportunities. Subscriptions, jobs, bookings, matters and Salesforce Quotes can all raise documents too. To invoice from another object you need two things: a mapping set whose master object is that object, and a button on that object that launches the wizard. Custom Object Button Creation Tool builds the button.

The object needs:

A lookup to an Account, so the wizard knows which Xero contact to use
A lookup field on the TCC Xero Invoice object pointing back to your object, so each invoice created is related to the record it came from. Create it in Setup on the Invoice object (Object Manager → Invoice → Fields → New → Lookup to your object), then pick it as the Matching Invoice Lookup Field in the mapping set. For quotes, repeating invoices and purchase orders, the lookup goes on that document's object instead
Line item data, either a child object with products (like Opportunity Product) or fields you map to line items
A mapping set naming that object as the master, with the fields that should appear on the document

The master object list covers most standard and custom objects in your org: anything that can be created, updated, deleted and queried, so Cases, Contracts, Orders, Work Orders and your own objects all appear.

The TwoCanConnect Custom Object Button Creator: object to create the button on, the field linking back to the Account, an optional mapping set, button type, invoice type and button label — Launch, under any document card, opens the button creator for that document type.

Question	What to pick
Which object do you want to create a button on?	The object you'll raise the document from
Which field on the object links back to the Salesforce Account?	The lookup the wizard follows to find the Xero contact. Required
Do you want to map a specific field mapping set to this button?	Leave empty to use the object's default set, or name one so this button behaves differently
Which button type?	Detail Page Button raises a document from one record. List Button works from a list view
New or Repeating Invoice	On the invoice card only
Button Label	What users see

Create New Button on Object deploys the button; add it to the object's page layout afterwards. Copy Code to Clipboard gives you the button URL instead, if you'd rather create it yourself in Setup.

Ten sets, not ten objects

The limit is 10 sets per document type, shown in each card header as (n/10 Used). Each set names one master object, so ten sets means up to ten source objects for invoices. If you need more, get in touch.

For the full walkthrough of raising documents from a custom object, see Generating documents from custom objects.

Still stuck?Run Self-Diagnose Submit a case →