Xero Accounting¶

Overview¶

The Xero Accounting task integrates BaseCloud CRM with Xero (cloud accounting platform), enabling OAuth-authenticated contact and invoice management across multiple organizations with automatic token refresh.

Key Features:

• 8 OAuth Actions: Full CRUD for contacts and invoices
• Multi-Tenant Support: Manage multiple Xero organizations
• Auto Token Refresh: Automatic OAuth token renewal
• Tracking Categories: Two-level project/department tracking
• Contact Auto-Create: Automatic contact creation in invoices
• Global Coverage: 180+ countries, 160+ currencies
• Pagination: Handle large datasets efficiently
• Advanced Filtering: OData-style where clauses

Use Cases:

• Multi-organization invoicing from single CRM
• Automated contact synchronization
• Project-based billing with tracking
• Invoice status monitoring and reconciliation
• Bulk reads that fetch every page automatically

Prerequisites¶

1. Xero Account & App¶

Xero Requirements:

• Active Xero subscription (any plan)
• Xero Developer account: https://developer.xero.com
• OAuth 2.0 app created in Xero Developer Portal

App Setup:

1. Create app at https://developer.xero.com/app/manage
2. Note Client ID and Client Secret
3. Add redirect URI: https://your-basecloud-domain.com/oauth/xero/callback
4. Scopes required:
5. accounting.contacts (read/write contacts)
6. accounting.transactions (read/write invoices)
7. offline_access (refresh token support)

2. BaseCloud App Connection¶

Configure Xero Connection:

1. Navigate to Settings Integrations Xero in BaseCloud
2. Click Connect Xero Account
3. Authorize with Xero (OAuth flow)
4. Select organization(s) to connect
5. Note app_connection_id for use in tasks

Multi-Tenant:

• Can connect multiple Xero organizations
• Each organization has unique xero_tenant_id
• Specify tenant in each task call

3. Tracking Categories (Optional)¶

Xero Tracking Setup:

1. Log into Xero Settings Tracking Categories
2. Create categories (e.g., "Department", "Project")
3. Add options (e.g., Department: Sales, Marketing, Support)
4. Note exact option names for use in invoices

Two categories maximum, because that is Xero's limit — but each can hold any number of options. Categories group invoice line items for reporting and reconciliation, so the names here are what a task writes into when it sets a tracking value.

Outputs¶

Reference fields as {{task_<ID>_<field>}}.

Always emitted¶

Configuration¶

Builder fields¶

The Field column is the label as it appears in the task builder; Key is the name the value is stored under and referenced by.

Action 1: create_contact¶

Create new contact in Xero (never updates existing).

Output Variables:

task_31001_xero_contact_id; // Xero contact UUID
task_31001_xero_contact_name; // Contact name
task_31001_xero_account_number; // Account number
task_31001_xero_first_name; // First name
task_31001_xero_last_name; // Last name
task_31001_xero_email_address; // Email
task_31001_xero_message; // "Contact created successfully"
task_31001_xero_existing; // true if duplicate found, false if new

Duplicate Handling:

• If contact name exists: Returns existing contact with existing=true
• If account number exists: Returns existing contact
• No update performed - use update_contact for changes

Action 2: update_contact¶

Update existing Xero contact.

Output: Same structure as create_contact

Notes:

• Only provided fields are updated
• Empty fields are ignored (not cleared)
• Requires valid Contact ID UUID

Action 3: get_contact¶

Retrieve single contact by ID, number, or name.

At least one search field required

Output:

task_31001_xero_contact = {
  contactID: 'uuid',
  name: 'Acme Corporation',
  accountNumber: 'ACC-001',
  emailAddress: 'billing@acme.com',
  firstName: 'John',
  lastName: 'Doe',
  // ... full Xero contact object
};

Action 4: get_contacts¶

Retrieve every matching contact. All pages are read automatically (1,000 per request); use the Where Filter to narrow large lists.

Output:

task_31001_xero_contacts = [...]  // Array of contact objects
task_31001_xero_pagination = {
  pages: 1,
  totalCount: 45,
  truncated: false  // true when the list was too large to keep in full
}

Where Filter Examples:

