Xero API integration in Singapore: stop retyping orders, invoices and payments

What is a Xero API integration, and when does a Singapore business need one?

A Xero API integration is code that reads from and writes to your Xero organisation automatically, so records created elsewhere appear in your books without anyone keying them in. You need one when the same sale is being typed twice: once in the store, CRM or job system, and again by whoever does the accounts.

In Singapore the trigger is usually volume or complexity rather than size. A florist in Tiong Bahru with 400 web orders a month, a B2B distributor issuing invoices in three currencies, and a tuition centre billing parents termly can each lose several staff hours a week to copy-and-paste. Errors creep in too: a wrong GST code, a duplicated customer, a payment matched to the wrong invoice. Your accountant then spends billable time fixing them at quarter end, just before the GST return.

The Xero Accounting API exposes the objects you already see in the Xero web app: contacts, invoices, credit notes, payments, bank transactions, items, tracking categories and tax rates. A good Xero API integration in Singapore decides which system is the source of truth for each object, which direction data flows, and what happens when the two disagree. That design matters more than the code itself.

• Sales are recorded in one tool and re-entered in Xero by hand
• Month-end reconciliation takes days because gateway payouts are lumped
• Customers exist twice, with slightly different names, across systems
• GST codes are chosen by memory rather than by rule
• Staff ask finance whether a client has paid because the CRM cannot see Xero

If none of those describe you, a Xero integration is probably premature. Keep entering data manually until the pain is measurable, then read on.

When is an existing Xero app enough instead of a custom Xero API integration?

An existing connector from the Xero App Store is enough when your sales flow is standard: one store, one currency, ordinary GST on everything, and a payment provider whose payouts the connector already understands. In that case, subscribe, configure and spend your budget elsewhere.

We say this first on every enquiry because it is the cheapest answer and often the correct one. Ready-made connectors are maintained by their vendors, keep pace with Xero changes and cost a predictable monthly fee. The trade-off is control. You accept the connector's idea of how an order becomes an invoice, how refunds become credit notes and how fees are recorded.

Custom work earns its place when a connector forces your bookkeeper into workarounds. Common Singapore examples: some products are zero-rated exports while others carry standard-rated GST; one customer group is billed on 30-day terms while retail buyers pay upfront; orders arrive in SGD, USD and MYR; or the business needs one invoice per delivery rather than per order. Another signal is a connector that posts daily summaries when your auditor wants order-level detail, or the reverse.

How does Xero API authentication work for a Singapore organisation?

Xero uses OAuth 2.0: a person with access to your Xero organisation approves the app once, and the integration receives an access token plus a refresh token that keeps the connection alive. For Singapore organisations this means the standard authorisation code flow, or PKCE for apps that cannot store a secret.

There is a Singapore-specific wrinkle. Xero's Custom Connections, a paid machine-to-machine option using the client credentials grant for a single organisation, are listed in Xero's developer documentation as available only for organisations in Australia, New Zealand, the UK and the US. A Singapore Xero API integration therefore relies on the user-approved flow, so token storage and refresh must be handled carefully.

The token lifetimes shape the design. Xero's official SDK documentation describes access tokens that expire after 30 minutes and refresh tokens valid for up to 60 days, and Xero's webhook guide notes you need the offline_access scope to keep a connection beyond 30 minutes. Our code refreshes tokens before expiry, stores them encrypted and alerts you if a refresh fails, which is usually because someone disconnected the app inside Xero.

Scopes are changing too. Xero's scopes documentation says broad scopes such as accounting.transactions are being replaced by granular ones such as accounting.invoices and accounting.payments, assigned to web and PKCE apps since March 2026, with broad scopes available until September 2027. We request only the granular scopes your sync needs, which also makes the consent screen less alarming for your finance team.

What are the Xero API rate limits, and how does a sync stay inside them?

Xero limits each connected organisation to five calls in progress at once and 60 calls a minute, with a daily cap of 1,000 calls for apps in the starter tier and 5,000 for higher tiers, according to Xero's published API limits. There is also an app-wide limit of 10,000 calls a minute across all tenants.

