How to Sync Loyverse POS to BasilBook
One access token, one store, and your Loyverse receipts start posting balanced journal entries — including the multi-store trap that catches most people on the first try.
Why connect Loyverse to your books at all?
Loyverse is a good till. It is not an accounting system, and it does not pretend to be — which leaves someone re-typing a day's takings into a spreadsheet every evening.
That re-typing is where the errors live. Not big ones — a transposed figure, a day skipped because it was a Sunday, a refund recorded once instead of twice. Individually invisible, collectively the reason your bank balance and your books disagree by an amount nobody can explain by March.
Connecting the two removes the retyping entirely. Receipts arrive with their lines, their discounts and their totals, and each one posts a balanced double-entry journal — revenue, tax and the right cash account — without anyone opening a journal screen.
Step-by-step setup
You need admin access in Loyverse to mint a token, and an owner or manager role in BasilBook. It takes about five minutes.
- Create a personal access token in Loyverse
In the Loyverse back office, open Integrations and create an access token. Copy it immediately — Loyverse shows it once and never again.
- Paste it into BasilBook
Settings → Integrations → Loyverse. The token is encrypted before it is stored and is never displayed back to you in full — only the last four characters, so you can tell which one is in there.
- Choose your store
BasilBook lists every store the token can reach and asks you to pick one. This is the step that matters most; the next section explains why.
- Sync items, then receipts
Items first, so receipts have something to attach to. Then choose a date range for receipts and import. Journals post as the receipts land.
The multi-store trap
A Loyverse access token is not scoped to one store. It can read every store on the account — which sounds convenient and is the single easiest thing to get wrong here.
If you run three branches on one Loyverse account and let all three flow into one BasilBook workspace, you get one set of books containing three restaurants' takings. Your revenue is right and everything else is useless: you cannot tell which branch is profitable, stock is a fiction because it was consumed in three kitchens, and per-location payroll no longer ties to per-location sales.
The right shape is a workspace per branch, each pointed at its own Loyverse store. The same access token can serve all of them; it is the store you select that scopes the sync. Each branch then has its own books, its own stock and its own P&L, and you can still see the group by reading them side by side.
What syncs, and what it becomes
Loyverse's REST API gives BasilBook everything it needs from that one token.
| In Loyverse | In BasilBook |
|---|---|
| Items | Sale items, matched by name (case-insensitive) so a re-sync updates rather than duplicates |
| Categories | Item categories, created on first sight |
| Receipts | Sales with lines, discounts and totals, keyed on the receipt number |
| Employees | Staff records, so takings by cashier need no second list of names |
| Payment type | The cash account the sale debits — card to bank, cash and QR to Cash on Hand |
The last row is the one that quietly matters. Cash and QR takings sit in Cash on Hand until a bank deposit clears them, which is what makes "money we have" and "money we banked" two separate, checkable numbers instead of one hopeful one.
Keep it in sync automatically
Once it works, stop doing it by hand. Each connected integration can sync on its own — hourly, every six hours, or once a day.
The setting lives on the same card you pasted the token into. It is off by default on every workspace, and it is a Pro feature. Each run re-reads the last three days rather than resuming from where it stopped, so a receipt amended after the fact gets corrected rather than missed.
There is a fuller explanation of why the window works that way, and what happens when a token is revoked, in the automatic sync post.
Troubleshooting
Four things account for almost every failed Loyverse sync.
- "Unauthorized" on test — The token was mistyped, has a trailing space, or was revoked in Loyverse. Mint a fresh one and paste it again — BasilBook cannot show you the stored one to compare.
- Sales from a branch that is not this one — The wrong store is selected. Change it before importing more; sales already imported from the wrong store have to be removed rather than re-pointed.
- Receipts import but items look wrong — Sync items before receipts. If an item arrived after the receipts that reference it, re-run the receipt import for those dates — repeat imports are safe.
- "Automatic sync is paused" — Five consecutive automatic syncs failed, so the schedule stopped rather than retrying hourly forever. Fix the token, run one manual sync, and the schedule resumes.
The Loyverse integration page covers what syncs, what it costs, and what each sale does to your ledger.