Tally sync

The Tally sync keeps a TallyPrime company and xMatix in step through a push connection: an xMatix add-on loaded into TallyPrime checks in on a timer, sends what changed in Tally, collects what xMatix wants written into Tally, and reports the result. Nothing dials into the customer's network and nothing else is installed on the Tally machine.

The sync covers three jobs. Masters — groups, ledgers, stock groups, stock items, units, godowns, cost centres and currencies — flow from Tally into xMatix, and customer/vendor ledgers and stock items can also be written back. Sales invoices posted in xMatix can be sent to Tally as Sales vouchers. Purchase vouchers entered in Tally can arrive in xMatix as bills with their lines. All of it is configured as an ordinary sync profile; the push transport adds two tabs, Sites and Outbound queue, and changes how health and reconciliation work.

Overview

When to use it

• A business keeps its statutory books in TallyPrime and wants xMatix to use the same customers, vendors, items and chart of accounts.
• Sales are invoiced in xMatix and the accountant wants the invoices to appear in Tally without re-keying them.
• Purchases are booked in Tally and should be visible in xMatix as bills.
• A business is moving off Tally and wants its masters loaded and kept current during the transition.

How xMatix handles it

Check-ins, not polling. Tally listens only on its own machine, so xMatix cannot call it. Instead, every interval the add-on sends a handshake naming the Tally company and its latest change number. xMatix answers with the work for this tick: which ranges of changes to send, which outbound writes to apply and, when it is due, a reconciliation request. xMatix keeps every position; the add-on holds no state of its own.

Change detection. Tally gives every create or edit of a master or voucher a rising change number (its AlterID). The sync uses it as the watermark and asks for changes in bands — a range of change numbers, at most the site's band size wide — so Tally never has to export everything in one go. Each record is paired on Tally's internal GUID, which survives renames: renaming a ledger in Tally updates the paired xMatix record rather than creating a second one. A band that is sent twice is applied once.

Resets. Rewriting a company, restoring a backup or splitting by financial year makes Tally's change number go backwards. The handshake notices that the number it was last given is now ahead of what Tally reports and starts a fresh baseline pass for the affected entities, instead of silently syncing nothing. Because pairing is by GUID, the re-read updates existing records rather than duplicating them.

Writing into Tally. An xMatix change bound for Tally is not sent directly. It becomes an item on the Outbound queue, the next check-in fetches it, Tally imports it, and the add-on reports what Tally did. Only when Tally confirms the import does the record count as in sync. A master is addressed in Tally by its name, so renames are sent with the old name to point at. Empty mapped values are not written, so an update never blanks a field in Tally.

Vouchers. A sales invoice is composed into one Tally voucher from the invoice header, its lines and the party's ledger name. Before anything is queued, xMatix checks that the voucher's debits equal its credits (to within 0.01). A voucher that does not balance is never sent. With stock lines, the sales value is carried on each line and the header lists only the party, tax and round-off ledgers. xMatix keeps its own ledger postings for the invoice; Tally posts its own from the voucher.

Deletes. Tally's change numbers record no deletions, so a master or voucher deleted in Tally is not noticed by the normal check-ins. It is found by reconciliation, which raises a conflict for a person to decide. Deletes in xMatix are not sent to Tally.

Prerequisites

• The Manage integrations setup capability (see Permissions).
• TallyPrime running on each machine that will report, with the company to be synced open.
• A dedicated sync identity user in xMatix. The engine reads and writes xMatix as this user, so record-level security limits what it can see.
• Your implementation team, to build the add-on for each site and load it into TallyPrime. The add-on is built from the site's token; it cannot be downloaded from the setup screens.
• For sales vouchers: the ledger names you will use (sales, output CGST, SGST, IGST and round-off) must already exist in the Tally company, spelt exactly as they are in Tally.

Procedure

Step 1 — Create the profile from a starter template

1. Go to Setup → Platform → Sync Profiles and select Start from template.
2. In Starter template, choose one of the Tally templates:
   • Tally masters — currencies, units, godowns (as storage locations), cost centres, stock groups (as item groups), groups (as GL accounts), stock items (as items) and customer/vendor ledgers (as accounts).
   • Tally sales vouchers (outbound) — xMatix invoices to Tally Sales vouchers.
   • Tally purchase vouchers (inbound) — Tally Purchase vouchers to xMatix bills and bill lines.
3. Tick the entities you want and pick each one's direction from the directions it allows (see What syncs).
4. Fill in the template's parameters (for example the Tally ledger names for the sales template).
5. The first time, also give the Profile name and the Sync identity user id. The integration app and connection are created for you unless you pick existing ones.

