Onboarding · Xero

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.

Audience
The IT and finance staff responsible for bringing CargOxygen live on your side. This guide covers only the steps your team carries out and can be forwarded as is. Deployment and configuration are handled by our operations team; you do not need to sign in to any of our systems.
Labels
The Xero developer portal (developer.xero.com) is available only in English, and its labels are quoted as shown. CargOxygen is available in English and Chinese; this guide quotes the English interface.
Your contact
Your onboarding contact is the member of our operations team assigned to your deployment. They complete the matching steps on our side. For anything this guide does not cover, contact them directly.
Last updated
2026-11-03

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
  • 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.
NOTE

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.

STEP 1

Register an app in the Xero developer portal

  1. Sign in to developer.xero.com with your Xero account, open My Apps, and click New app.
  2. Fill in the fields as follows, then click Create app:
    FieldWhat to enter
    App nameA 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 typeWeb app
    Company or application URLThe application URL from your onboarding contact, https://<your domain> (it must be an https address)
    Redirect URIThe 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
  3. 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.
  4. 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).

STEP 2

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.

  1. In the portal, open this app's Webhooks page.
  2. For Delivery URL, enter the webhook delivery URL from your onboarding contact. It must be https and must not include a port number.
  3. Select the event categories: Invoice and Credit Note (required); Prepayment and Overpayment (recommended). Leave Contact unselected; CargOxygen does not process it.
  4. Click Save. The page shows a Webhook Key; save it.
  5. 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.
TIP

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.

STEP 3

Hand the credentials to your onboarding contact

What to hand overSecret?
App name, Client idNo (the client id appears in the authorization URL anyway). An ordinary message is fine.
Client secretYes
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.

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:

  1. 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.
  2. 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.
  3. Tracking (optional): map CargOxygen branches and departments to Xero tracking categories. Skip this step if you do not use them.
  4. 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.
  5. 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.

STEP 5

Validate the webhook (only if you turned it on)

  1. 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.
  2. When the status changes to OK, validation has passed.
  3. 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 seeCauseWhat to do
After you click Connect to Xero, Xero shows an error pageThe Redirect URI registered in the portal does not match the redirect URI from your onboarding contact, or the client id is wrongCheck 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 authorizationGo 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 pageConnect again
Return page: "This authorisation does not include any Xero organisation"No organization was selected during authorizationConnect 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 yetAsk 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 systemFirst click Disconnect in the company that holds it, or choose another organization
When binding: the base currencies differThe Xero organization's base currency differs from the company's local currencyThis organization cannot be bound to this company
When binding: the accounting periods do not cover a full financial year, or the financial year ends differThe company's accounting periods in CargOxygen are incomplete, or the two sides have different year endsFollow 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 readyThe authorization did not include every permission CargOxygen needsIn 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 ExpiredThe authorization expired or was revoked on the Xero sideRe-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 accountNo bank account has been created in Xero yetCreate a bank account in Xero first, then click Validate against Xero
Readiness check Bank account mapping: the organization snapshot has no bank account listThe Xero organization information stored in CargOxygen is out of dateIn 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 organizationsAn app on the free tier can connect at most 5 organizationsUpgrade the app in the portal first (see the end of Step 1), then connect