Xero

Sync contacts and invoices from your data warehouse to Xero. Keep your Xero accounting records enriched with the latest customer data, contact details, and invoice information from your central data platform.

Prerequisites

• A Xero account (any plan)
• A Xero OAuth 2.0 app registered in the Xero Developer Portal 
• The Xero organisation tenant ID (UUID) for the target organisation
• OAuth scopes: accounting.contacts and/or accounting.transactions depending on your sync target

Permissions

Your Xero OAuth app must request the following scopes:

The Xero user who authorises the app must have Adviser or Standard role access to the target organisation. Users with Invoice Only or Read Only access cannot create or update records.

Authentication

Xero uses OAuth 2.0 for all API access. API key authentication is not supported.

OAuth 2.0 (Recommended)

1. Log in to the Xero Developer Portal 
2. Create a new app or select your existing app
3. Note your Client ID and Client Secret
4. In Zeotap, select OAuth 2.0 as the auth method
5. Click Connect to begin the OAuth flow
6. Authorise Zeotap to access your Xero organisation
7. Zeotap will automatically refresh your access token every 30 minutes

Access Token

If you already have a valid Xero access token (for testing or custom integrations):

1. Select Access Token as the auth method
2. Paste your access token into the Access Token field
3. Note: Xero access tokens expire after 30 minutes. For production use, OAuth 2.0 is strongly recommended.

Configuration

Finding Your Tenant ID

After completing OAuth authorisation, call the Xero Connections endpoint to list your authorised tenants:

curl -H "Authorization: Bearer {access_token}" \
     -H "Content-Type: application/json" \
     https://api.xero.com/connections

The response includes the tenantId (UUID) for each authorised organisation.

Target Settings

Supported Operations

Sync Modes

Audience Sync Modes

Xero does not have a native audience or list membership concept. Contact Groups exist in Xero but are managed separately from the standard contact sync. Audience sync modes are not supported.

Features

• Field Mapping: Yes
• Schema Introspection: No — Xero contact and invoice fields are well-known and provided as default destination fields

Required Mapping Fields

Default Destination Fields

Contact Fields

Invoice Fields

How It Works

1. Field Mapping: Zeotap maps your warehouse columns to Xero contact or invoice fields. Field names must match Xero’s API field names (PascalCase, e.g. FirstName, EmailAddress).

2. Batch Requests: Xero accepts up to 50 records per API request. Zeotap automatically chunks your data into batches of 50 and sends them as JSON payloads.

3. Request Format: All requests use JSON (application/json) with the Authorization: Bearer {token} and Xero-Tenant-Id: {tenant_id} headers. Items are wrapped in a named array:

   {
     "Contacts": [
       { "Name": "Acme Corp", "EmailAddress": "billing@acme.com" }
     ]
   }

4. Sync Mode Behavior (all modes use the Xero POST /Contacts or POST /Invoices endpoint, which is documented as “create or update”):

   • Insert: Sends POST without a ContactID or InvoiceID. Xero creates new records.
   • Update: Sends POST with the ContactID or InvoiceID populated from the configured ID field. Xero updates the existing record.
   • Upsert: Sends POST with the ContactID or InvoiceID included when available. Xero matches on the ID and updates existing records, or creates new ones if no ID is provided.

5. Invoice Line Items: The LineItems field should contain a JSON array. Each line item requires at minimum a Description. Example:

   [
     { "Description": "Consulting services", "Quantity": 10, "UnitAmount": 150.00, "AccountCode": "200" }
   ]

6. Error Handling: Xero returns per-item validation errors in the response body. Zeotap parses these and reports row-level errors with the specific validation message from Xero. Transient errors (429 rate limits, 5xx server errors) are retried automatically with exponential backoff.

Rate Limits

Xero enforces multiple rate limit tiers:

Each API response includes rate limit headers:

• X-MinLimit-Remaining — remaining calls in the current minute
• X-DayLimit-Remaining — remaining calls for the day
• X-AppMinLimit-Remaining — remaining app-wide calls

Zeotap automatically handles rate limiting:

• HTTP 429 responses trigger exponential backoff with retry
• The Retry-After header is respected when present
• Up to 3 retries per request

With batching at 50 records per request, syncing 1,000 contacts requires only 20 API calls, well within the per-minute limit.

Best Practices

• Use OAuth 2.0: Xero access tokens expire after 30 minutes. OAuth 2.0 with offline_access scope lets Zeotap refresh tokens automatically. Static access tokens will stop working after 30 minutes.
• Map the ID field: For upsert and update modes, configure the ID Field in target settings and map a column containing the Xero ContactID or InvoiceID (UUID). Without it, upsert mode creates duplicate records.
• Use PascalCase field names: Xero API fields use PascalCase (FirstName, EmailAddress, AccountNumber). Ensure your field mappings match this casing exactly.
• Validate line items: For invoice syncs, ensure the LineItems column contains valid JSON arrays. Malformed JSON will cause the entire row to fail.
• Monitor daily limits: With only 5,000 API calls per day per tenant, plan your sync schedules to avoid hitting the daily cap, especially if other integrations share the same Xero app.
• Test with a demo company: Xero offers free demo companies for testing. Configure your destination with a demo company tenant ID before syncing to production.

Troubleshooting

Authentication failed: invalid or expired access token

Xero access tokens expire after 30 minutes. If using OAuth 2.0, Zeotap refreshes tokens automatically. If using a static access token, generate a new one. Ensure the offline_access scope is requested during OAuth to enable token refresh.

Tenant ID not found or forbidden

The tenant ID must be a valid UUID for a Xero organisation that the authorised user has access to. Verify the tenant ID by calling the Connections endpoint (GET https://api.xero.com/connections). If you have access to multiple organisations, ensure you are using the correct tenant ID.

Contact name is required

Xero requires a Name field for all contacts. Ensure your field mapping includes a Name column with a non-empty value for every row. The name can be a person’s full name or an organisation name.

Invoice line items validation error

The LineItems field must be a valid JSON array. Each line item requires at minimum a Description field. Common issues:

• The JSON is malformed or not an array
• Line items are missing the Description field
• AccountCode references a code that does not exist in your Xero chart of accounts

Rate limiting (429 errors)

Xero limits API calls to 60 per minute per tenant. Zeotap retries automatically, but persistent rate limits may indicate:

• Too many concurrent syncs targeting the same Xero organisation
• Other applications sharing the same Xero app or tenant
• Very large syncs that exceed the daily limit of 5,000 calls

Reduce sync frequency or batch size if rate limits persist.

Contact or invoice not found in update mode

Update mode requires a valid Xero ContactID or InvoiceID (UUID) for each row. Verify that:

• The ID Field is configured in target settings
• The mapped column contains valid Xero UUIDs (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
• The records exist in the target Xero organisation

Duplicate contacts created in upsert mode

If upsert creates duplicates instead of updating, the ID field is likely not configured or the mapped column contains empty values. Xero identifies existing records by their ContactID, not by name or email. Configure the ID Field and ensure every row includes the Xero ContactID for records that should be updated.

Currency code rejected

Xero only accepts ISO 4217 currency codes that have been enabled in your Xero organisation settings. Navigate to Settings > General Settings > Currencies in Xero and add the required currencies before syncing.