Those numbers sound generous until a busy sale day arrives. A store posting each order, its payment and its contact as three separate calls could burn through the minute limit during a 9.9 or 11.11 campaign. When a limit is hit, Xero returns HTTP 429 with a header naming the limit and, for minute and daily limits, a Retry-After value in seconds.

A well-built Xero API integration for a Singapore store is designed around those rules from day one rather than patched later:

• Batch writes: Xero accepts several invoices in one request, and its guidance suggests around 50 per call
• Queue every outbound change, so a burst of orders drains steadily instead of failing
• Read the remaining-calls headers on each response and slow down before hitting zero
• Honour Retry-After exactly, pausing only the affected organisation
• Use webhooks or modified-since filters instead of re-downloading unchanged records
• Cache reference data such as tax rates, accounts and tracking categories

New apps also start with a limited number of connected organisations, and Xero caps each organisation at two uncertified apps. For a single business connecting its own Xero account that is rarely an issue, but it is worth knowing if your bookkeeper already has other apps connected.

Syncing Shopify or WooCommerce orders into Xero: per order or daily summary?

Post one invoice per order when customers need tax invoices, when you sell on credit, or when your accountant wants to trace every sale. Post a daily summary when you sell many small retail orders paid upfront and nobody needs order-level detail in the ledger.

Both approaches are legitimate and both appear in Singapore businesses. Order-level invoices make Xero the full record but consume more API calls and create a large contact list, often with a generic "Web customer" contact for guest checkouts. Daily summaries keep Xero tidy, group GST by tax type, and leave the detail in Shopify or WooCommerce, which your auditor can still inspect.

Whatever you choose, the mapping needs decisions that connectors often gloss over. Shipping is usually a separate line with its own revenue account. Discount codes can reduce line prices or appear as a negative line. Gift cards are a liability when sold and revenue when redeemed, so they must never be booked as a sale at purchase. Refunds become credit notes linked to the original invoice, and partial refunds need the same care.

We build this on your Shopify store or WooCommerce site through their order webhooks, with a nightly check that compares order totals against what reached Xero. Any gap lands in a short report rather than surfacing at quarter end. If you are still choosing a platform, our ecommerce website design service for Singapore covers that decision.

How do PayNow receipts and card payouts reconcile in Xero?

Reconcile payouts through a clearing account: each customer payment is recorded against its invoice into a clearing account in Xero, and when the provider's payout lands in your bank, the transfer from clearing to bank matches the bank feed line exactly, with fees booked separately.

This matters because gateways rarely pay out order by order. A card provider may settle a batch of 60 orders minus fees and refunds as one deposit. Without a clearing account, your bookkeeper sees one unexplained figure in the bank feed and has to rebuild it from the provider's report. With one, the integration has already done that work.

PayNow behaves differently. The Association of Banks in Singapore describes PayNow Corporate as letting a business receive Singapore Dollar funds instantly by linking its UEN to its bank account, which means a direct PayNow QR payment lands in your bank almost at once, without gateway batching. The challenge is identification: the bank feed shows an amount and a reference, and the integration must match that reference to an open invoice. A payment gateway that offers PayNow usually batches those receipts like cards instead.

We usually recommend unique references on each invoice or order, printed on the PayNow QR or checkout page, so the match is automatic. For the gateway side of this, including dynamic QR codes and webhooks, see our guide to integrating a PayNow payment gateway.

How should GST tax rates be mapped in a Xero API integration for Singapore?

Map every sale to an explicit Xero tax type by rule, never by default. For standard-rated supplies made today that is the 9% type, which Xero's API reference lists as OUTPUTY24; zero-rated exports use ZERORATEDOUTPUT; exempt supplies and out-of-scope supplies have their own types.

The IRAS page on current GST rates confirms that Singapore's rate is 9% and that GST-registered businesses charge it on local supplies unless they qualify as zero-rated or exempt. The trap for developers is history. Xero's list for Singapore still includes the older types: OUTPUT at 7% and OUTPUTY23 at 8%. Integrations written before 2024, or copied from old tutorials, sometimes still send OUTPUT, so invoices go out at the wrong rate until someone notices on the GST return.

