Orders

List orders

The orders placed through the API, newest first, a page at a time.

GET/public/v1/orders

Authentication: An API key in the X-Api-Key header
Permission: Can send orders
Rate limit: About 120 requests a minute per key

Lists the orders the API placed at the venues the key reaches, whichever of the venue's keys placed them: an order placed with a key that has since been replaced is still listed. Orders the venue hid from its own order list are left out; they can still be read by id. Each item is the same body GET /orders/{orderId} returns.

Read a page at a time: while nextCursor is not null, ask again with cursor set to it. The list is newest first, so an order placed while you are paging moves every later page along by one: an order can then appear on two pages, never on none.

Guide: Placing orders

Parameters

venueIdstring · uuidQuery parameter

Only this venue's orders. A headquarter's key can name one of its branches; leave it out to list the orders of every venue the key reaches.

statusstringQuery parameter

Which orders: open (neither closed nor cancelled, the default), closed or all.

Default: Open

Values:OpenClosedAll

cursorintegerQuery parameter

The page to read, counted from 1. Take it from nextCursor of the previous page.

Default: 1

pageSizeintegerQuery parameter

Orders per page: 1 to 100, 50 by default.

Default: 50

Accept-LanguagestringHeader

The language of userMessage in an error: tr (the default), en, de, fr, it, es, ar or ru. The first language in the header decides, without its region (en-US reads as en) and without weighing q values; a language Cibusy does not offer is answered in Turkish. It does not choose the language of a menu: that is lang on the menu call.

Responses

200

One page of orders.

400

INVALID_PAGE_NUMBER, INVALID_PAGE_SIZE, or VALIDATION_ERROR for a status that is not one of the three.

401

The X-Api-Key header is missing (PUBLIC_API_KEY_MISSING), or the key is invalid or has been revoked (PUBLIC_API_KEY_INVALID).

403

PUBLIC_API_SCOPE_MISSING: the key was not made with the "Can send orders" permission.

404

PUBLIC_API_VENUE_NOT_FOUND: venueId is not a venue this key can reach.

429

The key's budget of about 120 requests a minute is spent; wait Retry-After seconds.

Retry-After

Seconds to wait. The next one-minute window opens within it.

The `data` of a successful answer

One page of the orders placed through the API, newest first.

itemsobject[]

The page's orders. At most pageSize of them; empty past the last page.

Fields of Order

idstring · uuid

The order's id. Use it with GET /orders/{orderId}.

numberinteger

The number the venue calls the order by, counted from 1 within the venue. Show it to the customer; it is the one printed on the kitchen ticket. Unique within one venue only.

venueIdstring · uuid

The venue the order was placed at.

typestring

How the order reaches the diner.

DineIn: At a table: the round is added to the table's open bill, or opens one.
Takeaway: Takeaway: the customer collects it at the venue.
Delivery: Delivery: the venue brings it to the customer.

statusstring

Where the order has got to, worked out from the order's lines and its bill on every read.

Received: The venue has the order and the kitchen has not started.
Preparing: The kitchen has started on at least one line.
Ready: Every line is ready or already served.
Served: Every line on it is served.
OnTheWay: A delivery has left the venue.
Completed: The venue closed the bill.
Cancelled: The order was voided, or every line on it was struck off.

paymentStatusstring

How much of the bill has been paid at the venue.

Unpaid: Nothing has been paid at the venue.
PartiallyPaid: Part of the bill has been paid.
Paid: The bill is settled.

tableobjectnullable

The table, for a dine-in order. null for a takeaway or a delivery.

Fields of Order table

idstring · uuid

The table's id, as GET /venues/{venueId}/tables lists it.

namestring

The table's name.

customerobjectnullable

Who the order is for, for a takeaway or a delivery. null for a dine-in order, and for an order nobody took the customer's details for.

Fields of Customer details

namestringnullable

The customer's name.

phonestringnullable

The customer's phone number, in international form.

addressstringnullable

Where a delivery goes.

paymentMethodstringnullable

How the customer said they would pay, if they said. null otherwise.

Cash: Cash.
Card: Card.
MealCard: Meal card.

notestringnullable

The note for the kitchen the order was placed with. null when there was none.

linesobject[]

Every line on the order, including lines other people put on a table's bill and lines since cancelled. For a dine-in order that joined a bill that was already open, the lines of the whole bill are here: the addedLineIds of the placement answer say which of them that call wrote.

Fields of Order line

idstring · uuid

The line's id. Stays the same for as long as the line is on the order.

productIdstring · uuid

The product, as the menu lists it.

productNamestring

