How to Sync Hang POPOK POS Sales to BasilBook
A five-minute walkthrough that connects your Hang POPOK store to BasilBook — so products, categories, and sales sync automatically and each invoice posts as a balanced journal entry.
Why connect Hang POPOK to your books?
Because the alternative — exporting POPOK reports nightly and pasting them into a spreadsheet — is slow, error-prone, and silently loses the operational detail your accountant needs.
A direct sync pulls every voucher from POPOK with the channel, payment type, item-level breakdown, and timestamp intact. That gives you food vs beverage gross margin, delivery channel mix, and cash vs card vs wallet split — all without manual data entry.
More importantly, the sync posts the matching double-entry journal lines as it goes: debit your cash or receivables account, credit revenue, accrue any delivery commission. By morning, yesterday's sales are already balanced in your books.
Before you start
Three things you'll need on hand. Most operators have all of them in under ten minutes.
- A BasilBook organization — Either created during onboarding or via Settings → Organizations. The integration runs at the organization level, scoped to one restaurant location.
- Admin access to your Hang POPOK store — You need to be able to generate API tokens. If your POS was set up by someone else, ask them to add you as an admin or to generate the token for you.
- A BasilBook plan that fits the use — Product and category sync is on the Free plan. Sales sync, double-entry posting, and delivery receivables are Pro features.
Step-by-step setup
Four steps. The first three are one-time setup; the fourth runs every day after that.
- Generate an API token in Hang POPOK
In your Hang POPOK admin, go to Settings → Integrations and create a new API token. POPOK shows the token once and then masks it forever — copy it to a password manager or keep the dialog open until you've pasted it into BasilBook.
- Paste your store name and token into BasilBook
In BasilBook, go to Settings → Integrations → POPOK. Enter your store subdomain (the part before .hangpopok.com — for example, basilbistro from basilbistro.hangpopok.com) and the API token. BasilBook encrypts the token at rest with AES-256-GCM.
- Run the first product sync
Click Sync products. BasilBook pulls every product and category from POPOK and creates matching sale items. This is a one-time bulk import; future product changes sync incrementally.
- Enable nightly sales sync (Pro)
Toggle on Sales sync. From the next night onward, BasilBook pulls the previous day's vouchers, creates matching sales records, and posts the journal entries. You can also run it on demand from the integrations page.
What syncs automatically
Four entity types flow from POPOK into BasilBook on different cadences.
| Entity | Cadence | Notes |
|---|---|---|
| Products | On demand + nightly | Free + Pro. Each POPOK product becomes a BasilBook sale item with the same name and price. |
| Categories | Alongside products | Free + Pro. Used to group sale items in BasilBook and for revenue reporting. |
| Sales vouchers | Nightly + on demand | Pro only. Channel detected from POPOK 'place_title' (Dine-in, Takeaway, Grab, FoodPanda, etc.). |
| Journal entries | Posted with each sale | Pro only. Balanced double-entry: debits cash/receivables, credits revenue, accrues delivery commission. |
If you want to see exactly what posts where, the auto-journal page walks through the journal lines for each transaction type — sale, refund, void, delivery settlement.
Troubleshooting common issues
The four problems we see most often, and the fix for each.
- "Invalid token" on first sync — Usually a paste error — leading or trailing whitespace, or the wrong subdomain. Re-generate the token in POPOK, paste carefully, and double-check the subdomain matches your POPOK URL exactly.
- Sync returns zero vouchers for a known busy day — Check your POPOK timezone. POPOK timestamps are in milliseconds and BasilBook converts them to your organization timezone — if those don't match what you expect, vouchers can land on the previous or next day.
- Delivery sales show as "Dine-in" — Channel detection reads the POPOK 'place_title' field. If your delivery orders aren't tagged with the platform name (e.g., 'Delivery : Grab Food'), update the place setup in POPOK so the title includes the platform.
- Same voucher appears twice — Shouldn't happen — BasilBook deduplicates on POPOK's external voucher ID. If you see this, it usually means the voucher was migrated across POPOK stores. Email support with the duplicate IDs.
If you hit anything not covered here, email support with the POPOK voucher ID or sync timestamp and we'll dig in.