> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getlago.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Xero
> Lago seamlessly integrates with Xero, enabling real-time synchronization of billing data with your preferred accounting tool.
**PREMIUM ADD-ON** ✨
This integration is available upon request only. Please **[contact us](mailto:hello@getlago.com)** to get access to this premium integration.
## Connecting Lago to Xero
To fully integrate Lago with Xero, start by connecting your Lago instance to a new Xero connection.
You can have an unlimited number of Xero connections. First, link your Xero account to Lago.
Once connected, activate the specific syncs and actions required for your use case.
This ensures that your Lago instance is properly configured to communicate with Xero, enabling seamless data synchronization and management.
1. In Lago, navigate to **Integrations > Xero**;
2. Create a **new Xero connection**;
3. Assign a unique **name** and **code** to the connection; and
4. Use OAuth2 to **grant access** to your Xero instance.
There you go, Lago is fully connected to Xero!
## Enable actions and syncs
Here is a list of syncs and actions that Lago uses with Xero. Some are mandatory, while others are optional:
* `Accounts`: Fetch account data from Xero *(mandatory)*;
* `Customers`: Syncs or fetch customer data from Xero *(mandatory)*;
* `Items`: Fetch item data from Xero *(mandatory)*;
* `Invoices`: Syncs invoice data to Xero *(mandatory)*;
* `Credit Notes`: Syncs credit note data to Xero *(optional)*; and
* `Payments`: Syncs payment data to Xero *(optional)*.
## Mapping items between Lago and Xero
To sync invoices, credit notes and payments to Xero, Lago maps each Lago object to a corresponding Xero object (one-to-one). You can define mappings per Lago entity when different entities require distinct Xero items. If the same mapping applies across entities, configure a default mapping. It will be used for any entity that doesn't have a specific override.
Follow these steps to map an item:
* **Access a Xero Connection in Lago:** navigate to your connected Xero integration within the Lago platform;
* **Select the Item to map:** click on the specific item in Lago that you wish to map to a corresponding Xero item;
* **Fetch Items from Xero:** Lago will automatically retrieve the relevant items from your Xero instance;
* **Map the Item:** choose the appropriate Xero item from the list provided by Lago; and
* **Click 'Save'** to finalize the mapping.
### Mapping a fallback item (mandatory)
The fallback item is a dummy item used as a backup in case the mapping of other objects fails.
To ensure continuous data synchronization between Lago and Xero, this fallback item will be used whenever there is a mapping issue.
This mapping follows a one-to-many structure, meaning that a single fallback item can be used to handle multiple mapping issues.
### Mapping a payment account (mandatory)
To synchronize invoice payments between Lago and Xero, ensure that at least one payment account is mapped.
To set up a payment account in Xero, follow these steps:
1. Log in to your Xero instance;
2. Navigate to **Accounting > Chart of Accounts**;
3. Select an existing revenue account or create a new one; and
4. When editing or creating the account, ensure the **'Enable payments to this account'** checkbox is selected.
In Lago, you can now map it in the dedicated section '**Account linked to payments**'.
### Mapping custom objects
Billable metrics and add-ons require a one-to-one mapping. Each billable metric, used for usage-based billing, must represent a specific SKU in your Xero instance.
You need to map each of these individually. Lago will use the mapped items whenever any of these metrics or add-ons appear on the final invoice sent to Xero.
This mapping follows a one-to-one structure, meaning each billable metric or add-on must be mapped to a specific Xero item.
## Customers synchronization
When creating or updating a Lago customer, you can choose to link it to a Xero customer.
The first option is to **automatically create a new customer from Lago to Xero**. Follow these steps:
1. Create or update a new Lago customer;
2. Select the targeted Xero connection;
3. Check the box labeled 'Create this customer automatically in Xero'; and
4. Save and create this new customer.
If the customer is successfully created in Xero, a new field will be displayed in the Lago customer view, providing a direct link to the corresponding Xero customer.
Customer creation from Lago to Xero happens in real-time with only a few seconds of delay.
The second option is to **import an existing Xero customer to a Lago customer**. Follow these steps:
1. Create or update a Lago customer;
2. Select the targeted Xero connection;
3. Ensure the box labeled 'Create this customer automatically in Xero' is unchecked;
4. Paste the Xero customer ID in the appropriate field; and
5. Save and create this new customer.
**Here is the list of fields that is currently synced to Xero:**
| Lago | Xero |
| ------------------------------------ | ------------ |
| customer | type |
| customer.name | Name |
| customer.email | EmailAddress |
| customer.phone | Phones |
| customer.tax\_identification\_number | TaxNumber |
| customer.address\_line\_1 | AddressLine1 |
| customer.address\_line\_2 | AddressLine2 |
| customer.city | City |
| customer.zip | PostalCode |
| customer.country | Country |
| customer.state | Region |
## Invoices synchronization
If a Lago customer is linked to a Xero customer, Lago syncs invoices to Xero Invoices in real-time.
It's important to note the following:
* Each fee issued by Lago is synced as a line item on a Xero invoice;
* The Lago fee `units` are synced to Xero as `Quantity`;
* The Lago fee `precise_unit_amount` is synced to Xero as `UnitAmount`;
* Lago can send the total tax amount for a specific line item; and
* Lago can apply discount to a specific line item.
If the invoice is successfully created in Xero, a new field will be displayed in the Lago invoice view, providing a direct link to the corresponding Xero invoice.
Invoice creation from Lago to Xero happens in real-time with only a few seconds of delay.
**Here is the list of fields that is currently synced to Xero:**
| Lago | Xero |
| ------------------------------------------- | -------------- |
| invoice | type |
| invoice.number | InvoiceNumber |
| invoice.status | Status |
| invoice.currency | CurrencyCode |
| invoice.issuing\_date | Date |
| invoice.payment\_due\_date | DueDate |
| invoice.fee.units | Quantity |
| invoice.fee.precise\_unit\_amount | UnitAmount |
| invoice.fee.amount\_cents | LineAmount |
| invoice.fee.taxes\_amount\_cents | TaxAmount |
| invoice.fee.precise\_coupons\_amount\_cents | DiscountAmount |
## Credit Notes synchronization
If a Lago customer is linked to a Xero customer, Lago syncs credit notes to Xero Credit Notes in real-time.
It's important to note the following:
* Each fee refunded by Lago is synced as a line item on a Xero Credit Note; and
* Any discounts on an credit note (like coupon, for instance) are synced as line items on the Xero Credit Note.
If the credit note is successfully created in Xero, a new field will be displayed in the Lago credit note view, providing a direct link to the corresponding Xero Credit Note.
Credit note creation from Lago to Xero happens in real-time with only a few seconds of delay.
**Here is the list of fields that is currently synced to Xero:**
| Lago | Xero |
| --------------------------------------------- | ---------------- |
| credit\_note.number | CreditNoteNumber |
| credit\_note.reference | Reference |
| credit\_note.status | Status |
| credit\_note.currency | CurrencyCode |
| credit\_note.issuing\_date | Date |
| credit\_note.line\_item.units | Quantity |
| credit\_note.line\_item.precise\_unit\_amount | UnitAmount |
| credit\_note.line\_item.amount\_cents | LineAmount |
| credit\_note.line\_item.taxes\_amount\_cents | TaxAmount |
## Payments synchronization
If a Lago invoice is tied to a Xero invoice, Lago automatically syncs payments occurring in Lago to Xero, updating in-real time the payment status of the invoice in Xero.
| Lago | Xero |
| --------------------- | ------- |
| invoice.id | Invoice |
| invoice.amount\_cents | Amount |
## Integration logs
Whenever an issue occurs in Xero, Lago will notify you through a [webhook message](/api-reference/webhooks/messages#accounting-provider-error) called `customer.accounting_provider_error`.