Skip to content

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:

JSON
{
  "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"
        }
      ]
    }
  ]
}
  • table is the table as the list of tables gives it; area is the hall, garden or floor it is in.
  • asOf is the moment the amounts are true of, in UTC. The bills are read again on every call.
  • minTotal is the floor the request asked for, and null when it asked for every active table.
  • bills are 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, table is the one that holds the party's bill, and mergedTables names 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 table and with area set to null.

Amounts#

  • total is 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. paid says what has been paid, remaining what is still owed.
  • A table's amounts are its bills' sums. total, paid and remaining always equal the sums of the same fields in bills.
  • paymentStatus is Unpaid when nothing has been paid on any of the bills, Paid when every bill is paid in full, and PartiallyPaid in 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.

AnswerMeaning
400 PUBLIC_API_MIN_TOTAL_INVALIDminTotal is negative.
400 VALIDATION_ERRORminTotal is not a number.
403 PUBLIC_API_SCOPE_MISSINGThe 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:

JavaScript
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.