> ## Documentation Index
> Fetch the complete documentation index at: https://dkkangoyazlmteknolojiticareta.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Order Lifecycle

> Complete guide to order status flow and management

## Order Flow Diagram

```mermaid theme={null}
graph TD
    A[RECEIVED<br/>status_id: 1] -->|/orders/accept| B[CONFIRMED<br/>status_id: 2]
    B -->|/orders/ontheway| C[IN_DELIVERY<br/>status_id: 16]
    C -->|/orders/complete| D[COMPLETE_WITH_PAYMENT<br/>status_id: 5]
    
    A -.->|/orders/cancel| E[CANCELED<br/>status_id: 6]
    B -.->|/orders/cancel| E
    C -.->|/orders/cancel| E
    
    style A fill:#FFE5CC
    style B fill:#CCE5FF
    style C fill:#E5CCFF
    style D fill:#CCF0CC
    style E fill:#FFCCCC
```

## 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                        | -                  |

<Note>
  Status history is **automatically** managed by database triggers. You don't need to manually update it.
</Note>

## Complete Lifecycle Flow

<Steps>
  <Step title="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:**

    ```bash theme={null}
    # 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
  </Step>

  <Step title="2. Order Confirmed (status_id: 2)">
    **What happens:**

    * Restaurant accepts the order
    * Preparation time is set
    * Kitchen starts preparing

    **Your actions:**

    ```bash theme={null}
    # 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
  </Step>

  <Step title="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:**

    ```bash theme={null}
    # Mark as out for delivery
    PUT /orders/ontheway/{payment_key}
    ```

    **Next steps:**

    * Courier delivers order
    * Customer receives food
    * Payment collected (if cash)
  </Step>

  <Step title="4. Order Complete (status_id: 5)">
    **What happens:**

    * Order successfully delivered
    * Payment confirmed
    * Order lifecycle ends

    **Your actions:**

    ```bash theme={null}
    # Mark as complete
    PUT /orders/complete/{payment_key}
    ```

    **Result:**

    * Order removed from active orders
    * Transaction complete
  </Step>
</Steps>

## Alternative Flow: Cancellation

<Warning>
  Orders can be canceled at any status before completion.
</Warning>

<Steps>
  <Step title="Get Cancel Reasons">
    ```bash theme={null}
    GET /orders/cancel-reasons
    ```

    **Response:**

    ```json theme={null}
    {
      "data": [
        {"id": 1, "reason": "Ürün tükendi"},
        {"id": 2, "reason": "Adres bulunamıyor"},
        {"id": 3, "reason": "Yoğunluk nedeniyle"},
        ...
      ]
    }
    ```
  </Step>

  <Step title="Cancel Order">
    ```bash theme={null}
    PUT /orders/cancel/{payment_key}
    {
      "reason_id": 3
    }
    ```
  </Step>

  <Step title="Result">
    * Order status → CANCELED (status\_id: 6)
    * Customer notified
    * Refund processed (if paid)
  </Step>
</Steps>

## 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

<Accordion title="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
</Accordion>

## Courier Types

Orders can have different courier types that affect the workflow:

<Tabs>
  <Tab title="restaurant">
    **Restaurant's Own Courier**

    * You manage the entire delivery
    * Must call `/ontheway` and `/complete`
    * Full control over delivery timing

    ```json theme={null}
    {
      "courier_type": "restaurant",
      "courier_fee": 0
    }
    ```
  </Tab>

  <Tab title="fuudy">
    **Platform Courier (External)**

    * Fuudy/platform manages delivery
    * You only accept and prepare
    * Don't call `/ontheway` or `/complete`

    ```json theme={null}
    {
      "courier_type": "fuudy",
      "courier_fee": 25
    }
    ```
  </Tab>

  <Tab title="come_get">
    **Customer Pickup**

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

    ```json theme={null}
    {
      "courier_type": "come_get",
      "courier_fee": 0
    }
    ```
  </Tab>
</Tabs>

## 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    |

<Info>
  All completed orders are marked as `COMPLETE_WITH_PAYMENT` regardless of payment type.
</Info>

## Scheduled Orders

Some orders may be scheduled for future delivery:

```json theme={null}
{
  "scheduled_date": "2026-01-15 18:30:00"  // Future time
}
```

**vs. Immediate delivery:**

```json theme={null}
{
  "scheduled_date": ""  // Empty = immediate
}
```

<Tip>
  For scheduled orders, start preparation based on the `scheduled_date` to ensure timely delivery.
</Tip>

## Best Practices

<AccordionGroup>
  <Accordion title="Always Acknowledge Orders">
    Call `/orders/success` immediately after importing an order into your POS to prevent duplicate notifications.
  </Accordion>

  <Accordion title="Use payment_key for API Calls">
    Always use the `payment_key` (UUID) for operational endpoints, not the `id` (integer).
  </Accordion>

  <Accordion title="Handle All Status Transitions">
    Ensure your POS can handle orders in any status, including edge cases.
  </Accordion>

  <Accordion title="Validate Courier Type">
    Check `courier_type` before calling `/ontheway` and `/complete`. These are only valid for `"restaurant"` type.
  </Accordion>

  <Accordion title="Set Realistic Prep Times">
    Consider kitchen load, order complexity, and time of day when setting `preparing_time`.
  </Accordion>

  <Accordion title="Handle Cancellations Gracefully">
    Always provide a meaningful `reason_id` when canceling orders.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Order keeps appearing in get-current">
    **Cause:** Order hasn't been acknowledged.

    **Solution:** Call `/orders/success/{payment_key}` after processing.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Order disappeared after acknowledge">
    **Cause:** Order was acknowledged and status didn't change.

    **Solution:** This is expected behavior. Order will reappear when status changes.
  </Accordion>

  <Accordion title="Using wrong order ID">
    **Cause:** Using `id` (integer) instead of `payment_key` (UUID).

    **Solution:** Always use `payment_key` for API operations.
  </Accordion>
</AccordionGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="Get Current Orders" icon="list" href="/api-reference/orders/get-current">
    API reference for fetching orders
  </Card>

  <Card title="Accept Order" icon="check" href="/api-reference/orders/accept">
    Accept order endpoint details
  </Card>

  <Card title="Best Practices" icon="star" href="/guides/best-practices">
    Integration best practices
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/guides/error-handling">
    Handle errors gracefully
  </Card>
</CardGroup>