---
title: "Cancel order"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.cardzone.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel order

Path: Cardzone B2B API › Orders

`POST /api/b2b/v1/orders/{id}/cancel`

Requires an active API credential with the `orders:create` permission.

Cancels any order in the store that is not final (`processing`, `action_required`, or `failed`) while no fulfillment attempt or provider request is running and no shipment has left. Looking an order up by `merchant_order_ref` only finds orders created through the API. Repeating a cancellation that succeeded returns 200 again; an order canceled another way returns `409` with `order_already_terminal`.

A `409 order_not_cancelable` response means the order is not eligible and includes a machine-readable `details.reason_code`.

Sandbox credentials receive a forbidden response because sandbox orders are stateless.

## Authentication

- `BearerAuth`, http, header `Authorization`

## Path parameters

- `id` (`cancelOrder.path.id`; string, required) — Pass the Cardzone order_id returned by the API. A legacy full order UUID or the merchant_order_ref supplied on create is also accepted.

## Code samples

### cURL

```bash
curl --request POST \
  --url 'https://cardzone.ai/api/b2b/v1/orders/<id>/cancel' \
  --header 'Authorization: Bearer <token>'
```

### TypeScript

```typescript
const url = 'https://cardzone.ai/api/b2b/v1/orders/<id>/cancel';
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://cardzone.ai/api/b2b/v1/orders/<id>/cancel"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)
```

## Responses

### 200

Order canceled

#### Example

```json
{
  "order_id": "1CBDzqwiovwVrtFk6nZ1Aw",
  "merchant_order_ref": "merchant-order-10001",
  "status": "canceled",
  "product_id": "018f7b75-0194-726a-9814-e26efa39dfac",
  "product_code": "psn-sa-160",
  "quantity": 1,
  "purchase_price": {
    "amount": "380.00",
    "currency": "SAR"
  },
  "recommended_retail_price": {
    "amount": "400.00",
    "currency": "SAR"
  },
  "codes": [],
  "actions": [],
  "created_at": "2026-05-18T00:29:58+03:00"
}
```

- `order_id` (`cancelOrder.response.200.order_id`; string, required) — Cardzone order identifier. This is a reversible Base58 representation of the internal UUID.
  - minLength 22; maxLength 22; pattern `^[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$`
- `status` (`cancelOrder.response.200.status`; string, required) — `processing`: accepted or still fulfilling. `fulfilled`: successful; safe to mark the partner order successful. `action_required`: inspect `actions` and take the required action. `failed`: terminal failure; inspect `failure_reason` when present. Replacement codes the store paid for can still be added to `codes`, and a dashboard retry moves the order back to `processing`. `canceled`: terminal cancellation; no fulfillment action remains.
  - one of `"processing"`, `"fulfilled"`, `"action_required"`, `"failed"`, `"canceled"`
- `product_id` (`cancelOrder.response.200.product_id`; string, required, nullable)
  - format `uuid`
- `quantity` (`cancelOrder.response.200.quantity`; integer, required)
- `actions` (`cancelOrder.response.200.actions`; array<object>, required) — Actions required from the API consumer. Empty when no action is needed.
  - `type` (`cancelOrder.response.200.actions.type`; string, required)
    - one of `"wallet"`, `"fulfillment"`
  - `code` (`cancelOrder.response.200.actions.code`; string, required) — Machine-readable action the API consumer should handle.
    - one of `"wallet_topup_required"`, `"merchant_attention_required"`, `"manual_review_required"`
  - `message` (`cancelOrder.response.200.actions.message`; string, required) — Human-readable action summary. Wallet actions include the aggregate additional top-up amount needed for all current wallet-blocked orders in the store.
    - example `"Recharge 75 SAR to resume fulfillment for all wallet-blocked orders."`
- `created_at` (`cancelOrder.response.200.created_at`; string, required)
  - format `date-time`
- `merchant_order_ref` (`cancelOrder.response.200.merchant_order_ref`; string, optional, nullable) — Merchant order reference supplied on create, when present.
- `product_code` (`cancelOrder.response.200.product_code`; string, optional, nullable)
- `purchase_price` (`cancelOrder.response.200.purchase_price`; object, optional)
  - `amount` (`cancelOrder.response.200.purchase_price.amount`; string, required) — Decimal amount as a string
    - example `"12.00"`
  - `currency` (`cancelOrder.response.200.purchase_price.currency`; string, required)
    - example `"SAR"`
