# Build a Live Actuals Model Using Xero

This guide explains how to connect Model Reef to Xero and build a live actuals model that stays current as your ledger updates. You will import your Chart of Accounts, map accounts into variable types and categories, and combine actuals with forward-looking assumptions.

## Before you start

You should have:

* A Xero organisation with appropriate access rights.
* A Model Reef workspace where you can create models and integrations.
* A sense of how you want to group accounts into reporting categories.

If you are new to imports, see:

* **Xero Integration**
* **Importing and Data Inputs overview**

## What you will build

By the end you will have:

* A Model Reef model connected to Xero.
* COA accounts mapped into Revenue, COGS, Opex, Staff, Assets, Liabilities, Equity.
* Historical actuals imported into the Data Library and variables.
* A process for refreshing actuals on demand and reviewing updated statements.

{% stepper %}
{% step %}

### Create a new model for live actuals

Start by creating a dedicated live actuals model, for example:

* `Company - Live Actuals - Xero`.

Set:

* Currency to match your Xero organisation.
* Periodicity to monthly unless you have a clear reason to use a different basis.
* Model start date to cover at least the last year you want to track.

This model will become the anchor for financial actuals.
{% endstep %}

{% step %}

### Connect Model Reef to your Xero organisation

In the model integration settings:

* Choose **Connect to Xero**.
* Follow the OAuth prompts to authorise access to your Xero organisation.
* Confirm that the correct entity is selected if you have multiple Xero files.

Once connected, Model Reef can request:

* Chart of Accounts.
* Historical P\&L and Balance Sheet totals by period.
  {% endstep %}

{% step %}

### Import and map the Chart of Accounts

Use the Xero import flow to bring in your COA:

* Fetch the list of accounts.
* Map each account to a Model Reef type and category, for example:
  * Sales accounts to Revenue categories.
  * Direct costs to COGS.
  * Overheads to Opex.
  * Wages and related oncosts to Staff.
  * Balance Sheet accounts to Assets, Liabilities or Equity.

Model Reef will propose mappings; you should review and correct any that are obviously wrong.

These mappings will be reused each time you refresh data.
{% endstep %}

{% step %}

### Import historical actuals

With the mapping in place:

* Run an initial **Actuals import** from Xero.
* Specify the historical horizon, for example the last two to three years.
* Model Reef will:
  * Pull periodic totals per mapped account.
  * Create Data Library entries for each series.
  * Create variables attached to the correct branches and categories.
  * Compile statements for the historical period.

Check P\&L and Balance Sheet views to ensure totals match your expectations from Xero.
{% endstep %}

{% step %}

### Configure forward looking assumptions

Your live actuals model can also include a forecast:

* For each major line, decide whether:
  * It is purely actuals (historical only).
  * It requires a forward forecast.
* For forecast lines:
  * Add drivers for growth, margin or cost per unit.
  * Use ML or regression based presets if you want forecasts grounded in historical patterns.
  * Ensure that forecast logic begins after the latest actual period.

Model Reef keeps historical and forecast behaviour conceptually separate but shows them as a continuous time series in outputs.
{% endstep %}

{% step %}

### Review the live financial statements

Open:

* **P\&L** to see historical results and future projections.
* **Balance Sheet** to confirm that opening balances and key accounts look correct.
* **Cashflow Statement** and **Cash Waterfall** to understand cash patterns.

If classes of accounts are mis grouped, adjust the mapping and re import or remap variables.
{% endstep %}

{% step %}

### Establish a refresh and review cadence

To keep the model live:

* Decide how often to update actuals, for example:
  * Monthly when the books are closed.
  * More frequently for high frequency cash tracking if needed.
* On each refresh:
  * Run the Xero import.
  * Review any new accounts that appear and map them.
  * Confirm that statements still look consistent.

Forward forecasts will automatically update based on the latest historical data and drivers.
{% endstep %}

{% step %}

### Use the live model as a base for scenarios

Because scenarios are separate models, you can:

* Duplicate the live actuals model to create:
  * A planning or budget model.
  * Downside or upside scenario models.
* In those copies, override drivers and assumptions while keeping the historical actuals imported from Xero.

This keeps the live actuals model as a clean anchor and lets scenarios diverge as needed.
{% endstep %}
{% endstepper %}

## Check your work

* Xero accounts are mapped correctly to Model Reef types and categories.
* Historical statements in Model Reef match those in Xero within materiality thresholds.
* Forward looking assumptions begin in the correct periods and do not overwrite actuals.
* The refresh process is simple enough to repeat every reporting cycle.

## Troubleshooting

<details>

<summary>New accounts appear with no mapping</summary>

After adding accounts in Xero, revisit the mapping screen and classify them before running imports.

</details>

<details>

<summary>Totals differ from Xero reports</summary>

Check for date range mismatches, account exclusions or mapping errors.

</details>

<details>

<summary>Forecast appears to move unexpectedly after refresh</summary>

Confirm that forecast drivers and settings have not changed, and review whether new actuals shifted starting points.

</details>

## Related guides

* [Logistics, Transport & Fleet](/use-cases/logistics-transport-and-fleet.md)
* [Xero Integration](/help/xero-integration.md)
* [Debt Service Logic](/help/financial-outputs-and-valuation/debt-service-logic.md)
* [Entering Schedules](/syntax/how-input-fields-work/entering-schedules.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.modelreef.io/how-tos/data-workflows-and-automation/build-a-live-actuals-model-using-xero.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.