Sync Setup — Tax Rates, Contacts & Items

Set up the three foundation sync modules in the correct order before enabling invoice sync.

Overview

Three foundation modules must be synced and configured before invoice sync can run. Complete them in this order:

1. Tax Rates — sync and map every Xero tax type to a local tax code
2. Contacts — sync Xero contacts to customer mapping
3. Items — sync Xero items to product mapping (requires tax mapping to be complete)

Step 1 — Tax Rates

Sync tax rates

1. Go to Configuration → Integrations.
2. Enable Sync Tax Rates if not already on.
3. Click Sync Tax Rates.
4. Wait for the status to show Completed.

Tax rates sync as a single page — no pagination. This is usually fast.

Map tax types

After syncing, each Xero tax type must be manually mapped to a local tax code. Invoice sync is blocked until all tax types are mapped.

1. In Configuration → Integrations, find the Tax Rate Mapping table.
2. For each row showing Unmapped or Needs Review:
   • Select the matching local tax code from the dropdown.
   • Click Save.

Xero tax types by country:

Map each to the corresponding tax code you have configured in Configuration → Tax.

Until all rows are mapped, the Items sync and all Invoice operations are blocked.

Step 2 — Contacts

What contacts sync does

Contacts sync pulls your Xero contact list and creates a mapping between each Xero contact and a Orderverse customer record. This mapping is required for invoice push — every invoice must have a matched Xero contact.

Sync contacts

1. Go to Configuration → Integrations.
2. Enable Sync Contacts if not already on.
3. Choose the contact field mapping you want:
   • Phone Type: Default, Direct dial, Fax, Mobile, or Do not sync
   • Address Type: Billing Address, Delivery Address, or Do not sync
4. Click Sync Contacts.
5. Wait for the status to show Completed.

Contacts are fetched 100 per page. Large contact lists take longer.

If a field is set to Do not sync, Contacts sync leaves that local value alone. This is useful when you want Xero to own the customer identity, but keep phone or address managed locally.

Contact matching

After sync, each Xero contact is matched to a local customer automatically where possible (by name or email). Unmatched contacts appear in the mapping table for manual assignment.

If a customer does not have a matching Xero contact, invoices for that customer cannot be pushed to Xero until the mapping is set.

When Contacts sync is active, Orderverse treats Xero as the source of truth for new customer records. The Add Customer button stays visible, but it opens a guide telling the user to create the contact in Xero first.

Step 3 — Items

What items sync does

Items sync pulls your Xero item master (inventory products) and maps each item to a local product record. It also resolves the product's tax code using the tax rate mapping completed in Step 1.

Tax rate mapping must be complete before Items sync can run. If any tax types are unmapped, Items sync is blocked.

Sync items

1. Go to Configuration → Integrations.
2. Enable Sync Items if not already on.
3. Click Sync Items.
4. Wait for the status to show Completed.

Items are fetched 100 per page.

What items sync updates on products

When an item syncs, the following fields on the matching local product are updated:

Note: product_title (the display name shown on your order portal) is separate from product_name and is not overwritten by Xero sync. Customers always see your custom title.

When Items sync is active, Orderverse treats Xero as the source of truth for new product records. The New Product button stays visible, but it opens a guide telling the user to create the item in Xero first.

Sync status & logs

After each sync run, the status table in Configuration → Integrations shows:

Expand Recent Sync Logs to see per-run detail and any errors.

Re-syncing

You can re-run any module at any time after the cooldown period (60 seconds). Re-syncing contacts or items is safe — existing mappings are preserved and only new or changed records are updated.

Related

• Xero Integration Overview
• Invoice Push
• Invoice Pull & Status Refresh
• Configuration → Tax
• Configuration → Integrations