Order lifecycle

Status flow

The actions that write the status are the same on both verticals: accept, ready, dispatch, deliver, cancel. The target status depends on the vertical (see the Writing status table below). For status names and meanings, see Order statuses.

Listing and reading orders

curl "https://api.supergelsin.com/api/partner/v1/orders?updatedSince=2026-01-31T10:00:00Z&limit=50" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01"

GET /orders is a paged list and returns { items, nextCursor }. Ordering is by updatedAt ascending, then id ascending; the list starts at the oldest change and moves forward by cursor. If nextCursor is set, send it as cursor in the next request; null means the end of the stream. Orders with incomplete payment are never listed.

• Default: when neither status nor updatedSince is given, only active orders are returned (restaurant: pending, preparing, ready, on_the_way; Çarşı: pending, confirmed, preparing, on_the_way).
• When updatedSince is given, all statuses come back, including delivery and cancellation changes; this is how the point of sale reconciles its own records.
• On the next pull, pass a value a few seconds earlier than the last updatedAt you saw and remove duplicates by the id and updatedAt pair: the change time is written before the operation completes, so a newly changed order may not show up with a very close timestamp.
• On Çarşı, status=return_pending returns orders cancelled as undeliverable whose return is awaiting confirmation; returnLines is filled on these orders.

GET /orders/{id} returns the full body of a single order. An order with incomplete payment and an order of another business receive the same 404 not_found. The webhook body (the order field) is the same object; webhooks provide low latency, and these endpoints are the source of truth (Webhooks).

Order body

Customer information is narrowed 2 hours after closing (the name is shortened, the phone and coordinates are removed, the address is reduced to District / Province, the note is removed); the order summary (items, amounts, payment, invoice) is not affected by this narrowing.

Mapping lines to your products

Map lines by identifier, never by name. On a restaurant, items[].id is the item id from the GET /menu response; for options, selectedOptions[].choiceId is the modifierGroups[].choices[].id in the menu (Menu and item mapping). On a Çarşı business, the mapping key is clientReferenceId; match the product with the identifier you sent (Catalogue).

Payment: the amount due at the door

Collection information is inside the order and is the same on both verticals. channel and dueAmount tell the cashier whether to collect money at the door.

"payment": {
  "channel": "door",           // door = collected at the door · online = paid through the platform
  "instrument": "bank_card",   // cash | bank_card | meal_card
  "method": "pos_merchant",
  "dueAmount": 250             // amount to collect at the door
}

dueAmount is the amount to be collected at the door. It is 0 when channel is online or when the order is cancelled (including undeliverable). For payment at the door it is the order total; on Çarşı it can decrease after picking ends, when the picking shortfall is deducted. The amount read before picking closes is not final; read the order again after picking ends.

instrument is meal_card for meal-card methods. The online meal-card methods (meal_card_online_*) are not enabled at the moment. The set is closed for this version; if you meet a code you do not recognise, look at the channel and instrument fields instead of ignoring it.

Writing status

curl -X POST "https://api.supergelsin.com/api/partner/v1/orders/cm_ornek_siparis/status" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01" \
  -H "Content-Type: application/json" \
  -d '{ "action": "accept", "prepMinutes": 25 }'

If the target status is already in effect the result does not change and the response is 200; the same request can be repeated. The response is the current order body. An invalid transition returns 409 invalid_transition; current gives the order status and allowed the actions possible from that status.

Cancellation and reasons

GET /cancel-reasons returns all cancellation reasons for the business's vertical: who they are attributed to (attributedTo), their effect on performance (affectsPerformance), whether they are selectable (selectable) and in which order statuses they can be chosen (allowedFrom). Only codes with selectable: true are used with the cancel action. The list is not paged.

• Undeliverable reasons (customer_unreachable, invalid_address) are accepted only while the order is on_the_way; an order on the way cannot be cancelled with another reason.
• Cancelling an order paid online refunds the payment to the customer. How the sale closed after an undeliverable outcome is in deliveryFailed.completedSale: on a restaurant, true means the sale is complete, and even though status is cancelled it is not cancelled at the till; it is closed as a sale paid online. On Çarşı it is always false; for an online payment the whole amount is refunded to the customer.
• On Çarşı, the return of an order cancelled as undeliverable is confirmed with POST /orders/{id}/return (Picking and return).

Automatic cancellation of an unaccepted order

A pending order that is not accepted is cancelled automatically with the reason acceptance_timeout 12 minutes after it reaches the business; this applies on both verticals and is recorded in the business's performance. The period runs from the moment the order reaches the business; for online payment, that is the moment the payment is confirmed. accept must be written before this period ends.

On Çarşı, a future-dated (scheduled) order is not cancelled automatically. On a restaurant, a scheduled order must also be accepted within this period. Test orders (isTest: true) are outside automatic cancellation.