Run the template again later to add more entities. There is one sync profile per external system: applying a second Tally template extends the existing Tally profile rather than creating another, keeps the entities and maps you already have exactly as they are, and only adds what is missing. The result lists each entity as created, updated, unchanged, added as a dependency (for example Item needs Item Group), or skipped because your tenant lacks that xMatix entity.

The template sets the default conflict policy to External wins, an overlap window of 0 and no schedule — the add-on's timer is the cadence for a Tally profile.

Step 2 — Review the entities and field maps

Open the profile. On Entities and Mapping, check what the template created:

• Field maps use Tally's own export names in capitals (NAME, PARENT, PARTYGSTIN and so on). Add maps for any further fields you need.
• Do not map Tally's internal identifiers (GUID, ALTERID, MASTERID) or the correlation field xMatixExternalId; compile refuses them because the sync manages them itself.
• For a master you send to Tally (Account or Item set to Bidirectional), the name field must map to NAME. A record with no name is parked as an error with "No NAME on the mapped record."
• For the sales template, set the Invoice declaration's xMatix filter to posted invoices only (for example Status == "Posted") so drafts never reach Tally's books.
• For the purchase template, add a reference map from Bill's supplier account to PARTYLEDGERNAME once the customer and vendor ledgers have landed, so each bill links to its vendor.

Then select Compile, fix any errors it reports, set the profile to Active, and compile again.

Step 3 — Register a site for each Tally company

1. On the profile, open the Sites tab and select Add site.
2. In Register a push site, enter:
   • Site name — one site per Tally company; name it after the location and company.
   • Expected interval (seconds) — how often the add-on checks in. Default 600, between 60 and 86,400. It must match the interval the add-on is built with.
   • Band size (AlterID span) — the widest range of changes Tally exports in one tick. Default 200, between 1 and 5,000. A smaller band means a shorter pause on the Tally user's screen on each tick.
3. Select Register. The Token issued — shown once dialog shows the site's token and the command your implementation team uses to build the add-on. Copy both and hand them over securely, then select I have copied it. Only a fingerprint of the token is stored, so it cannot be shown again; if it is lost, rotate it.

The interval and band size cannot be changed after the site is registered. To change them, register a new site and remove the old one.

Step 4 — Load the add-on in TallyPrime

Your implementation team builds the add-on for the site and loads it in TallyPrime (Help → TDLs & Add-Ons, set to load on startup), then restarts Tally with the company open. The add-on adds an xMatix Status entry to Gateway of Tally.

On its first check-in the site binds itself to the Tally company that is open. From then on it accepts only that company. A second company needs a second site and its own add-on build.

Within one interval the site's Status on the Sites tab should read Reporting, and Company, Add-on, Tally (version) and Last AlterID fill in.

Step 5 — Watch the first sync and the outbound queue

• Records tab — inbound masters appear as In sync as their bands arrive. The first pass is a full baseline; later passes send only changes.
• Outbound queue tab — every write bound for Tally, with its Status, Attempts, the Site that fetched it, and Tally's Result or Error.

Row actions: Show import message displays exactly what was sent to Tally; Retry re-queues a Failed or Cancelled item with its attempts reset; Withdraw cancels a Queued item — the record then stays Pending out until it changes again in xMatix or you resume it from the Records tab.

An item fetched but never reported on (for example, Tally was closed mid-import) is put back in the queue after three intervals, and fails once its three attempts are used.

Step 6 — Turn on reconciliation

1. On the Schedule tab, enter a value in Nightly reconciliation (6-field cron, UTC). For a Tally profile the value works as an on/off switch; the add-on decides when to run it.
2. Set Reconcile window (hours) — how long after one sweep of an entity the next one is due. Default 26.

When reconciliation is on, on a quiet check-in (one with no changes to send) xMatix asks the add-on for a list of every record of one entity: GUID and change number, plus name and closing balance for ledgers. It compares that list with what has been synced. Only entities that have finished their first baseline are swept, and line declarations are not swept.

Each sweep appears on the Reconciliation tab and reports:

• Missing — in Tally but never synced to xMatix. These are reported with a sample of keys; nothing is fetched automatically.
• Deleted at source — synced earlier but gone from Tally. Each one becomes a Deleted at source conflict on the Conflicts tab; nothing is deleted in xMatix until someone decides. If Tally's list was cut short, no deletes are inferred from it.
• Balance differences (ledgers) — each ledger's Tally closing balance against the net of posted journal lines in xMatix for the paired account, to within 0.01.