• Name.Contains("Corp") - Name contains "Corp"
• EmailAddress=="billing@acme.com" - Exact email match
• AccountNumber.StartsWith("C") - Account starts with C
• UpdatedDateUTC>=DateTime(2024,1,1) - Updated since date

Action 5: create_invoice¶

Create invoice with line items and tracking.

Output:

task_31001_xero_invoice_id; // Invoice UUID
task_31001_xero_invoice_number; // Invoice number
task_31001_xero_invoice_status; // DRAFT / AUTHORISED / PAID
task_31001_xero_invoice_total; // Total amount
task_31001_xero_invoice_sub_total; // Subtotal
task_31001_xero_invoice_total_tax; // Tax amount
task_31001_xero_contact_id; // Contact UUID

Line Amount Types:

• Exclusive: Prices exclude tax (tax added on top)
• Inclusive: Prices include tax (tax within price)
• NoTax: No tax applied

Invoice Statuses:

• DRAFT: Editable draft
• SUBMITTED: Submitted for approval
• AUTHORISED: Approved and locked
• PAID: Fully paid (set automatically by Xero)

Action 6: get_invoice¶

Retrieve single invoice by ID or number.

At least one field required

Output:

task_31001_xero_invoice = {
  invoiceID: "uuid",
  invoiceNumber: "INV-001",
  total: 1150.00,
  amountDue: 1150.00,
  amountPaid: 0,
  status: "AUTHORISED",
  lineItems: [...],
  contact: {...},
  // ... full invoice object
}

Action 7: get_invoices¶

Retrieve multiple invoices with filtering.

Output:

task_31001_xero_invoices = [...]  // Array of invoices
task_31001_xero_pagination = {
  pages: 1,
  totalCount: 23,
  truncated: false  // true when the list was too large to keep in full
}

Action 8: update_invoice¶

Update existing invoice.

Notes:

• Only provided fields updated
• Line items replace all existing (not additive)
• Status changes have restrictions (DRAFTAUTHORISED, cannot unpay PAID)

Real-World Examples¶

Create a Xero invoice from a won deal¶

CRM Trigger  (status changed to "Won")
  └─ Match to Client   look the client up
      └─ Xero          create the invoice

Keep a Xero contact in step with the CRM¶

CRM Trigger  (contact updated)
  └─ Match to Client   look the client up
      └─ Xero          update the contact

Store the Xero contact ID on the client record so the update targets the right contact rather than creating a duplicate.

Confirm to the customer once the invoice exists¶

Webhook In
  └─ Xero    create the invoice
      └─ Email   send confirmation, referencing {{task_31001_xero}}

Troubleshooting¶

OAuth Token Expired¶

Cause: Access token invalid or expired

Solution: Automatic - task auto-refreshes tokens. If persistent:

1. Reconnect Xero in BaseCloud Settings
2. Check refresh token hasn't expired (90 days)
3. Verify app scopes unchanged

Contact Duplicate Detection¶

Cause: create_contact finds existing contact

Solution: This is normal behavior:

• Check {{task_31001_xero_existing}}
• If true, use returned contact ID
• Use update_contact for changes

Tracking Category Not Found¶

Cause: Tracking value doesn't match Xero exactly

Solutions:

1. Check exact spelling in Xero Settings
2. Case-sensitive match required
3. Use "null" to skip tracking (not empty string)
4. Pre-fetch tracking categories to validate

Invoice Number Already Exists¶

Cause: Xero prevents duplicate invoice numbers per contact

Solutions:

1. Use unique numbering: INV-{{timestamp}}-{{client_id}}
2. Check existing invoices first with get_invoices
3. Leave Invoice Number empty for Xero auto-numbering

Line Items Calculation Wrong¶

Cause: Tax type mismatch with line_items_tax_type

Solutions:

• Exclusive: Unit prices don't include tax tax added on top
• Inclusive: Unit prices include tax tax extracted from price
• Verify which format your prices use

Not All Records Returned¶

Cause: Get Contacts and Get Invoices read every page, but stop at about 12 MB of results so the output can still be saved. {{task_31001_xero_pagination.truncated}} is true when that happens.

Solution: Narrow the list with a Where Filter, Statuses or Contact IDs.

Multi-Tenant Confusion¶

Cause: Wrong tenant ID used for operation

Solutions:

