Connecting to Xero
To connect CargOxygen to Xero, your team registers an app in the Xero developer portal under your own Xero account and hands its credentials to your onboarding contact, who installs them in your CargOxygen deployment. Your finance team then connects each company in CargOxygen to its own Xero organization.
Why you register the app yourselves: Xero's developer platform terms do not allow one developer to register several apps with the same function, so each customer uses its own app. The app belongs to you, and you can review or disable it in the portal at any time.
Each company maps to one Xero organization. Several companies in the same CargOxygen deployment can each connect to their own Xero organization, and companies that do not use Xero keep using CargOxygen's own accounting features.
Before you start
- A Xero account that can sign in to developer.xero.com (your own account).
- A Xero user with permission to authorize app connections in each Xero organization you plan to connect.
- A CargOxygen administrator account.
- The three addresses your onboarding contact sends you. Always use the addresses they send; the examples below show only the format:
- Redirect URI:
https://<your CargOxygen domain>/api/workflow/fin-integration/xero/callback - Application URL:
https://<your CargOxygen domain> - Webhook delivery URL (needed only if you turn on webhooks):
https://<your CargOxygen domain>/api/workflow/fin-integration/xero/webhook
- Redirect URI:
- Opening
https://<your CargOxygen domain>in a browser shows no certificate warning. If you use your own domain, first set up its CNAME record as your onboarding contact instructs; the certificate is replaced automatically within an hour after the CNAME takes effect.
If your Xero organization is already in use (it already holds customers, suppliers, or outstanding invoices), tell your onboarding contact first, and do not go ahead with Enable in Step 4.
Register an app in the Xero developer portal
- Sign in to developer.xero.com with your Xero account, open My Apps, and click New app.
- Fill in the fields as follows, then click Create app:
Field What to enter App name A name of your choice. It must not contain the word "Xero" (a Xero rule). The name appears on the Xero authorization page and on the links in Xero invoices that lead back to CargOxygen. Integration type Web app Company or application URL The application URL from your onboarding contact, https://<your domain>(it must be an https address)Redirect URI The redirect URI from your onboarding contact, character for character: it starts with https://, the host name is all lowercase, there is no trailing/, and there are no spaces before or after it - Click Configuration on the left. Check that the Redirect URI matches the one from your onboarding contact exactly, then click Generate a secret to create the client secret. Save the Client id and Client secret to a secure location of your own right away.
- Register only this one Redirect URI. Do not add any other address.
A new app is on Xero's free tier (Starter) by default: it can connect up to 5 Xero organizations, and each organization has a daily limit on API calls. If you plan to connect more than 5 organizations, or your document volume is high, upgrade the app in the portal (the Core tier is paid; see Xero's pricing page for current prices).
Turn on webhooks (optional)
Webhooks let Xero notify CargOxygen within tens of seconds when receipts, payments, or allocations change. Leaving them off does not lose any data: CargOxygen checks Xero for changes every 10 minutes on its own, so syncing is only slower.
- In the portal, open this app's Webhooks page.
- For Delivery URL, enter the webhook delivery URL from your onboarding contact. It must be https and must not include a port number.
- Select the event categories: Invoice and Credit Note (required); Prepayment and Overpayment (recommended). Leave Contact unselected; CargOxygen does not process it.
- Click Save. The page shows a Webhook Key; save it.
- The subscription status now shows 'Intent to receive' required, or the portal has already run a validation on its own and it failed. Both are expected: CargOxygen does not have the key yet. You will validate in Step 5.
Add the colleague responsible for this integration as a collaborator on the app. If webhook deliveries keep failing, Xero sends the notice that the webhook has been disabled only to collaborators.
Hand the credentials to your onboarding contact
| What to hand over | Secret? |
|---|---|
| App name, Client id | No (the client id appears in the authorization URL anyway). An ordinary message is fine. |
| Client secret | Yes |
| Webhook Key (only if you turned on webhooks) | Yes |
When handing over secrets:
- Send them only to the recipient your onboarding contact names. Do not put them in an email body, a group chat, a support ticket, or anywhere else that keeps the original text for a long time or is visible to many people.
- After sending, delete the copy you sent. Your onboarding contact likewise deletes the copy they received once it is entered. From then on, our systems show only the last 4 characters of each secret, never the full value.
- If you suspect a leak, generate a new client secret under Configuration in the portal and hand it over again as described in this step. If you replace only the secret and keep the same app, organizations that are already connected do not need to reconnect. If the old secret stops working before the new one has been installed, syncing fails for that period and resumes on its own once the new secret is in place.
Your onboarding contact will tell you once the credentials are active. Then continue with Step 4.
Connect the Xero organization in CargOxygen
Where: In CargOxygen's left-hand menu, go to System Config ▸ Accounting Integration, signed in as an administrator.
One company at a time: The top of the page states which company you are configuring ("You are configuring the accounting integration for company …"). Connecting, mapping, and enabling apply only to that company. To configure another company, switch company first, then open this page again.
If the top of the page says "The Xero app credentials are not configured on the server…", the credentials are not active yet; contact your onboarding contact.
The page has five steps:
- Connect: Click Connect to Xero, and the Xero authorization page opens in a new tab → sign in as a Xero user with the required permission → select the organizations to connect → approve → when the return page shows "Authorisation completed", close it → go back to the CargOxygen page (it refreshes on its own) → under Organisations from this authorisation, select the organization that belongs to this company and click Bind.
- You must finish authorizing in Xero within 10 minutes of clicking Connect to Xero.
- Before binding, CargOxygen checks three things automatically: the organization is not already bound to another company in this system; the Xero organization's base currency is the same as the company's local currency; and the Xero financial year end is the same as the year end derived from the company's accounting periods in CargOxygen (the company's accounting periods must cover a full financial year). If a check fails, the page explains why and where to fix it.
- Mapping: account mapping, tax rate mapping (two columns, Sales (AR) and Purchases (AP)), and bank account mapping. You can click Apply suggested defaults to fill the empty cells first, review each entry, then click Save mappings.
- Tracking (optional): map CargOxygen branches and departments to Xero tracking categories. Skip this step if you do not use them.
- Validate: Click Validate against Xero to check each mapping against the accounts, tax codes, and bank accounts currently in Xero. If any are no longer valid, fix them in Mapping, save, and validate again. This step also refreshes the Xero organization information stored in CargOxygen, including the list of bank accounts.
- Enable: Pushing can be enabled only when all eight Readiness checks show Ready: Connection, Base currency, Financial year, Account mapping, Tax mapping, Contact policy, Authorisation scopes, and Bank account mapping. For Contact policy, tick the confirmation box on the page (contacts are synced one way, from CargOxygen to Xero, along with the documents).
- Baseline date: documents dated before the baseline date are never pushed to Xero, which prevents double entry during cutover. Leave it empty to use the day you enable. While pushing is enabled, this field cannot be changed.
- Click Enable pushing to confirm.
Once pushing is enabled, CargOxygen pushes AR and AP invoices and credit notes to Xero, except those dated before the baseline date. Receipts and payments are recorded in Xero; CargOxygen pulls them back and allocates them automatically. For this company, CargOxygen no longer accepts receipts or payments entered by hand, or manual allocations; it rejects them and shows the reason. To pause, click Disable pushing. The connection and mappings are kept.
Validate the webhook (only if you turned it on)
- Once your onboarding contact tells you the Webhook Key is active, open this app's Webhooks page in the portal and click Validate 'Intent to receive' (the portal may also label it Send 'Intent to receive'). While the subscription is in Retry status this button does not appear; click Save again to trigger validation.
- When the status changes to OK, validation has passed.
- If the status goes back to 'Intent to receive' required with a failure reason, forward the reason, word for word, to your onboarding contact.
From then on, if Xero cannot deliver for 24 hours in a row, it disables the subscription and emails the collaborators. No data is lost in the meantime: CargOxygen keeps scanning every 10 minutes, and Xero keeps the events from that period and resends them after recovery. Once the problem is fixed, click Re-enable webhooks in the portal and repeat the validation in this step.
Troubleshooting
| What you see | Cause | What to do |
|---|---|---|
| After you click Connect to Xero, Xero shows an error page | The Redirect URI registered in the portal does not match the redirect URI from your onboarding contact, or the client id is wrong | Check the Redirect URI character by character against Step 1. If it matches and the error persists, ask your onboarding contact to check the client id |
| Return page: "The authorisation callback could not be verified (the state is invalid or has expired)" | More than 10 minutes passed between clicking Connect and finishing authorization | Go back to CargOxygen and click Connect to Xero again |
| Return page: "The Xero authorisation was not completed (it was cancelled or declined)" | Authorization was cancelled on the Xero page | Connect again |
| Return page: "This authorisation does not include any Xero organisation" | No organization was selected during authorization | Connect again and select the organization |
| Return page: "Processing the Xero authorisation failed" | Most often the client secret is wrong, or a new secret is not active yet | Ask your onboarding contact to check the secret |
| When binding: 'Xero organisation "…" is already bound to company …' | A Xero organization can be bound to only one company in this system | First click Disconnect in the company that holds it, or choose another organization |
| When binding: the base currencies differ | The Xero organization's base currency differs from the company's local currency | This organization cannot be bound to this company |
| When binding: the accounting periods do not cover a full financial year, or the financial year ends differ | The company's accounting periods in CargOxygen are incomplete, or the two sides have different year ends | Follow the dialog to adjust the periods in Period Management, or change the year end in Xero's Financial Settings, then bind again |
| Readiness check Authorisation scopes is not ready | The authorization did not include every permission CargOxygen needs | In the Connect step, click Update permissions and approve the new permissions in Xero. The connection stays as it is, and you do not need to select the organization again |
| Connection status Expired | The authorization expired or was revoked on the Xero side | Re-authorize with the button on the page. If the same Xero user authorizes, you do not need to select the organization again |
| Readiness check Bank account mapping: the Xero organization has no active bank account | No bank account has been created in Xero yet | Create a bank account in Xero first, then click Validate against Xero |
| Readiness check Bank account mapping: the organization snapshot has no bank account list | The Xero organization information stored in CargOxygen is out of date | In the Validate step, click Validate against Xero to refresh it (in earlier versions the message says "Run the mapping validation", which refers to the same button) |
| You need to connect more than 5 organizations | An app on the free tier can connect at most 5 organizations | Upgrade the app in the portal first (see the end of Step 1), then connect |