Auto-repair does not apply to Tally profiles.

Step 7 — Rotate, disable or remove a site

On the Sites tab, in the row's actions:

• Rotate token issues a new token, shown once. The current token keeps working until the rebuilt add-on first presents the new one, so the site is never locked out.
• Enable / disable stops or restarts a site. A disabled site's add-on is refused and the site shows Disabled, without raising a not-reporting alert.
• Remove deletes the site. Its add-on is refused from the next check-in. Records already synced are not affected.

What syncs

Groups are always inbound: the chart of accounts is owned by Tally. Only ledgers under Sundry Debtors and Sundry Creditors are brought in as accounts; other ledgers are not mapped by the template. Cost categories are available as a Tally object but are not in the template. Credit notes, receipts, payments and journals have no template; bill-wise allocations are not synced.

Inbound voucher lines. A purchase voucher's lines travel with the voucher and are split out in xMatix. Each line is keyed on its voucher's GUID plus its position, so re-sending a voucher updates its lines rather than adding new ones. Tally sends quantities and rates with their unit ("10 Nos", "100.00/Nos"); the unit is stripped when the value is stored as a number.

Sales voucher shape. The template builds each Sales voucher from the invoice's document date, number and remarks, the place of supply and party GSTIN, a debit to the party's ledger for the invoice total, credits to the CGST, SGST, IGST and round-off ledgers (skipped when zero), and one inventory line per invoice line (item, quantity, unit, rate, amount) credited to the sales ledger.

Fields

The site registration and the Sites tab columns.

Business rules

• Site status. A site that has checked in within two intervals is Reporting; silent for more than two intervals it is Late; for more than four it is Not reporting. A site that has never checked in is Never reported, and a site you switched off is Disabled. Not reporting and Never reported count as needing attention. Intervals shorter than 60 seconds are treated as 60.
• Profile must be active. While the profile is not Active (or Seeding), every check-in is refused with "Sync profile '…' is … Activate it to start syncing." The site's last-seen time is still updated, so you can see the add-on is alive.
• One company per site. After its first check-in a site refuses any other company with "This site is registered for a different company."
• Per-tick limits. A check-in carries at most four bands and fifty outbound items; anything more waits for the next tick. A band or reconciliation list larger than 24 MB is refused.
• Outbound retries. An outbound item gets three attempts. An item Tally ignored — no error, but nothing created or altered — fails at once without retrying.
• Unbalanced vouchers. An invoice whose voucher debits and credits differ by more than 0.01 is not queued. The record is parked as an error on the Records tab with "Voucher does not balance: debits … vs credits … (difference …)".
• Line edits. Changing only an invoice line re-sends the whole invoice voucher.
• Deletes. Deletes in xMatix are not queued for Tally; deletes in Tally surface only through reconciliation as conflicts.
• When outbound writes are queued. Outbound items are created when the profile's outbound flow runs. A profile created from a template has no schedule, so agree with your implementation team how the outbound flow is run before relying on outbound sync.

Example

A distributor keeps its books in TallyPrime for the company "Lakeview Distributors". It wants its customers, vendors and stock items in xMatix, and wants invoices raised in xMatix to appear in Tally.

1. The administrator applies Tally masters with every entity Inbound, except Account set to Bidirectional so new customers created in xMatix reach Tally. On a second pass they apply Tally sales vouchers (outbound) with the ledger names Sales, Output CGST, Output SGST, Output IGST and Round Off, which all exist in the company.
2. They set the Invoice declaration's xMatix filter to posted invoices, compile, activate and compile again.
3. They register the site "Head office — Lakeview Distributors" with the default 600-second interval and band size 200, and pass the token to the implementation partner, who loads the add-on.
4. Ten minutes later the site shows Reporting. Over the next ticks the groups, ledgers and stock items arrive; the Records tab fills with In sync rows.
5. A sales user posts invoice INV-0412 for 11,800 (10,000 plus 900 CGST and 900 SGST). It appears on the Outbound queue as Queued, then Dispatched, then Confirmed, and the accountant sees a Sales voucher with the same number in Tally.
6. The administrator turns on Nightly reconciliation. The first sweep of Account reports two ledgers that were deleted in Tally; they appear as Deleted at source conflicts, and the administrator decides to keep the xMatix accounts.

Training

Practice exercise

In a sandbox with a test Tally company:

