Cancel Order

Cancel an order with a specified reason

PUT /orders/cancel/{order_id}

Cancel Order

cURL

curl --request PUT \
  --url https://www.xn--dkkango-n2a.com/api/integrations/orders/cancel/{order_id} \
  --header 'Access-Token: <api-key>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "reason_id": 123
}
'

Missing Field (422)

{
  "status": false,
  "error": "eksik alan",
  "message": "reason_id is required"
}

Overview

Cancels an order at any status (except already completed/canceled) with a mandatory cancellation reason.

Path Parameters

order_id · string · required

Order’s payment_key (UUID)

Headers

Access-Token · string · required

Your API access token

Content-Type · string · required

Must be application/json

Body Parameters

reason_id · integer · required

Cancellation reason ID (1-8) - see Cancel Reasons

Cancel Reasons

ID	Reason
1	Ürün tükendi (Product out of stock)
2	Adres bulunamıyor (Address not found)
3	Yoğunluk nedeniyle (Due to congestion)
4	Müşteri iptal etti (Customer canceled)
5	Teknik sorun (Technical issue)
6	Çok uzak teslimat adresi (Delivery address too far)
7	Ödeme problemi (Payment problem)
8	Diğer (Other)

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/cancel/3e9caf87-5cb7-4c4e-adcb-fc2ec54cf24e \
  -H 'Access-Token: your-access-token' \
  -H 'Content-Type: application/json' \
  -d '{"reason_id": 3}'

Success Response (200)

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

Error Responses

Missing Field (422)

{
  "status": false,
  "error": "eksik alan",
  "message": "reason_id is required"
}

When to Cancel

1. Product Out of Stock (reason_id: 1)

Key ingredient or menu item is unavailable.

async function cancelOutOfStock(order, missingItem) {
  await cancelOrder(order.payment_key, 1);
  
  await notifyCustomer(
    order.customer.phone,
    `Sorry, ${missingItem} is out of stock. Order canceled.`
  );
  
  // Deactivate item to prevent future orders
  await deactivateFood(missingItem.id);
}

2. Address Not Found (reason_id: 2)

Delivery address is invalid or cannot be located.

async function cancelInvalidAddress(order) {
  await cancelOrder(order.payment_key, 2);
  
  await requestAddressCorrection(order.customer.phone);
}

3. Too Busy (reason_id: 3)

Restaurant is overwhelmed and cannot fulfill order.

async function cancelDueToBusyness(order) {
  await cancelOrder(order.payment_key, 3);
  
  // Consider closing restaurant temporarily
  const activeOrders = await getActiveOrderCount();
  if (activeOrders > 20) {
    await closeRestaurant(restaurantId);
  }
}

4. Customer Canceled (reason_id: 4)

Customer requested cancellation.

async function handleCustomerCancellation(order) {
  const confirmed = await confirmWithStaff(
    `Customer wants to cancel order ${order.id}. Proceed?`
  );
  
  if (confirmed) {
    await cancelOrder(order.payment_key, 4);
  }
}

5. Technical Issue (reason_id: 5)

POS system or equipment failure.

async function cancelTechnical(order, issue) {
  await cancelOrder(order.payment_key, 5);
  
  await logTechnicalIssue({
    orderId: order.id,
    issue: issue,
    timestamp: new Date()
  });
  
  await notifyTechSupport(issue);
}

6. Address Too Far (reason_id: 6)

Delivery address is outside service area.

async function cancelTooFar(order) {
  const distance = await calculateDistance(
    restaurantAddress,
    order.address
  );
  
  if (distance > MAX_DELIVERY_DISTANCE) {
    await cancelOrder(order.payment_key, 6);
    
    await notifyCustomer(
      order.customer.phone,
      'Sorry, your address is outside our delivery area.'
    );
  }
}

7. Payment Problem (reason_id: 7)

Payment verification failed.

async function cancelPaymentIssue(order) {
  await cancelOrder(order.payment_key, 7);
  
  await requestPaymentUpdate(order.customer.phone);
}

8. Other (reason_id: 8)

Any other reason not covered above.

async function cancelOther(order, customReason) {
  await cancelOrder(order.payment_key, 8);
  
  await logCancellationReason(order.id, customReason);
}

Status Transition

ANY STATUS (except COMPLETE/CANCELED)
    ↓
[/orders/cancel called]
    ↓
CANCELED (status_id: 6)

Complete Workflow

class OrderCancellation {
  async cancel(order, reasonId, additionalNotes = '') {
    try {
      // 1. Validate reason
      if (reasonId < 1 || reasonId > 8) {
        throw new Error('Invalid reason_id');
      }
      
      // 2. Confirm with staff
      const confirmed = await this.confirmCancellation(order, reasonId);
      if (!confirmed) return false;
      
      // 3. Call API
      await this.cancelOrder(order.payment_key, reasonId);
      
      // 4. Update local database
      await database.updateOrderStatus(order.id, 'CANCELED');
      await database.logCancellation({
        orderId: order.id,
        reasonId: reasonId,
        notes: additionalNotes,
        canceledBy: currentUser.id,
        timestamp: new Date()
      });
      
      // 5. Notify stakeholders
      await this.notifyCustomer(order);
      await this.notifyKitchen(order);
      
      // 6. Process refund (if applicable)
      if (order.payment_type === 'CREDIT_CARD') {
        await this.processRefund(order);
      }
      
      // 7. Update metrics
      analytics.track('order_canceled', {
        orderId: order.id,
        reasonId: reasonId,
        orderValue: order.total
      });
      
      return true;
      
    } catch (error) {
      console.error('Cancellation failed:', error);
      throw error;
    }
  }
}

Best Practices

Always Use Correct Reason

// ✅ Good: Use specific reason
await cancelOrder(order.payment_key, 1); // Out of stock

// ❌ Bad: Always using "Other"
await cancelOrder(order.payment_key, 8); // Don't default to "Other"

Confirm Before Canceling

async function safeCancelOrder(order, reasonId) {
  const reason = getCancelReasonText(reasonId);
  
  const confirmed = await confirmDialog(
    'Cancel Order?',
    `Order: ${order.id}\nReason: ${reason}\n\nThis cannot be undone.`
  );
  
  if (confirmed) {
    await cancelOrder(order.payment_key, reasonId);
  }
}

Notify Customer

async function cancelWithNotification(order, reasonId) {
  await cancelOrder(order.payment_key, reasonId);
  
  const message = getCancellationMessage(reasonId);
  await sendSMS(order.customer.phone, message);
}

Related Endpoints

Get Cancel Reasons

Fetch available cancellation reasons

Get Current Orders

View orders to cancel