# Send manual journals to Xero

> Post sanda's numbers to Xero as manual journals, such as a month-end work-in-progress accrual. Each journal must balance, and a changed one is updated in place.

A push to Xero turns sanda's numbers into manual journals in a Xero organisation: a month-end work-in-progress accrual, wages owed at the end of a period, revenue recognised as jobs progress. The numbers come from your [semantic fluid](https://docs.sanda-os.com.au/semantic-fluid), so they are the figures your team already agreed on, and the journals land in your books as drafts for your accountant to post, or posted, as you choose.

Each run sends only the journals that changed since Xero last accepted them. A journal sanda made is updated in place when its lines change, and withdrawn when nothing is left on it. sanda never touches a journal it didn't make.

:::note
Xero manual journals is under **Choose a destination** on the **Push** tab once sending journals to Xero is switched on for your console. If the card isn't there, ask sanda support.
:::

## Before you start

- **A Xero user and plan that may make manual journals.** sanda writes as the user who connects it. Xero lets an app make and change manual journals only where the organisation's Xero plan includes them, and only for a user with the **Adviser** role, or a **Standard** user with reporting permissions. sanda checks this when you save a push, and again before every run.
- **The accounts the journals post to, set up in Xero.** A journal's lines post to accounts already in your chart of accounts. sanda doesn't make accounts, tracking categories or tax rates.
- **A date for each period in your warehouse.** Rows with the same date become one journal, so the rows a push reads need a date at the grain you want: a month end, a week end, a day.
- **Your accountant's agreement.** A journal changes your books. Agree with whoever signs them off which accounts a push posts to, whether it posts or leaves drafts, and who looks at the preview before the first run.

## Connect a Xero organisation

:::steps
1. **Open Push.** Go to **Data · Streams**, open the **Push** tab and press the **Xero manual journals** card under **Choose a destination**.
2. **Sign in to Xero** as the user sanda writes as, and choose the organisation the journals go to. sanda connects one organisation at a time: if you tick several, it keeps the newest and removes its connection to the others.
3. **Allow sanda.** Xero shows what sanda asks for: to make manual journals, and to read the organisation's settings, accounts, tracking categories and tax rates. Nothing else.
4. **Back in sanda**, a line at the top of the page says the organisation is connected, and a new push's editor is open on it. To connect another organisation, press **Connect Xero** beside Xero under **Connected** and choose it.
:::

The organisation is listed under **Connected** on the **Push** tab, with **Disconnect**, and **Connect again** once Xero stops accepting the connection. One connection to an organisation serves every push to it.

sanda keeps the connection encrypted, and it is never shown, in the console or to sam. Xero ends a connection that goes unused for 60 days, so sanda keeps it alive: a push that runs once a month still finds its organisation connected.

**Disconnect** forgets the connection, and removes sanda's connection to the organisation at Xero too, unless another sanda workspace still writes to the same organisation through it. The pushes to it stay, and run again once you connect it.

## Create the push

