---
feature: Provider order cancellation
slug: cancellation
surface: provider
consumer: flutter
version: 1.0.1
status: ready
brd_version: "1.3"
brd_ids: [PROV-016]
business_rules: [BR-19, BR-20, BR-21]
decisions: [DEC-10, DEC-24, TD-152, TD-153, TD-155]
schema_tables: [cancellation_rules, cancellation_rule_translations, orders, order_status_history, payments, refunds, wallets, wallet_transactions, earnings, trips, notifications]
screens: [provider--appointments--*]
related_docs: [orders.md, order-execution.md, ../client/cancellation.md, ../admin/cancellations-refunds.md]
last_updated: 2026-11-02
---

# Provider order cancellation — Flutter Integration Guide (provider)

> **Base URL:** `{HOST}/api/v1/provider` · [Shared API conventions](../API_CONVENTIONS.md).

## Version history

| Version | Date | Type | Summary | App action required |
|---------|------|------|---------|---------------------|
| 1.0.1 | 2026-11-02 | PATCH | The customer refund is credited to her wallet in the same transaction and never calls the payment gateway (TD-152); no contract change. | None |
| 1.0.0 | 2026-11-01 | Initial | `POST /orders/{order}/cancel`, `can_cancel` on every order, full wallet refund to the customer, two typed refusals. | Show **Cancel** from `can_cancel`, send the optional reason, refetch the order and the cancelled tab. |

## Changelog

### 1.0.1 — 2026-11-02

- **Changed:** The `provider_cancel` refund is completed in the cancelling transaction and does not call the payment gateway. No field changes.
- **Breaking:** No. **App action required:** None.
- **BRD / decisions:** DEC-10; TD-152.

### 1.0.0 — 2026-11-01
- **Added:** `POST /orders/{order}/cancel` (`provider.orders.cancel`, PROV-016); `can_cancel` (bool, always present) on the order tile and details; `provider` cancellation rules (DEC-24 defaults seeded by a migration).
- **Changed:** —
- **Fixed / Removed:** None.
- **Breaking:** No.
- **Endpoints affected:** `POST /orders/{order}/cancel`, `GET /orders`, `GET /orders/{order}`, `GET /appointments`.
- **App action required:** Show Cancel only when `can_cancel` is true; confirm with the provider before sending; after success the order is `cancelled` and appears in `GET /appointments?tab=cancelled`.
- **BRD / decisions:** PROV-016, BR-19, BR-20, DEC-24; TD-152, TD-153, TD-155.

---

## 1. Business summary

A provider can cancel an order she has already accepted, as long as execution has not started. For an
**instant** booking that is after payment and confirmation; for a **scheduled** booking it is after she
accepted it (even before the customer paid) and after payment, but always before she leaves. Once she
departs for the customer (`on_the_way`), or the app driver departs to collect her, cancelling is locked
(BR-19). A request still waiting for her answer is **rejected** (`POST /orders/{order}/reject`), not cancelled.

The customer is told, her wallet is refunded the **whole** paid amount whatever the cancellation rules
charge a customer, and **no amount is due** to the provider or the driver (BR-20). Any live driver search is
cancelled with the order. DEC-24: no ranking penalty.

## 2. User flow and screens

| Step | Screen / widget | Endpoint | Notes |
|------|-----------------|----------|-------|
| 1 | Appointment / order details | `GET /orders/{order}` | Show **Cancel** only when `can_cancel` is true |
| 2 | Confirmation dialog + optional reason | — | Reason max 500 characters |
| 3 | Submit | `POST /orders/{order}/cancel` | On success replace the order with the response |
| 4 | Cancelled tab | `GET /appointments?tab=cancelled` | Newest first |

## 3. Endpoints

### `POST /orders/{order}/cancel`

