Acknowledge Order

Mark order as received/acknowledged

PUT /orders/success/{order_id}

Acknowledge Order

cURL

curl --request PUT \
  --url https://www.xn--dkkango-n2a.com/api/integrations/orders/success/{order_id} \
  --header 'Access-Token: <api-key>'

Authentication Error (401)

{
  "status": false,
  "error": "yetkisiz erişim"
}

Overview

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

Critical: Always call this endpoint immediately after importing an order into your POS to prevent duplicate processing!

Path Parameters

order_id · string · required

Order’s payment_key (UUID) from the /get-current response

Headers

Access-Token · string · required

Your API access token

Response

status · boolean

true if successful

data · string

"OK" on success

Examples

cURL

curl -X PUT https://www.xn--dkkango-n2a.com/api/integrations/orders/success/3e9caf87-5cb7-4c4e-adcb-fc2ec54cf24e \
  -H 'Access-Token: your-access-token'

Success Response (200)

{
  "status": true,
  "data": "OK"
}

Error Responses

Authentication Error (401)

{
  "status": false,
  "error": "yetkisiz erişim"
}

Order Repetition Behavior

Key Concept: Orders repeat in /get-current responses until acknowledged with this endpoint.

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

Prevents Duplicate Processing

Without acknowledgment, the same order appears in every /get-current call, risking duplicate imports into your POS.

Ensures Reliability

If your POS crashes after receiving an order but before acknowledging it, the order will reappear when you restart.

Status Change Tracking

When an order’s status changes (RECEIVED → CONFIRMED → IN_DELIVERY), it appears again so you can track the progression.

When to Call

1. Fetch Order

   Get order from /orders/get-current

2. Validate Data

   Ensure order data is complete and valid

3. Import to POS

   Save order in your local database/system

4. Acknowledge Immediately

   Call /orders/success/{payment_key} right after successful import

Do NOT wait! Acknowledge immediately after importing. Don’t wait for staff to review or accept the order.

Integration Pattern

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

✅ Good

// 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);
}

❌ Bad

// 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);
}

Error Handling

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

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)

Using wrong order ID

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

Solution:

// ❌ Wrong
await acknowledgeOrder(order.id); // 1031

// ✅ Correct
await acknowledgeOrder(order.payment_key); // "3e9caf87-..."

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.

Related Endpoints

Get Current Orders

Fetch orders to acknowledge

Accept Order

Accept order after acknowledging

Order Lifecycle

Complete order flow guide