Our approach is to read the tax rates from your organisation through the API at start-up, confirm the mapping with you or your accountant in a simple table, and refuse to post any line whose product has no mapping. If your business is not GST-registered, every line uses the no-tax type and the integration keeps it that way.

Decisions about which of your supplies are zero-rated, exempt or out of scope belong to your accountant or tax adviser. We implement the rules they set and make them visible, so anyone can audit why a line carried a particular code. We do not give tax advice.

Does a Xero API integration handle multi-currency invoices?

Yes, provided your Xero plan supports it. On Xero's Singapore pricing page, handling multiple currencies is listed as a Premium plan feature, so a business on Starter or Standard cannot post USD or MYR invoices until it upgrades.

Once multi-currency is on, the integration sends the currency code on each invoice and lets Xero apply its exchange rate, or supplies a rate if your policy is to use the rate from the payment provider. The choice affects realised gains and losses. If the store charged a US buyer in USD and the gateway converted to SGD at settlement, the difference between the invoice rate and the settlement rate becomes a foreign exchange gain or loss in Xero, which is correct accounting but surprises people the first time.

For Singapore exporters and regional distributors, a few details need attention before go-live:

• Which currencies each customer may be billed in, stored on the contact
• Whether prices are set per currency or converted from SGD at order time
• Which bank or clearing account receives each currency
• How refunds in a foreign currency are rated, since the rate will have moved
• Whether GST applies, since exported goods are often zero-rated

We test each currency path on the Xero Demo Company before touching your live organisation, and we show your accountant the resulting journals.

Connecting a CRM or custom app to Xero: what should sync, and which way?

Sync contacts and invoices from the CRM into Xero, and send payment status back. Keep Xero as the source of truth for money and the CRM as the source of truth for relationships, and most conflicts disappear.

A typical Singapore services business, such as an interior design studio, an IT support provider or a corporate training firm, closes deals in a CRM and then asks finance to raise the invoice. The integration can create a draft invoice when a deal is marked won, copying line items, the customer's billing entity and its UEN into the contact record. Finance approves the draft in Xero, keeping human control over what goes out. When the invoice is paid, the CRM shows it, so account managers can see who is overdue without logging into Xero.

Custom apps work the same way. A booking platform, a membership system or an internal job tracker can raise Xero invoices through the API. The design questions are identical: which system creates the contact, how duplicates are detected (we match on UEN or email before name), and what happens when finance edits an invoice in Xero after the app created it. Usually the app should read the change, not overwrite it.

If your CRM itself is a spreadsheet held together with goodwill, consider a small custom CRM built for your Singapore team with the Xero link included from the start.

Xero webhooks or polling: how does the integration know something changed?

Use Xero webhooks for changes to contacts, invoices, credit notes, overpayments and prepayments, and use scheduled polling with a modified-since filter for everything webhooks do not cover, such as payments recorded against bank transactions.

Xero's webhook documentation lists create and update events for those categories. Each delivery goes to an HTTPS address you register, carries a signature header, x-xero-signature, that your endpoint must verify with the webhook key, and starts only after an "intent to receive" validation. A webhook payload tells you what changed, not the full record, so the integration then fetches the invoice or contact it needs.

Why not rely on webhooks alone? Deliveries can be delayed, your server can be down for maintenance, and some changes simply are not covered. We pair webhooks with a reconciliation job that runs every few hours, compares recent records and fixes anything missed. That job also catches the human changes: an invoice voided in Xero, a contact merged by your bookkeeper, a payment deleted and re-entered.

What goes wrong in Xero integrations, and how do you prevent duplicate invoices?

Duplicates are the most common failure, and the fix is idempotency: every write carries a key that tells Xero it is a repeat. Xero's documentation on idempotent requests describes an Idempotency-Key header for POST, PUT and PATCH calls, with keys held for six minutes so a retried request returns the original response rather than creating a second invoice.