1. Apply Tally masters with Item Group, Item and Account, all Inbound. Compile, activate, compile again.
2. Register a site with interval 300 and band size 100, and have the add-on built and loaded.
3. In Tally, rename one stock item.

Expected result: the site reads Reporting within five minutes; after the next tick the renamed item shows its new name in xMatix and no second item was created; Last AlterID on the site has increased.

Quick reference

• One Tally sync profile per tenant; one site per Tally company.
• The add-on's timer is the cadence — a Tally profile needs no schedule for inbound sync.
• The site token is shown once; Rotate token never locks the site out.
• Nothing flows while Tally is closed; it catches up from the last change number when Tally reopens.
• An outbound write counts only when its queue item is Confirmed.
• Unbalanced vouchers are never sent; look on Records for the reason.
• Deletes in Tally are found only by Nightly reconciliation, and always need a person's decision.
• Never map GUID, ALTERID, MASTERID or xMatixExternalId.

Permissions

Sync Profiles, the profile's tabs (including Sites and Outbound queue) and the Sync Monitor need the Manage integrations setup capability (Create / edit integration apps, credentials, and triggers). Users without it do not see the Sync Profiles entry, and the sync screens refuse to load their data.

The add-on itself does not sign in as a user: it presents its site token. What the sync can read and write in xMatix is bounded by the profile's sync identity user and that user's record-level security.

Configuration

Common problems

The site says "Never reported"

The add-on has not checked in. Confirm with your implementation team that the add-on for this site is loaded in TallyPrime and that Tally is open with the company loaded. The add-on must be built for this site's public id and token; an add-on built for a removed site, or with a wrong token, is refused.

The site keeps going "Not reporting" every evening

Tally is closed outside working hours, so the add-on is not running. This is expected. Data catches up from the last change number when Tally reopens.

The add-on reports that the profile is not active

The profile's status is not Active (or Seeding). Open the profile, set Status to Active on the Schedule tab, and compile.

The add-on reports that no inbound flow exists

The profile has not been compiled since the entity was added. Select Compile on the profile.

The add-on reports the site is registered for a different company

The add-on was loaded in a different Tally company from the one the site bound to. Load the correct company, or register a separate site for the other company.

An outbound master failed with "Tally ignored the import"

Tally accepted the message but created and changed nothing. Usually the master already exists in Tally under a different spelling or capitalisation, or the voucher type does not exist in the company. Correct the name in one system so they agree, then Retry.

An invoice never reached the outbound queue

Open the Records tab and filter to Error. "Voucher does not balance" means a tax, discount or round-off amount is not covered by the voucher shape; the message gives the difference. An empty party ledger or item name means the invoice's account or a line's item has no name to send. Fix the invoice or the shape; the record is retried on the next run. Also check the Invoice filter includes the invoice (for example, that it is posted).

A voucher failed in Tally with an unknown ledger

The ledger names in the template parameters must exist in the Tally company exactly. Create the ledger in Tally or correct the name, then Retry.

Records we deleted in Tally are still in xMatix

Tally does not report deletes during normal sync. Turn on Nightly reconciliation; deleted records then appear as Deleted at source conflicts for you to decide.

Common questions

Does xMatix write into Tally?

Yes, when you choose to. Customer and vendor ledgers and stock items can be set to Bidirectional, and posted sales invoices can be sent as Sales vouchers. Every write goes through the Outbound queue and counts only once Tally confirms it. Groups, units, godowns, cost centres and currencies are always inbound, and deletes are never sent.

Why is there no schedule on a Tally profile?

xMatix cannot call Tally, so it does not start the sync. The add-on inside Tally checks in on its own timer, set by the site's interval. That is also why Tally health is read from the Sites column of the Sync Monitor: a stopped add-on produces no failed run and no error, only silence.

We restored a Tally backup — is the sync broken now?

No. Restoring, rewriting or splitting a company makes Tally's change number go backwards. The next check-in notices and re-reads the affected entities from the start. Because records are paired on Tally's GUIDs, the re-read updates existing xMatix records rather than duplicating them. Expect a longer first few ticks while the baseline runs.

Can we sync more than one Tally company?

Yes. Register one site per company on the same Tally profile, and have an add-on built for each. A site binds to the first company that checks in with it and refuses any other.

Do purchase vouchers create bills with lines?

Yes. With the purchase template, each Purchase voucher becomes a bill and its stock lines become bill lines. Link the bill to its vendor by adding the supplier reference map once the vendor ledgers have synced.

Related topics

• Scheduled sync
• Sync health and conflicts
• Integrations troubleshooting
• Credentials and rotation
• Integrations overview