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

# Acknowledge Order

> Mark order as received/acknowledged

## Overview

Marks an order as successfully received and acknowledged by your POS system. This prevents the order from repeating in subsequent `/get-current` calls.

<Warning>
  **Critical:** Always call this endpoint immediately after importing an order into your POS to prevent duplicate processing!
</Warning>

## Path Parameters

<ParamField path="order_id" type="string" required>
  Order's `payment_key` (UUID) from the `/get-current` response
</ParamField>

## Headers

<ParamField header="Access-Token" type="string" required>
  Your API access token
</ParamField>

## Response

<ResponseField name="status" type="boolean">
  `true` if successful
</ResponseField>

<ResponseField name="data" type="string">
  `"OK"` on success
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT https://www.xn--dkkango-n2a.com/api/integrations/orders/success/3e9caf87-5cb7-4c4e-adcb-fc2ec54cf24e \
    -H 'Access-Token: your-access-token'
  ```

  ```javascript JavaScript theme={null}
  const order = await getOrders();
  const paymentKey = order.payment_key; // Use payment_key, not id!

  const response = await fetch(
    `https://www.xn--dkkango-n2a.com/api/integrations/orders/success/${paymentKey}`,
    {
      method: 'PUT',
      headers: {
        'Access-Token': 'your-access-token'
      }
    }
  );

  const data = await response.json();
  // Order is now acknowledged
  ```

  ```python Python theme={null}
  import requests

  order = await get_orders()
  payment_key = order['payment_key']  # Use payment_key, not id!

  response = requests.put(
      f'https://www.xn--dkkango-n2a.com/api/integrations/orders/success/{payment_key}',
      headers={'Access-Token': 'your-access-token'}
  )

  data = response.json()
  # Order is now acknowledged
  ```

  ```php PHP theme={null}
  <?php
  $order = getOrders();
  $paymentKey = $order['payment_key']; // Use payment_key, not id!

  $url = "https://www.xn--dkkango-n2a.com/api/integrations/orders/success/{$paymentKey}";

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array(
      'Access-Token: your-access-token'
  ));
  $response = curl_exec($ch);
  curl_close($ch);
  // Order is now acknowledged
  ?>
  ```
</CodeGroup>

## Success Response (200)

```json theme={null}
{
  "status": true,
  "data": "OK"
}
```

## Error Responses

<ResponseExample>
  ```json Authentication Error (401) theme={null}
  {
    "status": false,
    "error": "yetkisiz erişim"
  }
  ```

  ```json Invalid UUID (403) theme={null}
  {
    "status": false,
    "error": "URL hatalı"
  }
  ```

  ```json Not Found (404) theme={null}
  {
    "status": false,
    "error": "sipariş bulunamadı"
  }
  ```
</ResponseExample>

## Order Repetition Behavior

<Info>
  **Key Concept:** Orders repeat in `/get-current` responses until acknowledged with this endpoint.
</Info>

### 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 [] ✅
10:02:00 - PUT /accept/1031 → Status changes to CONFIRMED
10:02:15 - GET /get-current → Returns order 1031 ✅ (new status!)
10:02:30 - PUT /success/1031 → Acknowledged for new status ✅
```

### Why This Matters

<AccordionGroup>
  <Accordion title="Prevents Duplicate Processing">
    Without acknowledgment, the same order appears in every `/get-current` call, risking duplicate imports into your POS.
  </Accordion>

  <Accordion title="Ensures Reliability">
    If your POS crashes after receiving an order but before acknowledging it, the order will reappear when you restart.
  </Accordion>

  <Accordion title="Status Change Tracking">
    When an order's status changes (RECEIVED → CONFIRMED → IN\_DELIVERY), it appears again so you can track the progression.
  </Accordion>
</AccordionGroup>

## When to Call

<Steps>
  <Step title="Fetch Order">
    Get order from `/orders/get-current`
  </Step>

  <Step title="Validate Data">
    Ensure order data is complete and valid
  </Step>

  <Step title="Import to POS">
    Save order in your local database/system
  </Step>

  <Step title="Acknowledge Immediately">
    Call `/orders/success/{payment_key}` right after successful import
  </Step>
</Steps>

<Warning>
  **Do NOT wait!** Acknowledge immediately after importing. Don't wait for staff to review or accept the order.
</Warning>

## Integration Pattern

```javascript theme={null}
async function processOrders() {
  try {
    // 1. Fetch orders
    const response = await getOrders();
    const orders = response.data;
    
    for (const order of orders) {
      try {
        // 2. Validate order
        if (!validateOrder(order)) {
          console.error('Invalid order:', order.id);
          continue;
        }
        
        // 3. Import to local database
        await importOrderToPOS(order);
        
        // 4. Acknowledge IMMEDIATELY
        await acknowledgeOrder(order.payment_key);
        
        console.log(`✅ Order ${order.id} imported and acknowledged`);
        
        // 5. Notify staff (after acknowledgment)
        notifyStaff('New order received', order);
        
      } catch (error) {
        console.error(`Failed to process order ${order.id}:`, error);
        // Don't acknowledge if import failed!
      }
    }
  } catch (error) {
    console.error('Error fetching orders:', error);
  }
}

// Poll every 30 seconds
setInterval(processOrders, 30000);
```

## Best Practices

<Tabs>
  <Tab title="✅ Good">
    ```javascript theme={null}
    // Acknowledge immediately after import
    async function handleOrder(order) {
      // Import
      await database.saveOrder(order);
      
      // Acknowledge right away
      await acknowledgeOrder(order.payment_key);
      
      // Then notify staff
      notifyStaff(order);
    }
    ```
  </Tab>

  <Tab title="❌ Bad">
    ```javascript theme={null}
    // DON'T wait for staff action!
    async function handleOrder(order) {
      await database.saveOrder(order);
      
      // ❌ Don't do this!
      // Wait for staff to click "accept" button...
      await waitForStaffApproval();
      
      // Too late - order might appear multiple times!
      await acknowledgeOrder(order.payment_key);
    }
    ```
  </Tab>
</Tabs>

## Error Handling

```javascript theme={null}
async function acknowledgeWithRetry(paymentKey, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      await acknowledgeOrder(paymentKey);
      return true;
    } catch (error) {
      console.error(`Acknowledge attempt ${attempt} failed:`, error);
      
      if (attempt < maxRetries) {
        // Wait before retry
        await sleep(1000 * attempt);
      } else {
        // Log for manual intervention
        await logFailedAcknowledgment(paymentKey, error);
        return false;
      }
    }
  }
}
```

## Common Issues

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

    **Solution:**

    1. Verify you're calling `/success` after importing
    2. Check for errors in the API response
    3. Ensure you're using `payment_key` (UUID), not `id` (integer)
  </Accordion>

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

    **Solution:**

    ```javascript theme={null}
    // ❌ Wrong
    await acknowledgeOrder(order.id); // 1031

    // ✅ Correct
    await acknowledgeOrder(order.payment_key); // "3e9caf87-..."
    ```
  </Accordion>

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

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

## Related Endpoints

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

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

  <Card title="Order Lifecycle" icon="route" href="/guides/order-lifecycle">
    Complete order flow guide
  </Card>
</CardGroup>