Skip to main content

​
Order Flow Diagram

​
Order Status Codes

Status IDStatus NameDescriptionActions Available
1Sipariş GeldiNew order receivedAccept, Cancel
2HazırlanıyorOrder confirmed and preparingOn The Way, Cancel
16Restoran Kuryeye VerildiOut for delivery (restaurant courier)Complete, Cancel
5Teslim EdildiOrder delivered successfully-
6İptal EdildiOrder canceled-
Status history is automatically managed by database triggers. You don’t need to manually update it.

​
Complete Lifecycle Flow

1

1. Order Received (status_id: 1)

What happens:
  • Customer places order
  • Order appears in /orders/get-current response
  • Order repeats in subsequent calls until acknowledged
Your actions:
# Fetch order
GET /orders/get-current

# Acknowledge receipt
PUT /orders/success/{payment_key}
Next steps:
  • Display order in POS
  • Staff reviews order
  • Decision: Accept or Cancel
2

2. Order Confirmed (status_id: 2)

What happens:
  • Restaurant accepts the order
  • Preparation time is set
  • Kitchen starts preparing
Your actions:
# Accept order with prep time
PUT /orders/accept/{payment_key}
{
  "preparing_time": 30
}
Next steps:
  • Kitchen prepares food
  • Monitor preparation progress
  • When ready, mark as out for delivery
3

3. Out for Delivery (status_id: 16)

What happens:
  • Food is ready
  • Courier picks up order
  • Order is on the way to customer
Your actions:
# Mark as out for delivery
PUT /orders/ontheway/{payment_key}
Next steps:
  • Courier delivers order
  • Customer receives food
  • Payment collected (if cash)
4

4. Order Complete (status_id: 5)

What happens:
  • Order successfully delivered
  • Payment confirmed
  • Order lifecycle ends
Your actions:
# Mark as complete
PUT /orders/complete/{payment_key}
Result:
  • Order removed from active orders
  • Transaction complete

​
Alternative Flow: Cancellation

Orders can be canceled at any status before completion.
1

Get Cancel Reasons

GET /orders/cancel-reasons
Response:
{
  "data": [
    {"id": 1, "reason": "Ürün tükendi"},
    {"id": 2, "reason": "Adres bulunamıyor"},
    {"id": 3, "reason": "Yoğunluk nedeniyle"},
    ...
  ]
}
2

Cancel Order

PUT /orders/cancel/{payment_key}
{
  "reason_id": 3
}
3

Result

  • Order status → CANCELED (status_id: 6)
  • Customer notified
  • Refund processed (if paid)

​
Cancel Reasons Reference

Reason IDDescriptionWhen to Use
1Ürün tükendiProduct out of stock
2Adres bulunamıyorAddress not found
3Yoğunluk nedeniyleToo busy to handle
4Müşteri iptal ettiCustomer requested cancellation
5Teknik sorunTechnical issue
6Çok uzak teslimat adresiDelivery address too far
7Ödeme problemiPayment problem
8DiğerOther reason

​
Order Repetition Behavior

​
Key Concept

Orders repeat in /get-current responses until explicitly acknowledged with /orders/success.

​
Example Timeline

10:00:00 - Order 1031 created (RECEIVED)
10:00:15 - GET /get-current → Returns order 1031 ✅
10:00:45 - GET /get-current → Returns order 1031 ✅ (repeated)
10:01:00 - PUT /success/1031 → Acknowledged ✅
10:01:30 - GET /get-current → Empty (order acknowledged) ✅
10:02:00 - PUT /accept/1031 → Status changes to CONFIRMED
10:02:15 - GET /get-current → Returns order 1031 again ✅ (status changed)
10:02:30 - PUT /success/1031 → Acknowledged for new status ✅

​
Why This Matters

  • Ensures you never miss an order
  • Allows recovery from crashes or network issues
  • You must acknowledge at each status change

​
Courier Types

Orders can have different courier types that affect the workflow:
Restaurant’s Own Courier
  • You manage the entire delivery
  • Must call /ontheway and /complete
  • Full control over delivery timing
{
  "courier_type": "restaurant",
  "courier_fee": 0
}

​
Payment Types

Orders can have different payment methods:
Payment MethodDescriptionWhen to Collect
Nakit (CASH)Cash paymentOn delivery
Kredi Kartı (CREDIT_CARD)Credit cardAlready paid
Banka Kartı (DEBIT_CARD)Debit cardAlready paid
All completed orders are marked as COMPLETE_WITH_PAYMENT regardless of payment type.

​
Scheduled Orders

Some orders may be scheduled for future delivery: 
{
  "scheduled_date": "2026-01-15 18:30:00"  // Future time
}
vs. Immediate delivery: 
{
  "scheduled_date": ""  // Empty = immediate
}
For scheduled orders, start preparation based on the scheduled_date to ensure timely delivery.

​
Best Practices

Call /orders/success immediately after importing an order into your POS to prevent duplicate notifications.
Always use the payment_key (UUID) for operational endpoints, not the id (integer).
Ensure your POS can handle orders in any status, including edge cases.
Check courier_type before calling /ontheway and /complete. These are only valid for "restaurant" type.
Consider kitchen load, order complexity, and time of day when setting preparing_time.
Always provide a meaningful reason_id when canceling orders.

​
Troubleshooting

Cause: Order hasn’t been acknowledged.Solution: Call /orders/success/{payment_key} after processing.
Cause: Order courier_type is not “restaurant”.Solution: Check courier_type field. Only restaurant couriers can use this endpoint.
Cause: Order was acknowledged and status didn’t change.Solution: This is expected behavior. Order will reappear when status changes.
Cause: Using id (integer) instead of payment_key (UUID).Solution: Always use payment_key for API operations.

Get Current Orders

API reference for fetching orders

Accept Order

Accept order endpoint details

Best Practices

Integration best practices

Error Handling

Handle errors gracefully