Xero integration

What it does

The Xero integration lets your agency run accounting operations on behalf of your clients without leaving TaskJuice. Connect a client's Xero organization once and you can list and create invoices, contacts, and payments through the Xero Accounting API, react to invoice and contact changes the moment they happen in the bookkeeping ledger, and chain those events into the rest of your workflow.

Connect a Xero account

1. Open your workspace in TaskJuice and navigate to Connections.
2. Choose Xero and click Connect.
3. Sign in to the Xero account that has access to your client's organization and approve the requested scopes (offline_access, openid, profile, email, accounting.transactions, accounting.contacts, accounting.settings).
4. After Xero returns you to TaskJuice, paste the tenant ID for the organization you want to operate on. You can list every authorized tenant by calling GET https://api.xero.com/connections with the access token.
5. TaskJuice returns you to the workspace with the connection ready to use in any workflow.

To revoke access, open the Xero developer portal at my.xero.com/connectedapps, find the TaskJuice app, and disconnect it. See the Xero OAuth 2.0 guide for the full grant flow and the Tenants reference for the connections endpoint.

Triggers

• xero/invoice-event fires when an invoice is created or updated. Each delivery may carry multiple events from the same subscription; TaskJuice fans them out into one workflow activation per event.
• xero/contact-event fires when a contact is created or updated, with the same batched delivery semantics.

Every inbound POST is authenticated by recomputing HMAC-SHA256 over the raw request body using the webhook signing key from your Xero app, base64-encoding the digest, and comparing it with the value Xero sends in the x-xero-signature header. Activations that fail the check are rejected before they reach your workflow. Xero also requires a one-time intent-to-receive validation when you first wire up a webhook: the receiver must respond 401 to a probe with an invalid signature and 200 to a probe with a valid one before the subscription becomes active.

Actions

• xero/list-invoices, xero/get-invoice, xero/create-invoice cover the invoice surface for both sales (ACCREC) and bills (ACCPAY).
• xero/list-contacts, xero/create-contact cover the contact surface for customers and suppliers.
• xero/list-accounts reads the chart of accounts.
• xero/create-payment records a payment against an invoice.
• xero/list-items reads tracked inventory items.

Known limitations

• The Xero Accounting API enforces per-tenant rate limits (60 requests per minute and 5,000 per day per organization). When a 429 status is returned, TaskJuice surfaces it as a retryable error and respects Xero's Retry-After header.
• Connections are scoped to a single Xero organization (tenant). To work across multiple client organizations, create one connection per tenant.
• Webhook events carry resource IDs only, not the resource body. Workflow steps typically follow the trigger with a xero/get-invoice or contact lookup to read the current state.
• Xero treats date fields as the Microsoft JSON /Date(...) format on responses and ISO-8601 strings on requests. Action input fields accept ISO dates and the integration translates them on the wire.