Six minutes covers network blips, not a job that crashes and restarts an hour later. So we also store the Xero ID of every record we create alongside the source order or deal, and check it before any write. An order is either linked to one invoice or it is not; there is no in-between.

Other failures we plan for on every Xero API integration in Singapore:

• Lock dates: your accountant locks a period, and a late order dated inside it is rejected
• Archived accounts or tax rates that a product mapping still points to
• Contacts renamed in Xero so a name-based match stops working
• Invoice approval limits on some Xero plans, which Xero returns as an error
• Disconnected apps after a staff member with Xero access leaves
• Validation errors from blank fields, such as a line with no account code

Each failure goes into a queue with a readable message, and you get a WhatsApp or email alert with a daily digest. Nothing is silently dropped, and nothing is retried forever.

How much does a Xero API integration in Singapore cost?

From us, a standalone Xero sync starts from US$600 and a Xero link inside a larger custom portal or app is quoted within that project, from US$900. The final figure depends on how many objects sync, in which directions, and how unusual your rules are.

Quotes from other suppliers vary widely, and it helps to understand why. A one-way push of paid orders as invoices is a small job. A two-way sync with contacts, credit notes, multi-currency payments, tracking categories and a reconciliation report is several times larger. Integrations that must work with an older on-premise system, or with a system whose own API is poorly documented, carry more uncertainty, and honest suppliers price that risk openly.

The recurring side counts as much as the build. Ask every supplier who monitors the sync, who renews tokens when someone disconnects the app, and who updates the code when Xero changes scopes or retires an endpoint, as it is doing with broad scopes until September 2027. Our two free months of maintenance cover that period after go-live; ongoing care starts from US$120/mo.

• Number of source systems and Xero objects involved
• One-way push versus two-way sync with conflict rules
• GST, multi-currency and tracking-category complexity
• Historical data import, if you want past orders in Xero
• Monitoring, alerts and a reconciliation dashboard

See how these figures sit alongside our other work on the BtechWaleTech pricing page.

How long does a Xero integration take, from Demo Company to live?

A standalone Xero API integration usually takes two to four weeks from approved quote to go-live. Most of that time goes into mapping and testing rather than coding.

Xero provides a Demo Company, a sample organisation you can connect to free for development. We build and test against it first, including GST, refunds, multi-currency and failure cases, before your live organisation is involved. When the logic is proven, we connect to your real Xero with read-only checks, then switch writing on for a small test batch that your bookkeeper reviews line by line.

Historical imports add time, especially if old orders have inconsistent tax treatment. We usually suggest starting from the next GST quarter and leaving old periods as they are.

Security, PDPA and who holds the keys to your Xero data

You hold the keys. The Xero app is registered under your developer account, the client secret is yours, and tokens live on a server or cloud account you own, encrypted at rest.

Accounting data includes customer names, emails, addresses and what they bought, all personal data under Singapore's Personal Data Protection Act. The build supports your obligations in practical ways: requesting the narrowest Xero scopes, storing only the fields the sync needs, logging who changed mappings, and restricting dashboard access to named staff. Compliance with the PDPA remains your responsibility, confirmed by your own adviser; our PDPA-focused website page explains how we approach consent and data minimisation on the front end.

During the build we work in the Demo Company and, once live, need only the access the job requires. When the project ends you can rotate the client secret and remove our access to your cloud account in minutes, and the sync keeps running because nothing depends on our accounts.

One more practical point: the person who authorises the app in Xero should be a long-term staff member or the business owner. If a departing employee's Xero login is removed and that person approved the connection, the integration may lose access. We document who approved it and how to reconnect.

Xero, InvoiceNow and GST e-invoicing in Singapore: what changes in 2026?

InvoiceNow is Singapore's Peppol-based e-invoicing network, and IRAS is phasing in a requirement for GST-registered businesses to send invoice data through it. Clean, consistently coded invoices in Xero make that step far easier, whatever tool transmits them.