The product's name in the venue's own words.

portionIdstring · uuidnullable

The portion ordered, as the menu lists it.

portionNamestringnullable

The portion's name as it read when the order was placed.

quantityinteger

How many of it.

unitPricenumber

The price of one unit, extras included, as it was when the order was placed.

totalnumber

What the line comes to: unitPrice × quantity, before campaigns. 0 for a cancelled line and for one the venue gave away.

statusstring

Where the line has got to in the kitchen.

Pending: Waiting in the kitchen.
Preparing: Being prepared.
Ready: Ready.
Served: Served.
Cancelled: Cancelled. The lines of a cancelled order read this way too.

extrasobject[]

The extras on each unit.

Fields of Line extra

idstring · uuid

The extra, as the menu lists it.

namestring

The extra's name.

pricenumber

What it cost per unit when the order was placed.

removedIngredientsobject[]

The ingredients left out of each unit.

Fields of Removed ingredient

idstring · uuid

The ingredient, as the menu lists it.

namestring

The ingredient's name.

notestringnullable

The note for the kitchen about this line. null when there was none.

orderedAtstring · date-time

When the line was put on the order, in UTC.

totalsobject

What the order comes to, and how much of it is paid.

Fields of Totals

subtotalnumber

The lines at menu price with their extras, before campaigns. Cancelled lines are not counted.

discountnumber

What the venue's campaigns and discounts take off.

serviceFeenumber

The venue's service fee, charged on the food after campaigns. 0 when the venue charges none.

totalnumber

What the order comes to.

paidnumber

How much of it has been paid at the venue.

remainingnumber

How much is still owed. 0 once the bill is paid.

currencystring

The currency of every amount, an ISO 4217 code. Always TRY.

createdAtstring · date-time

When the order was placed, in UTC.

closedAtstring · date-timenullable

When the venue closed the order, in UTC. null while it is open, and for a cancelled order.

nextCursorintegernullable

The cursor to send for the next page, or null when this is the last. A cursor is a page number, counted from 1.

Request sample

curl "https://api.cibusy.com/public/v1/orders?status=open&pageSize=20" \
  -H "X-Api-Key: $CIBUSY_API_KEY"

Response sample

200 OK

{
  "success": true,
  "timestamp": "2026-10-01T09:30:00.123Z",
  "traceId": null,
  "data": {
    "items": [
      {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "number": 57,
        "venueId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "type": "Takeaway",
        "status": "Preparing",
        "paymentStatus": "Unpaid",
        "table": null,
        "customer": {
          "name": "Ayşe Yılmaz",
          "phone": "+905321112233",
          "address": null
        },
        "paymentMethod": "Card",
        "note": null,
        "lines": [
          {
            "id": "3b5d7f91-a2c4-4e6f-8b1d-9f3a5c7e1b24",
            "productId": "5d2c8a41-7b0e-4c36-8f1d-9e4a6b3c2d10",
            "productName": "Izgara köfte",
            "portionId": "a8e1f6c3-2d94-4b70-b5a6-1c7d9e0f3a24",
            "portionName": "Porsiyon",
            "quantity": 2,
            "unitPrice": 360,
            "total": 720,
            "status": "Preparing",
            "extras": [
              {
                "id": "f1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
                "name": "Ekstra peynir",
                "price": 40
              },
              {
                "id": "b4c5d6e7-f8a9-4b1a-8c2d-3e4f5a6b7c8d",
                "name": "İyi pişmiş",
                "price": 0
              }
            ],
            "removedIngredients": [
              {
                "id": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
                "name": "Soğan"
              }
            ],
            "note": "Köfteler ayrı paketlensin.",
            "orderedAt": "2026-10-01T09:30:00.000Z"
          }
        ],
        "totals": {
          "subtotal": 720,
          "discount": 0,
          "serviceFee": 0,
          "total": 720,
          "paid": 0,
          "remaining": 720
        },
        "currency": "TRY",
        "createdAt": "2026-10-01T09:30:00.000Z",
        "closedAt": null
      }
    ],
    "nextCursor": null
  },
  "message": "Operation completed successfully"
}

Error sample

400 Bad Request

{
  "success": false,
  "userMessage": "Page number must be greater than 0.",
  "developerMessage": "The cursor is a page number and starts at 1, received: 0",
  "errorCode": "INVALID_PAGE_NUMBER",
  "validationErrors": null,
  "details": null,
  "timestamp": "2026-10-01T09:30:00.123Z",
  "traceId": null
}

List orders

Parameters

Responses

The data of a successful answer

The `data` of a successful answer