Integration
Active tables
Reading the tables with an open bill and what each comes to, filtering them by amount, and drawing a raffle among them.
GET /venues/{venueId}/active-tables lists the venue's tables that have an open bill right now, and what each bill comes to, whoever opened it: the staff at the till, a waiter, a guest ordering from the table's QR menu, or your own software. It is made for the venue's own screens and draws, such as a raffle among the tables sitting in the venue. The call needs a key with the Can read active tables permission.
Warning: This call shows the venue's takings as they happen. Give the permission only to the venue's own screens and to software it trusts; leave it off the key of a site that shows the menu or takes orders.
The request#
curl "https://api.cibusy.com/public/v1/venues/3fa85f64-5717-4562-b3fc-2c963f66afa6/active-tables?minTotal=500" \
-H "X-Api-Key: $CIBUSY_API_KEY"minTotal is optional. Left out, every table with an open bill is listed; given, only the tables whose bill comes to at least that much. A headquarter's key reads its branches' active tables too, as it does with every venue call.
The answer#
The data of the answer, with minTotal=500 and two tables:
{
"venueId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"asOf": "2026-10-02T17:05:00.000Z",
"currency": "TRY",
"minTotal": 500,
"tables": [
{
"table": { "id": "2f4e6a8c-0b1d-4c3e-9f5a-7b9d1e3c5a70", "name": "M1", "code": "K7PX2A", "capacity": 4 },
"area": { "id": "1e3a5c7d-9f0b-4d2e-8a4c-6b8d0f2a4c61", "name": "Salon" },
"mergedTables": [
{ "id": "4a6c8e0f-2b3d-4f5a-8c7e-9d1f3a5b7c92", "name": "M2", "code": "Q4ZT9B", "capacity": 2 }
],
"openedAt": "2026-10-02T15:40:00.000Z",
"total": 1240,
"paid": 400,
"remaining": 840,
"paymentStatus": "PartiallyPaid",
"bills": [
{
"id": "5e7a9c1b-3d5f-4a7c-9e1b-3d5f7a9c1e42",
"number": 61,
"openedAt": "2026-10-02T15:40:00.000Z",
"total": 1240,
"paid": 400,
"remaining": 840,
"paymentStatus": "PartiallyPaid"
}
]
},
{
"table": { "id": "6c8e0a2b-4d5f-4b7c-9e1a-3f5b7d9a1c34", "name": "B1", "code": null, "capacity": 6 },
"area": { "id": "8d0f2b4a-6c8e-4a1b-9d3f-5e7a9c1b3d85", "name": "Bahçe" },
"mergedTables": [],
"openedAt": "2026-10-02T16:10:00.000Z",
"total": 545,
"paid": 545,
"remaining": 0,
"paymentStatus": "Paid",
"bills": [
{
"id": "7a9c1e3b-5d7f-4b9a-8c1e-5f7b9d1a3c64",
"number": 63,
"openedAt": "2026-10-02T16:10:00.000Z",
"total": 545,
"paid": 545,
"remaining": 0,
"paymentStatus": "Paid"
}
]
}
]
}tableis the table as the list of tables gives it;areais the hall, garden or floor it is in.asOfis the moment the amounts are true of, in UTC. The bills are read again on every call.minTotalis the floor the request asked for, andnullwhen it asked for every active table.billsare the table's open bills, oldest first. Usually there is one; there are more when the venue keeps separate bills for the same table.
Every field and what it means is in the List active tables reference.
Which tables are listed#
- Every table with an open bill. A table is listed while its bill is open, and drops out when the venue closes the bill.
- A paid bill stays listed. A bill paid in full is listed until the venue closes it: the party is still at the table.
- A table without a bill is not listed. A table that was seated with nothing ordered yet has no bill. Neither is a bill whose every item was cancelled.
- Tables pushed together are one entry. For tables joined for one party,
tableis the one that holds the party's bill, andmergedTablesnames the others. - The order is the till's. Tables come area by area; within an area, the ones the venue has arranged first, then the rest by name. A table the venue has since deleted, with its bill still open, comes last, called
Unknown tableand withareaset tonull.
Amounts#
totalis what the table's open bills come to: the items, less the discounts, with the service fee, in Turkish lira with VAT. Cancelled items are not counted.- What has been paid is still in
total. A party that has paid half its bill has still spent all of it.paidsays what has been paid,remainingwhat is still owed. - A table's amounts are its bills' sums.
total,paidandremainingalways equal the sums of the same fields inbills. paymentStatusisUnpaidwhen nothing has been paid on any of the bills,Paidwhen every bill is paid in full, andPartiallyPaidin between.
Filtering by amount#
Given minTotal, only the tables whose total is at least that much are listed. The floor is inclusive: minTotal=500 lists a table at 500.00 and leaves out one at 499.99.
| Answer | Meaning |
|---|---|
400 PUBLIC_API_MIN_TOTAL_INVALID | minTotal is negative. |
400 VALIDATION_ERROR | minTotal is not a number. |
403 PUBLIC_API_SCOPE_MISSING | The key does not have the Can read active tables permission. |
Nothing about the guests#
The answer never names anybody at a table, gives a phone number or says whether a guest has a Cibusy account. The items ordered are not in it either. Announce a winning table by its name, and find the bill at the till by its number, the one printed on the bill and the kitchen ticket.
A bill's id is its order's id. GET /orders/{orderId} answers only for orders placed through the API, so a bill opened at the till or from the QR menu cannot be read there.
A raffle#
This sample picks one of the tables that have spent at least 500 TL, at random:
import { randomInt } from 'node:crypto';
const response = await fetch(
`https://api.cibusy.com/public/v1/venues/${venueId}/active-tables?minTotal=500`,
{ headers: { 'X-Api-Key': process.env.CIBUSY_API_KEY } }
);
if (!response.ok) throw new Error(`Cibusy: HTTP ${response.status}`);
const { data } = await response.json();
if (data.tables.length === 0) {
console.log('No table can enter the draw.');
} else {
const winner = data.tables[randomInt(data.tables.length)];
const bills = winner.bills.map((bill) => bill.number).join(', ');
console.log(`Winning table: ${winner.table.name} (bill no. ${bills})`);
}Reading it live#
- Every call is current. Nothing is kept, and the answer comes with
Cache-Control: no-store; do not hold it in a cache on the way. - Budget. The call counts against the key's read budget of about 120 requests a minute. Refreshing a screen every five seconds is 12 requests a minute, and the key's other reads share the same budget. More in Rate limits.
- No webhook. Nothing announces that a table opened or closed; read the list at the moment you draw.
- Subscription. The key of a venue whose subscription has lapsed keeps reading its active tables.