Integrations

Xero Integration

Connect Paid to Xero and every invoice Paid issues lands in Xero against the right customer, revenue account, and tax code. The Paid PDF is attached to the Xero invoice, and the Xero invoice status follows the Paid invoice as it moves through draft, posted, and voided. Payment status is handled by a separate path — recording a payment against a Paid invoice does not on its own mark the Xero invoice as paid.

Before you connect

You will need:

  • A Xero organization with at least one active revenue-class account in your chart of accounts. Most tenants ship with 200 - Sales by default.
  • An admin user on both Paid and Xero. The Xero admin needs permission to approve new third-party apps.

1. Connect your Xero organization

Go to Settings → Integrations and find the Xero card. Click Connect.

Xero will ask you to pick the organization you want to link and approve the integration. Paid needs permission to read your chart of accounts and tax rates, read and write customers, and read and write invoices and payments.

Once you approve, you are sent back to Paid and the Xero card shows a green Connected badge with the linked organization name.

To switch to a different Xero organization, disconnect first and then connect again. The disconnect step revokes the prior grant on Xero’s side, so the next authorize prompt lets you pick a different organization.

2. Configure mapping

From the Xero card, click Configure Xero mapping. The page has two tabs — Customers and Products — and a Defaults card at the top that applies to both.

Integration defaults

These apply to every invoice line that does not have a product-specific mapping.

  • Default revenue account. The Xero account Paid posts invoice lines to. Leave it on “Use Xero default (200)” to fall back to the seed Sales account, or pick any active revenue account from your chart.
  • Default zero-tax code. The Xero tax code Paid uses on lines whose tax amount is zero. The dropdown only shows zero-rated codes from your tenant — typically “No VAT” or “No Tax”, plus any other zero-rated alternatives. The tenant’s default zero rate is pre-selected.

Why is there no setting for taxed lines? Paid already calculates the tax amount on every line (for example through Avalara). For taxed lines, Paid lets Xero apply the revenue account’s configured rate automatically, which lines up with the amount Paid sent. You don’t need to pick a taxed rate code by hand.

Customers tab

The Customers tab lists Xero contacts and shows which Paid customer each contact is linked to.

  • Linked contacts show the matching Paid customer on the row.
  • Unlinked contacts can be matched to an existing Paid customer from the dropdown.
  • Search helps you find the right Xero contact or Paid customer when the list is long.
  • Automatic linking. When the integration is connected, new Paid customers are pushed to Xero in the background. Manual linking is mainly needed for pre-existing records or the rare case where the background sync didn’t go through.

Products tab

Use this tab when different products should post to different revenue accounts in Xero.

  • Apply to all unmapped bulk-assigns a Xero account to every product that doesn’t yet have a mapping.
  • Per-row dropdown overrides a single product. Selecting “Use integration default” clears the override and falls back to the integration-wide default.
  • Archived products stay in the list so renewal and amendment invoices for an archived product still post to the right account.

Click Save when you’re done. Paid validates every code against your live Xero chart of accounts before saving, so an invalid code is caught here rather than when the next invoice tries to sync.

Cross-referencing records between Paid and Xero

After a customer or invoice syncs, the Xero identifier is shown as External ID on the corresponding Paid detail page sidebar. You can click the copy icon to put it on your clipboard for finding the record in Xero or audit reports. If sync hasn’t completed yet, the field shows “Pending sync” with a Retry button.

Connecting Xero will overwrite the customer’s External ID with the Xero contact identifier on the next sync. If your team was using External ID to store a value from another system (Salesforce, HubSpot, an internal SKU, etc.), back that mapping up before you connect. You can still edit the field by hand after sync if your workflow needs a different value.

When things go wrong

Audit log

Successful syncs and permanent failures are recorded so finance can reconcile a billing period without sampling individual records. Each entry captures the Paid record, the Xero ID (on success), and the failure reason (on error). Temporary issues are retried in the background without creating a log entry for every retry.

Failure alerts

When a sync fails for a reason that won’t fix itself (an invalid code, archived account, malformed customer data), Paid sends a Slack notification with a link straight to the affected record so you can fix it and retry. Temporary issues like network blips are retried automatically in the background and don’t trigger an alert.

Retrying

If a customer or invoice didn’t sync:

  • Click Retry on the sidebar of the affected record.
  • Or wait — most edits to the record (status change, payment, etc.) re-trigger the sync automatically.
  • For an invoice failure caused by a customer issue, fix the customer in Paid first and retry the customer sync. The next invoice retry will then succeed.

Switching organizations or refreshing the connection

  1. Open the Xero card on Settings → Integrations.
  2. Click Disconnect and confirm. This revokes the authorization in Xero and removes the Xero-specific mappings from Paid.
  3. Click Connect again. You can pick the same organization (to refresh the connection) or a different one.

Disconnecting clears Xero-side mappings — customer links, invoice links, and per-product account overrides — for the disconnected tenant. If you reconnect to the same organization later, you’ll need to re-create those mappings. Reconnecting to a different organization is the usual case, since codes from one chart of accounts wouldn’t match another anyway.

What’s not supported yet

  • One Xero organization per Paid organization. If you operate multiple Xero entities (one per legal entity) you can’t route invoices to different tenants from the same Paid organization today.
  • Customer edits don’t push to Xero after the initial link. Updates to a customer’s name, address, VAT number, or contact details in Paid don’t propagate to the existing Xero contact. The billing address on the Xero contact is refreshed each time you send an invoice, but other fields are not.
  • Credit notes and refunds aren’t synced yet. They’re on the roadmap once base invoice sync is solid.
  • Mixed-jurisdiction invoices. When a single invoice spans multiple tax jurisdictions with different rates, all lines post to the same Xero account and Xero may show the account’s default rate against every line. The per-line tax amounts Paid sent are still correct — Xero may add a small footnote to reconcile the rate column against the amount.

Troubleshooting

The dropdown shows “Loading accounts…” and never finishes. Paid caches your Xero chart of accounts and tax rates for a few minutes per organization. If the fetch fails, you’ll see an error toast. Try again after a minute. If it keeps failing, disconnect and reconnect.

An invoice failed to sync with “Account code is not valid”. The mapped account is no longer active in Xero (archived or removed). Update the mapping on the Xero mapping page and retry the sync.

A customer shows “Pending sync” indefinitely. Click Retry on the customer sidebar. If retry fails again with a Xero-side rejection (visible in the Slack alert), the customer’s source data was rejected — common causes are a missing name, malformed email, or invalid VAT number. Fix the Paid customer and retry.

My tax rate isn’t in the zero-tax dropdown. Paid only lists rates that are active in Xero, applicable to customer invoices, and exactly 0 percent. Confirm in Xero that the rate is active and zero-rated.

The Xero invoice has a different number than the Paid invoice. That’s intentional. Paid lets Xero auto-generate its invoice number to avoid number collisions on retries, and writes the Paid number into the Reference field on the Xero invoice so you can still cross-reference them.

The Xero contact name doesn’t match the Paid customer. Paid uses the customer’s legal name when available, otherwise the display name. If the Xero contact name is wrong, edit it directly in Xero — Paid doesn’t push later customer edits.