According to the IRAS page on the GST InvoiceNow requirement, companies registering for GST voluntarily within six months of incorporation were covered from 1 November 2025, all new voluntary registrants from 1 April 2026, and businesses already registered before 2026 have been notified of their own implementation dates from mid-2026.

What does that mean for a Xero API integration? Invoices created by your store or CRM must carry complete, valid data: the customer's details, correct tax types and consistent line descriptions. An integration that posts lazy summaries or dumps everything under one generic customer may cause friction when those invoices have to travel as structured e-invoices.

Whether your Xero subscription or an add-on handles the actual transmission is a question for Xero and your accountant, and the answer depends on your setup. We make sure the data your systems send into Xero is complete, and our InvoiceNow integration page covers the network side, including connecting non-Xero systems through an access point.

Working with a freelance team in India on your Xero integration from Singapore

Singapore is two and a half hours ahead of India, so our working day covers most of yours: when you start at 9 am SGT we are finishing breakfast, and your afternoon is our morning and midday. Calls sit comfortably between 11 am and 7 pm Singapore time.

We work in English over video calls and WhatsApp, with written summaries after each call so your finance lead can catch up without attending. Quotes are in USD and payments go by Wise or bank wire, with invoices issued from India. Nothing is billed before you approve the written quote, and staged payments match the milestones in it; any contract terms beyond that are agreed in writing, see our terms.

The first two weeks follow a pattern. In the first few days you create a Xero developer account (we walk you through it on a call), invite us to a shared repository you own, and give read access to your store or CRM. We send back the mapping table: source fields, Xero fields, tax types and account codes. Once you and your bookkeeper sign it off, we build on the Demo Company and share a dashboard where you can watch test invoices appear.

What we do not do: on-site visits, bookkeeping, GST filing or tax advice. We are three developers who make systems talk to each other. Your accountant stays in charge of how things are recorded; we make sure the records arrive correctly. More about who we are is on the about page.

Worked example: a hypothetical Tai Seng distributor connecting a B2B store to Xero

Say a small food-ingredients distributor in Tai Seng sells to cafés on 30-day terms through a B2B ordering portal and to Malaysian customers in MYR. Staff currently rekey 25 portal orders a day into Xero, and the bookkeeper spends the first week of each month matching bank lines.

A sensible Xero API integration for them would look like this. Each approved portal order becomes an authorised Xero invoice under the café's existing contact, matched by UEN. Local sales carry the 9% standard-rated type; Malaysian export orders use the zero-rated type, as confirmed by their accountant, and bill in MYR, which requires Xero's Premium plan. Credit notes are raised automatically when the warehouse records a short delivery.

Payments arrive two ways. Cafés pay by PayNow to the company UEN with the invoice number as reference; the integration reads the bank feed and applies payments whose reference and amount match exactly, leaving mismatches for a human. A few customers pay by card through the portal; those receipts land in a clearing account and reconcile against the provider's weekly payout.

Scope-wise, this is a two-way sync with multi-currency and a reconciliation report. If the portal already exists, it fits the standalone sync range starting from US$600; if the portal is being built too, the whole job would be quoted as custom software from US$900. This scenario is illustrative, not a past client, and the actual quote would depend on their data.

Checklist: what to prepare before commissioning a Xero API integration in Singapore

Prepare access, decisions and sample data. With those three ready, a Xero integration moves quickly; without them, the first week is spent chasing answers.

• Your Xero plan name, and whether multi-currency is switched on
• A list of revenue accounts and tracking categories you want used
• Your accountant's rules for GST: which products are standard-rated, zero-rated or exempt
• Admin access to the source system: store, CRM or app
• A month of real orders or deals for testing, exported to CSV
• Your payment providers, payout schedules and how refunds are handled
• The name of the person who will approve the Xero app connection
• Where the integration should run: your own cloud account, or one we set up in your name
• Who receives alerts when something fails, and by which channel

If you are not sure about some of these, send what you have. We will fill the gaps together on the first call, and the quote will say which assumptions we made. You can reach us any day through the contact page or WhatsApp.