Order Lifecycle

Complete guide to order status flow and management

Order Flow Diagram

Order Status Codes

Status ID	Status Name	Description	Actions Available
1	Sipariş Geldi	New order received	Accept, Cancel
2	Hazırlanıyor	Order confirmed and preparing	On The Way, Cancel
16	Restoran Kuryeye Verildi	Out for delivery (restaurant courier)	Complete, Cancel
5	Teslim Edildi	Order delivered successfully	-
6	İptal Edildi	Order 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 ID	Description	When to Use
1	Ürün tükendi	Product out of stock
2	Adres bulunamıyor	Address not found
3	Yoğunluk nedeniyle	Too busy to handle
4	Müşteri iptal etti	Customer requested cancellation
5	Teknik sorun	Technical issue
6	Çok uzak teslimat adresi	Delivery address too far
7	Ödeme problemi	Payment problem
8	Diğer	Other reason

Order Repetition Behavior

How Order Repetition Works

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

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
}

fuudy

Platform Courier (External)

• Fuudy/platform manages delivery
• You only accept and prepare
• Don’t call /ontheway or /complete

{
  "courier_type": "fuudy",
  "courier_fee": 25
}

come_get

Customer Pickup

• Customer collects order
• Call /complete when customer picks up
• No delivery needed

{
  "courier_type": "come_get",
  "courier_fee": 0
}

Payment Types

Orders can have different payment methods:

Payment Method	Description	When to Collect
Nakit (CASH)	Cash payment	On delivery
Kredi Kartı (CREDIT_CARD)	Credit card	Already paid
Banka Kartı (DEBIT_CARD)	Debit card	Already 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

Always Acknowledge Orders

Call /orders/success immediately after importing an order into your POS to prevent duplicate notifications.

Use payment_key for API Calls

Always use the payment_key (UUID) for operational endpoints, not the id (integer).

Handle All Status Transitions

Ensure your POS can handle orders in any status, including edge cases.

Validate Courier Type

Check courier_type before calling /ontheway and /complete. These are only valid for "restaurant" type.

Set Realistic Prep Times

Consider kitchen load, order complexity, and time of day when setting preparing_time.

Handle Cancellations Gracefully

Always provide a meaningful reason_id when canceling orders.

Troubleshooting

Order keeps appearing in get-current

Cause: Order hasn’t been acknowledged.

Solution: Call /orders/success/{payment_key} after processing.

Can't call /ontheway on order

Cause: Order courier_type is not “restaurant”.

Solution: Check courier_type field. Only restaurant couriers can use this endpoint.

Order disappeared after acknowledge

Cause: Order was acknowledged and status didn’t change.

Solution: This is expected behavior. Order will reappear when status changes.

Using wrong order ID

Cause: Using id (integer) instead of payment_key (UUID).

Solution: Always use payment_key for API operations.

Related Resources

Get Current Orders

API reference for fetching orders

Accept Order

Accept order endpoint details

Best Practices

Integration best practices

Error Handling

Handle errors gracefully