Auth: provider JWT, approved account · Headers: `Accept-Language` · `{order}` = order uuid (another provider's order is a 404).

| Field | Type | Required | Validation | Description |
|-------|------|----------|-----------|-------------|
| `reason` | string | no | max 500, nullable | Stored on the order and shown to admins and in the customer's cancellation details |

Her own repeat call is a 200 that changes nothing (one refund, one notification).

Postman: "200 Paid order cancelled by the provider with a full refund"

```json
{
  "status": "success",
  "message": "Order cancelled and the customer refunded.",
  "data": {
    "id": "01a197ca-c40b-7373-9c92-ed14e3404211",
    "code": "JSH-sgsz62181169",
    "status": {
      "value": "cancelled",
      "label": "Cancelled"
    },
    "payment_status": {
      "value": "refunded",
      "label": "Refunded"
    },
    "booking_type": {
      "value": "instant",
      "label": "Instant"
    },
    "service_name": null,
    "customer": {
      "id": "01a197ca-c410-7365-a378-a237668e884f",
      "name": "Dr. Monty Bechtelar V"
    },
    "scheduled_at": null,
    "eta_minutes": null,
    "net_earning": "104.00",
    "respond_before": null,
    "seconds_left": null,
    "can_respond": false,
    "can_chat": false,
    "can_prepare": false,
    "can_start_travel": false,
    "can_mark_arrived": false,
    "can_start_service": false,
    "can_complete": false,
    "can_cancel": false,
    "can_rate": false,
    "services": [],
    "address": {
      "text": null,
      "lat": null,
      "lng": null
    },
    "estimated_duration_min": null,
    "services_amount": "130.00",
    "provider_commission_rate": "20.00",
    "notes_to_provider": null,
    "rejection_reason": null,
    "created_at": "2026-10-25T07:00:00+00:00",
    "transport": {
      "mode": null,
      "chosen_at": null,
      "can_choose_transport": false,
      "can_request_driver": false,
      "can_retry_driver": false,
      "trip": null
    }
  }
}
```


Response: the same order details as `GET /orders/{order}`, with `status.value = cancelled`, `payment_status.value = refunded`
(paid orders) and every action flag false.

### Errors

| HTTP | `error_code` | When | App behavior |
|------|--------------|------|--------------|
| 422 | `ORDER_CANCELLATION_LOCKED` | The order is `on_the_way`, `arrived` or `in_progress` | Hide Cancel; show `message` |
| 422 | `INVALID_STATE_TRANSITION` | Status or order kind does not allow it: still `pending_provider`, finished, rejected, expired, cancelled by someone else, or a package purchase | Refetch; use Reject for a pending request |
| 422 | `ORDER_CANCELLATION_NOT_ALLOWED` | No active `provider` rule allows the stage | Show `message` |
| 422 | — (`data.errors.reason`) | Reason longer than 500 characters | Mark the field |
| 404 | — | Not her order | Leave the screen |

Postman: "422 Provider cancellation locked after departure"

```json
{
  "status": "fail",
  "message": "Cancellation is unavailable because execution has started.",
  "data": {
    "error_code": "ORDER_CANCELLATION_LOCKED",
    "correlation_id": "52b4a61b-cc3f-4516-a093-848280711c63"
  }
}
```

Postman: "422 Request not yet accepted cannot be cancelled"

```json
{
  "status": "fail",
  "message": "This order action is no longer available.",
  "data": {
    "error_code": "INVALID_STATE_TRANSITION",
    "correlation_id": "3bcbc6e1-e30a-410b-a989-307cf80b75ff"
  }
}
```

Postman: "422 Provider cancellation denied by the active rule"

```json
{
  "status": "fail",
  "message": "Cancellation is unavailable under the current policy.",
  "data": {
    "error_code": "ORDER_CANCELLATION_NOT_ALLOWED",
    "correlation_id": "580defea-0352-4d8c-b3a8-894bafe1f281"
  }
}
```

Postman: "422 Cancellation reason longer than 500 characters"

```json
{
  "status": "fail",
  "message": "The reason field must not be greater than 500 characters.",
  "data": {
    "errors": {
      "reason": [
        "The reason field must not be greater than 500 characters."
      ]
    }
  }
}
```


## 4. Statuses and enums

| Field | Value | Meaning |
|-------|-------|---------|
| `status` | `cancelled` | Final. Appears in the cancelled tab |
| `payment_status` | `refunded` | The customer got the whole payment back to her wallet |
| `can_cancel` | `true` / `false` | `true` only in `awaiting_payment`, `confirmed`, `preparing` of a service or package-session order, while an active provider rule allows it |

## Data model

| Table | Read / write | Notes |
|-------|--------------|-------|
| `orders` | write | `status`, `cancelled_at`, `cancelled_by = provider`, `cancellation_reason`, `cancellation_rule_id`, `cancellation_fee = 0.00` |
| `cancellation_rules` | read | The active `provider` row for the stage |
| `refunds`, `wallet_transactions`, `payments` | write | One `provider_cancel` refund, credited to the wallet |
| `trips` | write | A live trip is cancelled |
| `earnings` | write | Anything already written for the order becomes `reversed` |
| `notifications` | write | `order_cancelled` for both apps |

## 5. Dart models

```dart
// Order tile / details gain one boolean.
class ProviderOrder {
  final bool canCancel; // PROV-016, always present
  // … existing fields (orders.md)
}
```

## 6. Business rules enforced by the backend

| Rule | What the backend does | What the app sees |
|------|-----------------------|-------------------|
| BR-19 | Cancelling is locked from `on_the_way` | `ORDER_CANCELLATION_LOCKED`, `can_cancel: false` |
| BR-20 | Full wallet refund, no provider or driver amount due | `payment_status: refunded` |
| TD-153 | Only the `provider` rules apply (a customer rule never does); none allowing = refused | `ORDER_CANCELLATION_NOT_ALLOWED` |
| TD-155 | A live trip is cancelled; earnings of the order are reversed | Trip card shows cancelled |
| Concurrency | The order row is locked before its status is read, so two taps cancel once | Second call is the 200 no-op |

## 7. Notifications and real-time events

`order_cancelled` inbox row for the customer and for the provider, plus `order.updated` with `reason: cancelled` on both sockets
(refetch the order). The customer's order details show `cancellation.cancelled_by.value = provider`.

## 8. Localization and UI notes

All messages follow `Accept-Language` (`ar` / `en`). Cancel is a destructive action: confirm it, and explain that the customer is refunded in full.

## 9. Integration checklist

- [ ] Cancel button driven by `can_cancel`
- [ ] Reason is optional, max 500
- [ ] The three 422 codes handled
- [ ] Order refetched on `order.updated` (`cancelled`)
- [ ] Cancelled tab refreshed

## 10. Acceptance scenarios

| AC ID | Scenario | Expected |
|-------|----------|----------|
| AC-PROV-016 | Cancel a paid confirmed order before execution | 200 `cancelled`, customer wallet credited in full, no earning, customer notified |
| AC-PROV-016 | Cancel after departure | 422 `ORDER_CANCELLATION_LOCKED` |
| AC-PROV-016 | Cancel a request she has not accepted | 422 `INVALID_STATE_TRANSITION` |
| AC-PROV-016 | Cancel a scheduled order awaiting payment | 200 `cancelled`, no refund |
| AC-PROV-016 | Cancel twice | Second call 200, one refund |
| AC-PROV-016 | Another provider's order | 404 |

## 11. Open decisions and known limitations

| ID | Impact | Current behavior |
|----|--------|------------------|
| DEC-24 | Provider ranking penalty | None |
| DEC-07 | Driver cancellation or no-show after accepting | Not part of this feature |
| TD-155 | Share of a cancellation fee | A provider cancellation never charges a fee |