- `recommended_retail_price` (`cancelOrder.response.200.recommended_retail_price`; object, optional)
  - `amount` (`cancelOrder.response.200.recommended_retail_price.amount`; string, required) — Decimal amount as a string
    - example `"12.00"`
  - `currency` (`cancelOrder.response.200.recommended_retail_price.currency`; string, required)
    - example `"SAR"`
- `code` (`cancelOrder.response.200.code`; string, optional, nullable) — First delivered voucher code/PIN when available
- `codes` (`cancelOrder.response.200.codes`; array<string>, optional) — All delivered voucher codes/PINs when available. Includes replacement codes Cardzone delivered and charged to the store, which can appear while `status` is `failed`.
- `failure_reason` (`cancelOrder.response.200.failure_reason`; string, optional, nullable) — Backward-compatible human-readable failure summary. Provider messages and responses are never exposed here.
- `failure_code` (`cancelOrder.response.200.failure_code`; string, optional, nullable) — Cardzone-owned terminal failure identifier. `fulfillment_failed` is the generic failure and `player_id_incorrect` means the submitted player ID was definitively rejected. Provider messages and responses are never exposed here.
  - one of `"fulfillment_failed"`, `"player_id_incorrect"`

### 401

Missing, revoked, or unknown API key. A live key also gets this while its store is inactive, or until the store's business verification is approved and its primary user's email is verified.

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "product_status": "out_of_stock"
  }
}
```

- `error` (`cancelOrder.response.401.error`; object, required)
  - `code` (`cancelOrder.response.401.error.code`; string, required)
  - `message` (`cancelOrder.response.401.error.message`; string, required)
  - `details` (`cancelOrder.response.401.error.details`; unknown, optional) — Optional field-level validation details
  - `product_status` (`cancelOrder.response.401.error.product_status`; string, optional) — Present on `404` product errors when the product exists but cannot be ordered: `out_of_stock` or `unavailable`, with the same meaning as the catalog `status`. Absent when the product id is unknown or deleted.
    - one of `"out_of_stock"`, `"unavailable"`

### 403

The API credential lacks permission, or a sandbox credential was used.

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "product_status": "out_of_stock"
  }
}
```

- `error` (`cancelOrder.response.403.error`; object, required)
  - `code` (`cancelOrder.response.403.error.code`; string, required)
  - `message` (`cancelOrder.response.403.error.message`; string, required)
  - `details` (`cancelOrder.response.403.error.details`; unknown, optional) — Optional field-level validation details
  - `product_status` (`cancelOrder.response.403.error.product_status`; string, optional) — Present on `404` product errors when the product exists but cannot be ordered: `out_of_stock` or `unavailable`, with the same meaning as the catalog `status`. Absent when the product id is unknown or deleted.
    - one of `"out_of_stock"`, `"unavailable"`

### 404

Order was not found

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "product_status": "out_of_stock"
  }
}
```

- `error` (`cancelOrder.response.404.error`; object, required)
  - `code` (`cancelOrder.response.404.error.code`; string, required)
  - `message` (`cancelOrder.response.404.error.message`; string, required)
  - `details` (`cancelOrder.response.404.error.details`; unknown, optional) — Optional field-level validation details
  - `product_status` (`cancelOrder.response.404.error.product_status`; string, optional) — Present on `404` product errors when the product exists but cannot be ordered: `out_of_stock` or `unavailable`, with the same meaning as the catalog `status`. Absent when the product id is unknown or deleted.
    - one of `"out_of_stock"`, `"unavailable"`

### 409

Order cannot be canceled

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "product_status": "out_of_stock"
  }
}
```

- `error` (`cancelOrder.response.409.error`; object, required)
  - `code` (`cancelOrder.response.409.error.code`; string, required)
  - `message` (`cancelOrder.response.409.error.message`; string, required)
  - `details` (`cancelOrder.response.409.error.details`; unknown, optional) — Optional field-level validation details
  - `product_status` (`cancelOrder.response.409.error.product_status`; string, optional) — Present on `404` product errors when the product exists but cannot be ordered: `out_of_stock` or `unavailable`, with the same meaning as the catalog `status`. Absent when the product id is unknown or deleted.
    - one of `"out_of_stock"`, `"unavailable"`


Source: https://docs.cardzone.ai/reference/orders/cancel/index.md