Skip to main content
TARGET_SYSTEM: xero Xero is a suite of online accounting software for small businesses, accountants, and bookkeepers.
ReadCreateUpdateDeleteWebhook
Accounts
Async task
Bank accounts
Bills
Bill lines
Booking proposals
Contacts
Customers
Credit notes
Dimensions
Expenses
Files
Goods receipts
Goods receipt lines
Invoices
Invoice lines
Items
Journals
Journal entries
Offers
Offer lines
Open items
Payments
Payment terms
Projects
Purchase orders
Purchase order lines
Sales orders
Sales order lines
Suppliers
Tax rates
Transactions
Trial balance
Units
Users
Vendor credits
= Supported by Maesn
= Not supported by Maesn at this time
= Not supported by Xero

​
How to connect to Xero

To allow your customers to link your application with their Xero accounts, you need to set up a Xero App and submit your application credentials to maesn.
1

Prerequisites

Before you begin, make sure you have the following:
  • A Xero account with administrator permissions.
You can sign-up for a free trial at https://www.xero.com/signup/, if you do not have a Xero account already. Note that you will not need to use this Xero account for anything else than managing the Xero App and, if you want to, becoming a Xero partner later.
2

Create the Xero App

In this step we create the App that a user can choose to install into their Xero instance to authorize the integration with your application.
  • Navigate to the Xero developer portal and log in, if you are not already logged in.
  • On the tab “my Apps”, click “New App”.
  • In the pop-up, enter the below details:
    • App Name: This should be your application’s name. When your users link their Xero account, they will see that “App Name” is requesting to integrate with their Xero account.
    • Integration Type: Web app.
    • Company or application URL: The homepage of your company’s website, e.g. https://yourcompany.com/.
    • Redirect URI: Should be set to https://api.maesn.dev/auth/callback/xero
3

Generate your client secret

Now it is time to generate the unique client secret for your App.
  • Navigate to the Configuration tab of your newly created App
  • Click the “Generate a secret” button.
  • Note your client id, which you will need together with the client secret in subsequent steps.
  • Copy the client secret by clicking the Copy button next to the value. Make sure that you have copied the value before navigating away from this page. Once navigating away, you will not be able to retrieve it again.
4

Configure your integration in the maesn API

In the last step, we setup your API tenant with your App’s details:
  • Get in touch with your contact person at maesn to submit the client id and client secret.
If you are not sure who your technical contact is, do not hesitate to reach out to us.

​
Becoming a Xero Partner

Anyone can become a Xero app partner. The requirements and steps to become a partner are detailed here. Note that it is only possible to link 25 Xero accounts to your app before it is certified through the app partnership process. In addition, your customers cannot link more than two applications that are not certified.

​
Webhooks

Xero supports the following resource types:
  • CONTACT
  • INVOICE
Xero sends CREATED and UPDATED events. In the case of Xero, webhooks are App-based. This means they must be created for a given app as described here. To set this up, call Maesn’s create webhook endpoint POST /tenant/webhooks with the following body:
Example code snippet
    const response = await axios.post(url, {
        "callbackUrl": callbackUrl,
        "targetSystem": "xero",
    }, {
        headers: {
            'X-API-KEY': apiKey,
        }
    });
You don’t need to specify the eventType and resource parameters: you can select the resource types directly in the Xero App configuration, while the event types are predefined by Xero (see above). Instead, you will need to provide the targetSystem parameter with the value xero. It will return an id and url that can be used in your App’s configuration:
Example response
{
    "data": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        ...
        "url": "https://url_to_use_in_your_app/events/callback/<code>"
    },
    "meta": {}
}
Once the url has been set in your app, there will be a Wehbook key that needs to be sent to the POST /events/key/:code endpoint, where :code is the <code> from the url got in the previous response. In the request body you need to provide the key in your Xero’s app:
Example code snippet
    const response = await axios.post(url, {
        "key": webhookKey,
    }, {
        headers: {
            'X-API-KEY': apiKey,
        }
    });
After the webhook key is successfully saved, the Send ‘Intent To Receive’ button has to be clicked in the Xero App. After that goes through, events will be coming in for every customer authenticated with that App. The event response will include the userId that can be used to identify the user:
Example event body
{
    "eventType": "CREATED",
    "filterDate": null, //not supported by xero
    "resource": "CONTACT",
    "recourceId": "b15311cf-c0c1-46fe-b895-341b4b2eb005",
    "userId": "1cb1fbcc-b9ed-4ed8-a8c2-40a7fa5c8047"
}
You can call the GET /user/user-info endpoint for each user to obtain their related userId : this allows you to match each webhook event to the correct customer.