> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequencehq.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Xero
> Sync Sequence invoices in real-time and streamline your accounting process.
## Manage links to Xero
Sequence natively syncs customers and invoices to Xero. When viewing customers or invoices, open the sidebar to see whether an object is linked or synced.
## Start guide
Connecting your Xero account to Sequence is simple. Go to the Connectors tab to get started.
By default, Xero only supports one currency. If you bill customers in multiple currencies, you may need to upgrade your [Xero plan](https://www.xero.com/uk/accounting-software/use-multiple-currencies/).
1. Click the button to connect to Xero.
2. Select the organization to which you want to connect. For testing, it is recommended to connect to a test Xero Demo Company if you are using the sandbox environment.
3. Authorize the connection.
4. Set up your default ledger accounts. See more under ledger accounts [ledger accounts](#ledger-accounts)
## Import customers from Xero
You can import customers from Xero into Sequence in order to speed up your onboarding. In order for an invoice or credit note to be synced the end-customer must be linked to a customer in Xero.
You can import some or all of your customers directly from Xero using the customer import tool. In order to be valid for invoicing in Sequence every customer needs the following:
* A primary address
* A primary email address
The primary address must have the following fields:
* First line
* Town/city
* Postal/zip code
* A valid country (Sequence uses the [alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format)
If a customer is invalid the reason will be provided, allowing you to update the customer in Xero and reload before importing.
If you want to link an existing customer to Xero you can select them in the Sequence customer view and choose to which Xero customer you want to link them.
In Xero, contacts can be customers and/or suppliers. Sequence only imports customer records. For a Xero contact to become a customer, at least one invoice needs to be issued for them.
To add and link a net new customer to Xero and Sequence, create them in Sequence first and then link them to the corresponding contact in Xero. Alternatively, you can create a mock invoice for the contact in Xero to turn them into a customer (at this point, this is the only way to create a new customer in Xero).
## Push customers into Xero
When you create a new customer in Sequence, you can push them into Xero to ensure invoices are synced.
## Ledger accounts
Whenever you create an invoice in Xero each line item is linked to a ledger account. This allows you to categorize the items.
Similarly in Sequence you will need to link each line item to a ledger account in Xero. In order to speed this up you can set a default ledger account in your connector settings. This can be overridden for individual line items.
When you create a new product, set its Xero ledger account. This will apply to any prices and generated line items on invoices.
Set a ledger account for a specific invoice line item:
If you have existing products, billing schedules, invoices and/or credit notes in Sequence at the time when you connect your Xero account then setting a default ledger account will allow the connector to begin working straight away. All existing line items will be linked to the default ledger account. These can then be updated on an individual basis either in a plan, invoice or credit note as shown above.
## Tax
For taxable customers, Sequence will not provide a specific tax code when syncing invoices to Xero. Xero will apply the default tax code for a line item's ledger account.
For tax exempt and reverse charged customers, Sequence will override the tax code to be 'NONE'. You can change this value in your Xero settings.
## Syncing invoices
Whenever an invoice is finalized or sent from Sequence it will automatically get pushed to Xero. The issue and due dates will be set to a dummy date of 1st January 3000 in Xero until you send the invoice, at which point we will update these. This will be overwritten with the correct dates when the invoice is sent. If you subsequently send the invoice via Sequence it will get marked as sent in Xero. Similarly if the invoice is marked as sent in Xero, then the status will be updated in Sequence.
Sending an invoice marks it as sent in Xero. You can navigate from the invoice in Xero to Sequence and vice versa.
Once an invoice has been pushed to Xero you can reconcile it against payments.
For invoices with a Stripe payment link, Sequence will sync the payment status from Stripe (and ignore the payment status in Xero). You need to reconcile your invoice in Xero separately in this case and additionally mark as paid in Sequence if the payment landed directly in your bank account without going via Stripe.
For regular invoices without a Stripe payment link, Sequence will sync the payment status from Xero.
## Syncing credit notes
Whenever a credit note is finalized in Sequence it will automatically get pushed to Xero. The issue and due dates will be set to a dummy date of 1st January 3000 in Xero until you send the credit note, at which point we will update these. This will be overwritten with the correct dates when the credit note is sent. If you subsequently send the credit note via Sequence it will get marked as sent in Xero. Similarly if the credit note is marked as sent in Xero, then the status will be updated in Sequence.
You can navigate from the credit note in Xero to Sequence and vice versa.
## Rounding behaviour in Xero
By default, Xero only supports two decimal points. When an invoice is pushed from Sequence into Xero, line item amounts with more than two decimal points (e.g. £0.0003 per event) are therefore flattened into a line item with a quantity of 1 to avoid discrepancies in the total. For example, an invoice line item with a quantity of 500 and a unit-rate of £0.001 will reflect in Xero as a quantity of 1 with a £0.50 rate.
## Multi-currency transactions in Xero
Xero’s multi-currency feature will auto convert transactions in different currencies. Separate journals for each currency are not required. For tracking different kinds of revenue, you can use tracking categories (similar to tags or labels in Xero) or you can use account codes (specific codes for products).
## Posting revenue recognition journals to Xero
If your account has revenue recognition and the Xero connector enabled, Sequence can post recognition journals straight into Xero as manual journals. You review each month's journals in Sequence, then push them across when you're ready, so there's no CSV to download and import by hand.
### Setting up your ledger accounts
Direct posting uses four Xero accounts. Map each one on the **Account > Revenue recognition** settings page. Most of these already exist in a typical chart of accounts. The clearing account is the one you'll usually need to add.
| Account | Purpose | Typical setup |
| ---------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| **Recognized revenue** | Where revenue lands once it has been earned. This is the income account on your profit and loss. | Usually exists already (for example, Sales). |
| **Deferred revenue** | Holds amounts that are billed but not yet earned. Used for billing in advance. | Usually exists already (for example, Income in advance). |
| **Unbilled revenue** | Holds amounts that are earned but not yet invoiced. Used for billing in arrears. | Often exists already (sometimes called accrued income). If not, add an asset account in Xero. |
| **Clearing** | A temporary holding account that connects Xero's automatic invoice journals to Sequence's recognition journals. | Add a new asset account in Xero. |
Deferred revenue and unbilled revenue are the two holding accounts that revenue moves out of as it is recognized.
To add any account you don't already have, go to **Accounting > Chart of accounts** in Xero and create it as an asset account, then map it in Sequence. You can register more than one Xero account under deferred, recognized, and unbilled revenue. The clearing account is a single account for the whole workspace, since it is a shared temporary holding account.
### The clearing account
When an invoice syncs to Xero, Xero automatically posts its own journal that would recognize the full invoice amount as revenue straight away. The clearing account stops that from happening.
Every invoice and credit note line is routed to the clearing account instead. Sequence then immediately posts an allocation journal that moves the amount out of clearing and into the right deferred or unbilled account for each product. The balance sits in clearing for only a few seconds before it moves on, and the account always returns to zero once allocation is complete.
The clearing account is purely a transit account. In normal operation it should never hold a balance for more than a few seconds, so it is only ever used to track a transaction on its way to the right account.
### How journals reach Xero
Revenue reaches Xero in two waves.
* **Allocation** happens automatically when an invoice or credit note is sent. It distributes the document's full amount across the deferred and unbilled accounts. Nothing hits your profit and loss at this stage.
* **Recognition** happens when you push journals from Sequence, month by month. It moves a slice of revenue out of the deferred or unbilled account and onto recognized revenue.
For example, an invoice covering 12 months in advance allocates the whole amount to deferred revenue when it is sent. You then recognize a portion each month by pushing that month's recognition journals to Xero. Because recognition moves revenue out of the deferred and unbilled accounts, a document has to be synced to Xero first, so that allocation can place its amount there.
### Journal posting mode
The **Journal posting** setting controls the state your journals arrive in.
| Mode | Behaviour |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Draft** (default) | Journals are created in Xero as drafts. Someone reviews and posts them in Xero before they affect the general ledger. This mirrors the review step of the CSV import workflow. |
| **Posted** | Journals are created in their final, posted state and affect the general ledger straight away. |
### Per-product account mappings
The accounts you map in settings are the defaults for the whole workspace. You can override the deferred, recognized, and unbilled accounts on individual products, so revenue for each product lands in its own Xero accounts. Set these on the product itself.
### Pushing journals and tracking sync status
You push recognition journals from **Revenue recognition > Journal reports**. Open the **⋯** menu in the top right and choose **Push to Xero**, then pick the periods you want to push.
The dialog lists each accounting period you can push, grouped by month, from your account period lock date up to the end of the last full month. The current part-month is left out until it completes. Each period carries a status:
| Status | Meaning |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Not synced** | The period has never been pushed to Xero. |
| **Syncing** | A push is in progress. |
| **Synced** | Every journal for the period has posted, with nothing outstanding. |
| **Changed** | The period was pushed before, but new journals have appeared since. For example, a new invoice landed in an already-synced month. |
| **Failed** | At least one journal in the period could not be posted. |
Pushing runs in the background, so you can leave the page while it works. Re-pushing is safe: Sequence only posts what has changed, so a synced period posts nothing and a changed period posts just the new entries, without duplicating what's already in Xero. If a period fails, you can retry it.
Each push is scoped to one currency at a time, matching the CSV export. Journals are restated into your Xero organization's base currency using the original document's exchange rate, so they reconcile in your base currency. If you bill in more than one currency, push each currency separately.
Invoices and credit notes must be synced to Xero before you push recognition journals. Syncing a document is what allocates its amount into the deferred or unbilled account, and recognition moves revenue out of those accounts. If a document has not synced, there is nothing to recognize from.
Once journals have posted to Xero, Sequence marks the period as synced and will not push the same journals again. If you delete the posted journals in Xero and need them re-pushed, contact Sequence support to reset the period.
The clearing account cannot be overridden per product. It is a single shared account for the whole workspace.
Product mappings are read when a recognition charge is created. Updates apply to new charges; existing charges keep the mapping they were created with.
## Revenue recognition CSV export
If you'd rather review journals outside Sequence before they reach Xero, or you don't use direct posting, you can export them instead of pushing them.
The Xero-formatted journal export produces a CSV that's directly importable as a **Manual Journals** file in Xero. Columns follow Xero's published template (`*Narration`, `*Date`, `Description`, `*AccountCode`, `*TaxRate`, `*Amount`, plus tracking columns).
See [Journal reports](/revenue-recognition/journal-report) for filters, async download, and the full column list.
### Aggregation levels
The export supports daily, monthly, and per-customer-per-product-monthly aggregation:
| Aggregation | Behaviour |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Daily** | One entry per journal per day. The default; produces the most detail. |
| **Monthly** | Daily journals collapsed into monthly totals per journal grouping. |
| **Monthly by customer and product** | Monthly totals scoped to each customer and product combination. Useful for accounts that want a finer-grained monthly rollup than a single total per ledger account. |
### Sign convention
Sequence's internal ledger uses an explicit `Direction` (Debit or Credit). When generating the Xero export, the amount is signed according to each Xero account's **normal balance**:
* Debiting a debit-normal account produces a positive amount.
* Crediting a credit-normal account produces a positive amount.
* Crediting a debit-normal account produces a negative amount.
* Debiting a credit-normal account produces a negative amount.
This matches what Xero expects on import, so journals load without manual sign correction.
### Rounding
Amounts are rounded to two decimal places. Trailing decimal zeroes are stripped where appropriate to match Xero's display.
### Credit notes without an accounting date
If a credit note has no accounting date set (e.g., it pre-dates the field being required), the export falls back to the credit note's **issue date** for the journal date.