1. Store tenant ID per client: {{client_xero_tenant_id}}
2. List available tenants: Use xeroService getTenants
3. Validate tenant access before operations
4. Use separate app connections per tenant if needed

Best Practices¶

OAuth Management¶

1. Token Storage: BaseCloud handles token storage/refresh automatically
2. App Scopes: Request only required scopes
3. Reconnection: Prompt users to reconnect before 90-day refresh expiration
4. Error Handling: Check for 401/403 errors indicating auth issues

Contact Management¶

1. Auto-Create in Invoices: create_invoice auto-creates missing contacts
2. Unique Account Numbers: Use CRM client IDs: C{{client_id}}
3. Sync Strategy: Decide on sync direction (CRMXero, XeroCRM, bi-directional)
4. Duplicate Prevention: Use get_contact before create_contact

Invoice Creation¶

1. Status Workflow:
2. DRAFT: For review/approval workflows
3. AUTHORISED: For immediate dispatch

4. Never set to PAID manually (Xero manages)

5. Tracking Categories:

6. Always use both levels for detailed reporting
7. Standardize category values across CRM

8. Validate values exist before invoice creation

9. Line Items:

10. Use meaningful item codes
11. Consistent account codes (200=Sales, 400=Sales Discounts)
12. Calculate totals in CRM for validation

Performance¶

1. Pagination: Automatic for get_contacts and get_invoices — every page is read
2. Filters: Use where clauses to reduce data transfer
3. Caching: Cache tenant IDs and tracking categories
4. Rate Limits: Xero has rate limits - add delays in bulk operations

Error Handling¶

1. Validation Errors: Parse {{task_31001_xero_error}} for details
2. Retry Logic: Implement retry for transient failures
3. Logging: Always log Xero operations with IDs/numbers
4. Alerts: Notify on critical failures (invoice creation, sync)

FAQ¶

Q: Can I use Xero with multiple organizations simultaneously?

A: Yes, specify different xero_tenant_id per operation. Store tenant IDs in client records or use tenant selector.

Q: How do I get my tenant ID?

A: Use xeroService getTenants() or check app connection details in BaseCloud after OAuth authorization.

Q: Can I update invoice line items after creation?

A: Yes, with update_invoice. Note: Replaces all existing line items (not additive).

Q: What happens if I create invoice with existing invoice number?

A: Xero returns error. Use get_invoice to check first or leave Invoice Number blank for auto-numbering.

Q: How do I handle refunds or credit notes?

A: Create separate credit note in Xero (not currently supported via task). Use Xero UI or request feature addition.

Q: Can I attach files to invoices?

A: Not via task action. Use Xero API directly or Xero UI for attachments.

Q: How long do access tokens last?

A: Access tokens: 30 minutes, Refresh tokens: 90 days. Auto-refresh handled by task.

Q: Can I get invoice PDFs?

A: Not directly. Xero generates PDFs separately. Use Xero API or UI to download.

Q: What's the rate limit?

A: Xero: 60 requests per minute per tenant. Add delays in bulk operations.

Q: How do I query tracking category reports?

A: Use get_invoices with where filter or query Xero Reports API separately.

Q: Can I create quotes instead of invoices?

A: Xero separates quotes from invoices. This task handles invoices only.

Q: How do I handle multiple currencies?

A: Xero supports 160+ currencies per contact. Specify currency when creating invoices.

Q: Can I mark invoices as paid from CRM?

A: No - Xero manages payment status based on payment entry. Use Xero UI or payment API.

Q: What if contact auto-create fails?

A: Task returns error. Create contact manually first with create_contact action.

Related Tasks¶

• BaseCloud Accounting - Internal alternative
• Sage - Alternative accounting integration
• Email - Send invoice notifications
• Loop - Process multiple contacts/invoices
• If Statement - Handle sync logic
• Timer Trigger - Schedule sync/monitoring

Technical Details¶

• Type ID: 31
• Function: taskXero() in automationService.js (lines 7803-8400)
• Service: xeroService.js (1367 lines)
• Library: xero-node (XeroClient)
• Authentication: OAuth 2.0 with auto token refresh
• Output Prefix: task_31001_* or task_31001_xero_*
• Pagination: Automatic, 1,000 results per request
• Rate Limit: 60 requests/minute/tenant