> For the complete documentation index, see [llms.txt](https://docs.younium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.younium.com/erp-and-accounting-integrations/xero.md).

# Xero

## Overview

The Xero integration connects Younium to Xero accounting for account and product synchronisation and outbound sales invoices. When posting is enabled, Younium creates a draft accounts receivable invoice or credit note in Xero when an invoice is posted in Younium, and stores the Xero document number on `Invoice.ExternalERPId`.

Authentication uses Xero OAuth 2.0 with a stored tenant id.

***

## Authentication

You connect Younium to Xero by authorising it from Xero itself: sign in, choose the Xero organisation to connect, and approve the access Younium asks for. Younium remembers which organisation you chose and renews its own access from then on, so the connection stays live without reauthorising.

***

## Activation and deactivation

Connect through the Xero OAuth flow; Younium stores the resulting tokens and tenant against the integration settings. Each authorisation attempt is single-use: Younium checks the callback against the connection attempt that started it, so completing the same authorisation link a second time, or returning to Xero on a stale or bookmarked link, fails and the connection must be started again from Younium. **Deactivating** removes those settings and stops invoice posting; documents already in Xero are untouched.

Saving the settings turns invoice posting on or off to match your choice. Deactivating removes the connection and stops invoice posting; documents already in Xero are untouched.

***

## Custom fields

| Entity  | Custom field name | Type | Notes                                             |
| ------- | ----------------- | ---- | ------------------------------------------------- |
| Account | `Xero Tax Code`   | List | List key sent as Xero `TaxType` on lines when set |

***

## Eligibility and filtering

* Lines sorted by product line number; `HideZeroAmountRecurring` and `HideZeroAmountUsageAndMeasurementLines` applied.
* Credit path when `Invoice.TotalAmount.Amount < 0` → Xero credit notes API.
* Account must have `ExternalERPId` (Xero contact GUID).

***

## Field mapping — posted invoice (Younium → Xero)

### Invoice / credit note header

| Younium field                                            | Xero field                                             |
| -------------------------------------------------------- | ------------------------------------------------------ |
| `Account.ExternalERPId`                                  | `Contact.ContactID` (GUID)                             |
| —                                                        | `Type` = `ACCREC` (invoice) or `ACCRECCREDIT` (credit) |
| `Invoice.InvoiceDate`                                    | `Date`                                                 |
| `Invoice.DueDate`                                        | `DueDate`                                              |
| `Invoice.YourReference`                                  | `Reference` (debit invoices only)                      |
| —                                                        | `Status` = `DRAFT`                                     |
| Derived rate from subtotal base/amount or `ExchangeRate` | `CurrencyRate`                                         |
| `Currency.Code` (mapped via `GetCurrencyXero`)           | `CurrencyCode`                                         |
| `Invoice.Notes`                                          | Extra `LineItem` with description only                 |

Account list custom **Xero Tax Code** value → list item **Key** → line `TaxType` when present.

### Line item

| Younium field                                                 | Xero field    |
| ------------------------------------------------------------- | ------------- |
| `ChargeDescription` + service period + notes                  | `Description` |
| `GetPricePerUnitAndQuantity().Quantity`                       | `Quantity`    |
| `GetPricePerUnitAndQuantity().Price` (negated on credits)     | `UnitAmount`  |
| `OrderProductCharge.ExternalERPId` or product `ExternalERPId` | `ItemCode`    |

### Write-back (Younium)

| Xero field                           | Younium field           |
| ------------------------------------ | ----------------------- |
| `InvoiceNumber` / `CreditNoteNumber` | `Invoice.ExternalERPId` |

***

## Post invoice workflow

**Runs when:** an invoice is posted in Younium.

Throttled (`ThrottledIntegration.Xero`). Creates invoice or credit note batch via Xero Accounting API.

***

## Import jobs

Import Xero accounts and products; export Xero accounts to Younium.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.younium.com/erp-and-accounting-integrations/xero.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.