---
title: "Cancel Order API (cancel-order)"
description: "Cancel a future-scheduled send-sms order before it is dispatched to the carrier. Only orders that have not started sending can be cancelled."
slug: /en/docs/api/cancel-order
locale: en
audience: developer
last_updated: 2026-04-30
endpoint:
  method: POST
  path: /v1/cancel-order/json
  base_url: https://api.iletimerkezi.com
auth: api-key-and-hash
related: [send-sms, get-report, authentication, error-codes]
alternates:
  tr: https://www.iletimerkezi.com/docs/api/cancel-order
  en: https://www.iletimerkezi.com/en/docs/api/cancel-order
  toplusmsapi: https://toplusmsapi.com/sms/iptal/json
  a2psmsapi: https://a2psmsapi.com/en/sms/iptal/json
---

# Cancel Order API (cancel-order)

The `cancel-order` endpoint cancels an order created via [`send-sms`](./send-sms.md) with a `sendDateTime` in the future, **before** it is dispatched to the carrier. Only orders that **have not started sending** can be cancelled; once the order enters the send pipeline, the cancel window has closed and the request returns `455`.

## Prerequisite: enable API access in the panel

> Before calling this endpoint, the **Allow API access** toggle must be on in your iletiMerkezi panel.
>
> Location: `panel.iletimerkezi.com` → **Settings → Security → Access Permissions**
>
> If it is off, every request returns `401 — Üyelik bilgileri hatalı` ("Authentication failed"). See [authentication.md](./authentication.md).

## Endpoint

| Field | Value |
|---|---|
| Method | `POST` |
| URL | `https://api.iletimerkezi.com/v1/cancel-order/json` |
| Content-Type | `application/json` |
| Auth | API Key + Hash (`request.authentication`) |

## Request

### Schema

```
request
├─ authentication
│  ├─ key (string, required)
│  └─ hash (string, required)
└─ order
   └─ id (string|integer, required) — orderId returned by send-sms
```

### Full example

```json
{
  "request": {
    "authentication": {
      "key": "API_KEY",
      "hash": "API_HASH"
    },
    "order": {
      "id": "312891245"
    }
  }
}
```

## Response

### Success (200)

```json
{
  "response": {
    "status": {
      "code": 200,
      "message": "İşlem başarılı"
    }
  }
}
```

`İşlem başarılı` means "Request successful" in Turkish. On success the body contains only `status` — no echoed order data. If you call [`get-report`](./get-report.md) afterwards on the same `order.id`, the order is typically in `status: 115` (could not be delivered) or returns `455 — Sipariş bulunamadı`.

### Error responses

#### 401 — Üyelik bilgileri hatalı ("Authentication failed")

API key/hash mismatch or the panel toggle is off. See [authentication.md](./authentication.md).

#### 455 — Sipariş bulunamadı ("Order not found")

Three possible causes:
1. The `order.id` does not belong to this account or has been removed.
2. The order has already entered the carrier queue and can no longer be cancelled.
3. The order has already finished.

Before attempting cancellation, check the order with [`get-report`](./get-report.md): if `order.status` is `113` (in progress) or `114` (completed), the cancel window is closed.

#### Other error codes

For `400, 404`: see [error-codes.md](./error-codes.md).

## Code samples

### cURL

```bash
curl -X POST 'https://api.iletimerkezi.com/v1/cancel-order/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "request": {
      "authentication": {
        "key": "'"$ILETIMERKEZI_API_KEY"'",
        "hash": "'"$ILETIMERKEZI_API_HASH"'"
      },
      "order": { "id": "312891245" }
    }
  }'
```


## Common pitfalls

- **The cancel window is narrow.** A future-scheduled order moves into the carrier queue as the dispatch time approaches. Once handed to the carrier it cannot be recalled; cancellation returns `455`.
- **`455` is overloaded.** "Not found" covers both an invalid ID and a valid order that is no longer cancellable. To disambiguate, call [`get-report`](./get-report.md) first and inspect `order.status`: `113` or `114` means the cancel window has closed.
- **The response is minimal.** A successful cancel returns only `response.status`; no `response.order`. To verify state, re-fetch the order via `get-report`.
- **Not idempotent.** Calling `cancel-order` twice on the same `order.id` returns `455` on the second call. Persist the cancel result on the client and short-circuit retries.
- **No "cancel an immediate send".** Orders submitted without `sendDateTime` are queued instantly; in practice there is no cancel window. This endpoint is meaningful only for future-scheduled orders.


## Related

- [Send SMS (send-sms)](./send-sms.md) — create an order, schedule with `sendDateTime`
- [Order report (get-report)](./get-report.md) — verify state before/after cancel
- [Authentication](./authentication.md)
- [Error code table](./error-codes.md)