The editor is the one every push uses (see [create a push](https://docs.sanda-os.com.au/streams/create-a-stream-out)), with Xero's form where it writes:

:::steps
1. **Open the editor.** Press the **Xero manual journals** card once your organisation is connected, or **New push**.
2. **Choose when it runs, and name it.** **When it runs** comes first, then **Name** and an optional **Description**. A month-end push often runs daily, so a journal is ready as soon as the month's figures are.
3. **Choose where it writes.** Under **Where it writes**, pick the **Xero organisation**.
4. **Choose the journal date.** Under **What it sends**, **Journal date** is the column or dimension that holds each row's date. Rows with the same date become one journal. A date and time counts as its day in the push's **Time zone**.
5. **Set up the journal lines.** Under **Journal lines**, each row of the table is a line every journal gets from its rows (see [journal lines](#journal-lines)). Press **Add a line** for each one more.
6. **Choose how it sends.** Under **How it sends**, set the **Narration**, the **Status**, the **Amounts** and the rest (see [how it sends](#how-it-sends)).
7. **Narrow the rows.** Under **Which rows**, press **add a condition** and set where the journals start on **Journal date** (see [which periods it reads](#which-periods-it-reads)).
8. **Save.** Press **Save push**. The push opens with **Preview the next run** already read, and nothing has been sent.
:::

Changing the organisation, or where the journal date comes from, starts the push over: the next run sends every journal again. Where the new source gives a date the push already made a journal for, it finds that journal by its narration and updates it. The journals it made for dates the new source doesn't give, or in another organisation, stay in Xero, posted or drafted beside the new ones, until you void or delete them there: moving **Journal date** from month ends to week ends, for instance, leaves every month-end journal in your books. The editor says so before you save. Any other change, such as an account, the narration or the status, updates the journals sanda made in place on the next run.

### Journal lines

Every journal takes the same lines from its rows: each row gives one line for each line in the table, and lines that are the same in every way but their amount are added together. A push has at least 2 lines and at most 20.

| Column | What it takes |
|---|---|
| **Account** | An account from your chart of accounts, chosen from Xero's list as Xero names it, such as **Work in progress (631)**. Bank accounts, and accounts receivable, accounts payable and retained earnings, aren't listed: Xero takes none of them on a manual journal. GST and wages payable accounts are |
| **Side** | **Debit** or **Credit** |
| **Amount** | A sanda value: a metric, or a column. It is rounded to the cent. A line whose amount is empty or zero on a row is left out |
| **Description** | Optional. A fixed value, or a column or dimension |
| Your tracking categories | One column for each of the organisation's active tracking categories, at most 2, each named as Xero names it, such as **Region**. A fixed option from the category's list, or a column or dimension whose value is one of the category's active options by name. A column is left out when the organisation has no such category |
| **Tax rate** | Only when **Amounts** is **Tax inclusive**: a tax rate from Xero's list, or nothing, for the account's own |

Debits and credits must balance on every journal. sanda checks each one before it sends. A difference of up to 1 cent a line, which rounding each line to the cent can leave, goes on the largest line of the side that is short. A journal still out of balance isn't sent, and the run says by how much.

One journal has at most 500 lines once its rows are spread over the table. A journal that would have more isn't sent: group the push's rows by something coarser, such as cost centre rather than job.

### How it sends

| Setting | What it does |
|---|---|
| **Narration** | Each journal's narration is this, then its date: **Month-end WIP · 2026-09-30**. It starts as the push's name while you type one for a new push, until you change it. It has to be unique to this push in this organisation, and can't hold double quotes |
| **Status** | **Draft, for an accountant to post**, or **Posted**, straight into the ledger |
| **Update journals an accountant has posted** | Off: once a journal is posted in Xero, sanda leaves it as it is and says so. On: sanda updates a posted journal when its lines change, and voids one with nothing left on it. A push whose **Status** is **Posted** updates its own posted journals either way |
| **Amounts** | **No tax**: each amount is posted as it stands, with no GST. **Tax inclusive**: each amount includes tax, which Xero works out from the line's **Tax rate**, or the account's own when the line has none. Amounts that exclude tax aren't offered |
| **Show on cash basis reports** | Off keeps an accrual out of cash basis reports, where it has no cash to stand for |
| **Time zone** | A journal's date is its day in this time zone, for a value that is a date and time |

Each journal also carries a link back to the push in sanda, which Xero shows on the journal, so whoever opens it in Xero can see where it came from. sanda finds its own journals by their narration and that link, so it never takes over a journal another push or workspace made.

### Which periods it reads

A push's rows decide which journals exist. A journal sanda made whose rows have gone, because no row has its date any more, is withdrawn, like one whose lines all come to zero. So set where the journals start with a fixed date, such as **Journal date is on or after** the first day of this financial year.

:::caution Use a fixed start, not a moving window
A condition that moves with each run, such as **last 3 months**, would leave each month's journal as the window moves past it, and sanda would withdraw that journal from your books. The save warns about a moving window, and about a push with no condition on **Journal date** at all.
:::

## What a run does

Each run sends at most 50 journals, one at a time, for at most 7 minutes. When more have changed, the newest go first: this month's journal before last year's, and a period your books have locked never keeps an open one waiting. What is left waits for the next run, so a first run over years of periods takes several runs to send them all.

| Each journal | What sanda does |
|---|---|
| New | Looks for it in Xero by its narration and the push's link, in case an earlier run made it but never heard back, and makes it if it isn't there |
| Changed | Reads it in Xero, then updates it in place with every line, so Xero is left with exactly the lines the push sends |
| Nothing left on it (every line zero, or no row with its date) | Withdraws it: a draft is deleted, and a posted journal is voided only when **Update journals an accountant has posted** is on, or the push posts |
| Voided or deleted in Xero | Made again, as a new journal, the next time sanda sends it: when its lines change, or when you press **Send everything again**. sanda finds that a journal was voided or deleted only when it sends that journal |
| Posted in Xero | Left as it is, and said, unless **Update journals an accountant has posted** is on, or the push's **Status** is **Posted** |
| On or before the organisation's lock date | Not sent, and counted as **too old to send**. A user who may approve transactions before the period lock date can post up to the end-of-year lock date instead |

sanda reads what Xero saved: a journal Xero refused is said in Xero's own words, a journal saved with a warning keeps the warning on the run, and a journal whose saved lines differ from the ones sent, such as an account Xero dropped, is refused so you can check it. Rows with no journal date can't be placed, and the preview counts them as **No journal date**.

### Xero's daily allowance

Xero gives sanda a number of API calls a day in each organisation, and says with every answer how many are left. They are sanda's own: another app connected to the organisation, such as a bank feed or payroll, has an allowance of its own and never spends them. Every push to the organisation shares them, with the editor's lists and the checks a save makes. A run needs 2 calls a journal, and 4 to read the organisation first. sanda leaves the last 50 calls of the day for the editor and the other pushes: a run that would spend into them sends nothing, and says so, and the next run carries on. A run that meets the end of the day part-way records what went.

**Send everything again** on the push sends every journal it reads again, over the next runs, updating the ones Xero has and making again any voided or deleted there. It costs 2 API calls a journal (see [send everything again](https://docs.sanda-os.com.au/streams/runs#send-everything-again)).

## Personal details

A journal carries the amounts you map, and any description or tracking value you take from your rows. Everyone who can see journals in the organisation sees them, so map only what your accountant and your team should see in your books: a job number in a description rather than a customer's name, for instance. A push to Xero sends no hashed details and asks for no consent. Xero is your own books, not an advertising network, so the rule that keeps some sources' data from advertising networks doesn't apply to it (see [what a push never does](https://docs.sanda-os.com.au/streams/out#what-a-push-never-does)).

## When something goes wrong

| What you see | What to do |
|---|---|
| Xero won't let sanda create or update manual journals in this organisation | Check that the organisation's Xero plan includes manual journals. If it does, give the user who connected sanda the Adviser role, or reporting permissions, in Xero, or press **Connect Xero** under **Connected** and sign in to the same organisation as a user who has them |
| That account isn't one a manual journal can use in this organisation | Choose another account: bank accounts, accounts receivable, accounts payable and retained earnings can't take a manual journal |
| Another push writes journals with this narration to this organisation | Give this push a narration of its own |
| An account, a tracking category or a tracking option is no longer active in Xero | Nothing was sent. Open the push, choose it again and save, or make it active in Xero |
| Tracking option "…" isn't active in Xero | A row names an option the tracking category doesn't have, or has archived. Add it in Xero, or correct the rows |
| Debits are … and credits … on this journal, so it doesn't balance | Check the values the debit and credit lines read. The journal is sent once it balances |
| This journal would have … lines | Group the push's rows by a coarser dimension |
| This journal is larger than Xero takes in one request | Shorten the descriptions its lines take from your rows, or group the rows by a coarser dimension so it has fewer lines |
| This journal is posted in Xero, so sanda left it as it is | Turn on **Update journals an accountant has posted**, or void the journal in Xero: sanda makes a new one the next time it sends it, when its lines change or when you press **Send everything again**. A journal refused on every run is held after 3 tries, and voiding it in Xero doesn't release it on its own |
| Xero refused the journal, in its own words | Xero's message comes first. A journal Xero refuses on every run is held after 3 tries, until it changes (see [held records](https://docs.sanda-os.com.au/streams/runs#held-records)) |
| Xero saved different lines from the ones sanda sent | Check the journal in Xero: an account or a tracking option may not be what Xero expected |
| Xero's books are locked up to a date, so this journal wasn't sent | Counted as too old to send, not as a failure. Narrow **Which rows** to the periods still open |
| Xero's daily API limit for this organisation is used up | Nothing to do: the next run carries on with what is left |
| Xero no longer accepts sanda's connection | Someone removed sanda's access in Xero, the user's role changed, or the connection lapsed. The push waits until you press **Connect again** under **Connected** and sign in |
| Connect the organisation again and allow sanda to make manual journals | The connection lost a permission sanda needs. Press **Connect again** and allow it |

A failed run counts toward the push pausing itself, as any push's does. See [runs](https://docs.sanda-os.com.au/streams/runs).

### If Connect fails

- **Xero connected sanda to a practice rather than an organisation.** Connect again and choose an organisation when Xero asks: a push writes to an organisation's books.
- **Xero won't take another connection from sanda's app just now.** An organisation can connect only so many apps Xero hasn't certified, and sanda's app has a limit of its own. Nothing was connected: contact sanda support.
- **Xero asked whether to allow sanda and the answer was no.** Nothing was connected. Start again and allow it.
- **Connecting Xero isn't switched on for this workspace yet.** Sending journals to Xero isn't switched on for your console. Ask sanda support.
- **You ticked several organisations.** sanda connects one at a time: it kept the newest and removed its connection to the others. Press **Connect Xero** again for each of the others.

## Limits

- One push maps at most 20 journal lines, and one journal has at most 500 lines.
- One line carries at most 2 tracking categories.
- One run sends at most 50 journals, for at most 7 minutes.
- One push reads at most 50,000 rows.
- A run leaves the last 50 of sanda's daily API calls in the organisation for the editor and the other pushes to it.

:::links
- [Push](https://docs.sanda-os.com.au/streams/out): Every way sanda's numbers go out to the systems your team works in.
- [Create a push](https://docs.sanda-os.com.au/streams/create-a-stream-out): The editor every push uses, and its preview.
- [Runs](https://docs.sanda-os.com.au/streams/runs): What each run did, and why a journal was refused, held or withdrawn.
:::