# Customer app

How the customer app works with the API today. Shared rules (headers, errors, phone format, image compression) are in [common.md](common.md).

## 1. Login with phone

The customer logs in with a phone and an OTP. The account is created only after a successful OTP login — requesting an OTP alone does not create a customer row.

```
POST /authentication/requestLoginOTP   { "phone": "+966 512345678", "role": "CUSTOMER" }
POST /authentication/login             { "phone": "+966 512345678", "role": "CUSTOMER", "otp": "1234", "fcm": "..." }
```

Use the country code picker and phone format from [common.md](common.md#phone-format). Send the same `phone` string on both calls.

Profile photo: `PATCH /user/profile` with `image` (compressed).

The profile's `coupon` number is how many coupons the admin made for this customer by name. If you show it, label it "Coupons for you".

## 2. Stores and categories

After the user picks a module:

```
GET /store?moduleId={moduleId}            stores
GET /category?moduleId={moduleId}         filter chips (id, name, image)
GET /store?moduleId={moduleId}&categoryId={categoryId}     after tapping a chip
```

Always send `moduleId`. Clearing the chip reloads stores with `moduleId` only. `isOffer=true` and `freeDelivery=true` (stores with their own free-delivery threshold) work as filters.

Order: when the app sends no `orderBy`, stores with a running package come first (by the package's priority), then by rating. Keep the order the API returns. A package never adds a store outside the customer's zone or the search. `GET /store/nearest` keeps its distance order.

On each store card:

| Field | Use |
| --- | --- |
| `shippingCharge` | Full delivery price to the customer's location (platform price by distance from the branch). `null` when there is no home delivery to this location. Never `0` for "free" |
| `homeDeliveryAvailable` | `false`: the customer is outside the store's zone (or the store has no location). Show the store, but takeaway / car only |
| `freeDeliveryFrom` | Lowest products total that makes delivery free here (platform or store threshold). `null` = none. Show "Free delivery over X" |
| `closed` | `true` when the store is not open for orders right now. Always `true` or `false`. |
| `reservationsEnabled` | Whether the Reserve button is enabled (section 7) |
| `isFavorite` | Heart icon (below) |

### Favourite stores

Every store the customer app gets back carries `isFavorite` and `FavoriteStore`, in the same shape: `GET /store` (with any filter, including search and offers), `GET /store/nearest` and `GET /store/{id}`.

```json
{ "id": 13, "name": "nada store", "isFavorite": true, "FavoriteStore": [{ "storeId": 13, "customerId": 30 }] }
```

| `isFavorite` | `FavoriteStore` | Meaning |
| --- | --- | --- |
| `true` | One entry | The signed-in customer has this store as a favourite: filled heart |
| `false` | `[]` | Not a favourite, or no token (guest): empty heart |

Read `isFavorite`. `FavoriteStore` stays for older builds and always agrees with it.

Toggle with `GET /store/{id}/favourite` (token required). It is not a `POST`. The same call adds and removes, and returns the new state:

```json
{ "message": "change_store_favourite_successfully", "data": { "isFavorite": true } }
```

`true`: the store is now a favourite (filled heart). `false`: it was removed (empty heart). Set the heart from this value. The next store request returns the same state; the API does not cache it.

Lists return branches, and `GET /store/{id}` for a main store returns its default branch. The toggle resolves a main store `id` the same way, so the heart follows the store returned by the API whichever `id` the app sends.

`GET /store?favorite=true` lists the customer's favourite stores.

## 3. Store screen

Open the store with the selected address:

```
GET /store/{id}?lat={lat}&lng={lng}
```

Without `lat` and `lng` the API returns `lat_and_lng_required`. Reload the store when the address changes; do not cache these flags.

| Field | Use |
| --- | --- |
| `homeDelivery` | `true`: show home delivery at checkout. `false`: this address is outside the store zone; hide it. |
| `carDelivery` | `true`: show "Pickup in the car" at checkout (section 5) |
| `closed` | Ordering is not possible right now |
| `reservationsEnabled`, `reservationCancelHours` | Table booking (section 7) |
| `StoreSchedule`, `timezone` | Opening and closing time per day, in the store's `timezone` (IANA name). Convert to the phone's timezone before showing ([section 7](#opening-hours-and-timezone)) |
| `isFavorite` | Heart icon ([favourite stores](#favourite-stores)) |
| `Coupon` | Coupons this customer can use here ([below](#store-coupons)) |

### Store coupons

The store's `Coupon` array lists only the coupons this customer can use at this store now (store, customer, dates and uses are checked; the minimum is checked in the cart). Each item:

| Field | Use |
| --- | --- |
| `id`, `name` | Title |
| `discountType`, `discount`, `maxDiscount` | `PERCENTAGE`: "10% (up to 15)"; show "up to" only when `maxDiscount > 0`. `AMOUNT`: "20 off" |
| `minPurchase` | "On orders from 50" |
| `startDate`, `expireDate` | Exact instants (ISO, UTC). Show them in the phone's timezone |

The code is not listed: the customer types it ([section 4](#coupon)). Items have no `type` or `Zone`. There are no free-delivery coupons.

### Menu

The store response has no categories or products. Load them:

```
GET /category/subCategory?storeId={storeId}
```

`storeId` is required (a branch uses its main store's menu). Each item is a subcategory filter:

| Field | Use |
| --- | --- |
| `id`, `name`, `image` | The filter |
| `Parent.name` | Main category name |
| `SubProduct` | This store's active products in the subcategory that are still in stock |

The first item is always the Featured category (`id: 0`, "Recommended" / "مميزة" / "Polecane" / "Рекомендовані" by `Locale`). Hide it when its `SubProduct` is empty. A subcategory with an empty `SubProduct` shows an empty state.

Alternative with main categories: `GET /category?moduleId=` for chips, then `GET /product?storeId={storeId}&categoryId={categoryId}` (add `&subCategoryId=` to narrow).

**Out of stock (b053):** customer menu lists (`GET /category/subCategory`, `GET /product`, `GET /product/recommended`) **omit** products whose `stock` is `0`. `stock: null` means untracked (always listed). Do not show an Add button for a product that is not in the list. If `GET /product/{id}` returns `stock: 0`, hide or disable Add (checkout also returns `Insufficient stock`).

### Product fields

| Field | Use |
| --- | --- |
| `name`, `description`, `thumbnail` | Title, text, image |
| `price` | Price before discount |
| `totalPrice` | Price the user pays |
| `discount`, `discountType` | Offer badge. `PERCENTAGE`: `discount` is a percent ("-20%"). `AMOUNT`: `discount` is a fixed amount off ("-12"). `NONE` or `discount: 0`: no badge. Do not compute the price; use `totalPrice`. |
| `isOffer` | `true` when the product has a discount |
| `stock` | Remaining units, or `null` when not tracked. `0` = out of stock (not in list responses). |
| `maxPurchase` | Most units of this product per order. `0` = no limit. Cap the cart counter at the lower of `stock` and `maxPurchase`. Returned on lists and detail. |
| `rating` | Rating |
| `allergens` | Comma-separated text, e.g. `"Peanuts,Milk"`. Split on `,`, trim, show each. |
| `calories`, `color`, `size`, `type` | Detail rows |

Any detail field can be `null` or `""`; hide the row then. The detail fields are on `GET /product/{id}`, `GET /product`, `GET /product/recommended` and each product in `SubProduct`.

## 4. Cart

**Quantity cap (b099).** Keep the `stock` of each product (from the menu / `GET /product/{id}`). Disable the "+" button when the quantity of that product, **summed over all its cart lines**, reaches `stock` or `maxPurchase` (when it is above `0`), whichever is lower. `stock: null` means no limit. If the cart still goes over (stock changed since), `POST /cart` returns `400` "Insufficient stock. Only N available": show the message and set the line to N. N can be `0` (the product sold out while in the cart): mark the line "Out of stock" and let the user remove it. `GET /product/{id}` still returns a sold-out product with `stock: 0` (lists hide it), so never fall back to a generic "unexpected error" on this screen (b102).

```
POST /cart
```

Request:

```json
{
  "storeId": 1,
  "addressId": 10,
  "items": [
    { "productId": 12, "quantity": 1, "variationOptionsId": [3], "addons": [7] }
  ],
  "couponId": 5
}
```

`couponId` is optional: the id of the coupon applied with `POST /coupon/apply-discount-code` ([below](#coupon)). Send it on every cart call while a coupon is applied; leave it out with no coupon. `couponsId` is deprecated: it still works with one id, and two or more return `400` `Only one coupon can be used per order`.

Response:

```json
{
  "items": [
    {
      "productId": 12,
      "quantity": 1,
      "price": 130,
      "productDiscount": 0,
      "variationOptions": [
        { "id": 3, "name": "Large", "price": 5, "variation": { "id": 1, "name": "Size" } }
      ],
      "addons": [
        { "id": 7, "name": "Cheese", "price": 20 }
      ]
    }
  ],
  "price": 180,
  "tax": 0,
  "shipping": 0,
  "deliveryFee": 12,
  "freeDelivery": true,
  "freeDeliveryBy": "PLATFORM",
  "homeDeliveryAvailable": true,
  "homeDeliveryUnavailableReason": null,
  "homeDeliveryUnavailableMessage": null,
  "discount": 18,
  "coupon": { "id": 5, "applied": true, "code": "SALE10", "reason": null, "message": null },
  "total": 162
}
```

| Field | Use |
| --- | --- |
| `items[].price` | Line total: (product + options + add-ons) × quantity |
| `items[].productDiscount` | Offer saved on the line, already taken off `price` |
| `items[].addons[]` | Under the product: "name +price" |
| `items[].variationOptions[]` | Under the product: "variation.name: name +price" (not translated) |
| `price` | Products total |
| `tax` | Tax |
| `shipping` | What the customer pays for delivery: `0` when free or when home delivery isn't available |
| `deliveryFee` | Full fee before free delivery (platform price per km × distance from the branch, between the platform minimum and maximum) |
| `freeDelivery` | `true` when the platform (its threshold) or the store (its `freeDeliveryOver`) pays the delivery. The platform threshold is checked first |
| `freeDeliveryBy` | `PLATFORM`, `STORE` or `null`. Display only |
| `homeDeliveryAvailable` | `false`: no home delivery to this address (outside the store's zone). Offer takeaway / car only |
| `homeDeliveryUnavailableReason` / `homeDeliveryUnavailableMessage` | `OUTSIDE_ZONE`, `STORE_LOCATION_MISSING` or `CUSTOMER_LOCATION_MISSING`, and the translated message. `null` when available |
| `discount` | Coupon discount, already taken off `total`. `0` with no coupon, or when the coupon does not apply. Show it as its own line |
| `coupon` | The coupon sent: `applied`, and when not, `reason` and `message`. `null` when no coupon was sent |
| `total` | Grand total: products − coupon + tax + delivery |

- Always list add-ons under the product; the line price includes them.
- Show the "Free delivery" banner only when `freeDelivery` is `true`, with `deliveryFee` struck through. Do not treat a missing fee as free. Free delivery comes from the platform or the store threshold, never from a coupon.
- `POST /order` with `HOME_DELIVERY` to an address outside the store's zone returns `400` with the same message as `homeDeliveryUnavailableMessage`.
- Use `total` as returned. Do not subtract the coupon again, do not add delivery again, and do not compute free delivery in the app. No commission is ever added for the customer.
- A store that can't take orders yet (no tax or no commission set) returns `400` `This store can't take orders yet` (translated). Show the `message`.

### Coupon

One coupon per order. Show the coupon field as one code with a "Remove" button, not a list of codes. Applying a second coupon replaces the first.

Coupons are a percentage or a fixed amount off the **products** only (the cart's `price`, after item offers). Tax and delivery are not part of them, and a coupon never takes off more than the products total.

When the customer types a code:

```
POST /coupon/apply-discount-code
{ "code": "SALE10", "storeId": 12, "price": 180 }
```

`price` is the cart's `price` (products total after item offers): not `total`, no tax, no delivery. The code is not case-sensitive.

`201` response `data`:

| Field | Use |
| --- | --- |
| `id` | Send it as `couponId` on the cart and the order |
| `code`, `name` | The applied code and title |
| `discountType`, `discount`, `maxDiscount` | `PERCENTAGE` (`discount` is %, capped at `maxDiscount` when above 0) or `AMOUNT` (money) |
| `discountAmount` | What the coupon takes off the products now |
| `priceAfterDiscount` | Products after the coupon (tax and delivery come on top in the cart) |
| `startDate`, `expireDate` | Validity (ISO, UTC) |

When the coupon can't be used, the answer is `400` and `message` is the reason, translated by `Locale`:

| Reason | `message` (`en`) |
| --- | --- |
| `coupon_not_found` | Coupon not found |
| `coupon_store_not_included` | This coupon doesn't cover this store |
| `coupon_customer_not_targeted` | This coupon isn't available for your account |
| `coupon_inactive` | This coupon is switched off |
| `coupon_not_started` | This coupon hasn't started yet |
| `coupon_expired` | This coupon has expired |
| `coupon_min_purchase_not_met` | Your products are below this coupon's minimum |
| `coupon_uses_per_customer_reached` | You've used this coupon the most times allowed |
| `coupon_max_customers_reached` | This coupon has reached its number of customers |

Show `message` as returned. Then call `POST /cart` with `couponId` and show `discount` and `total` from the cart.

The cart checks the coupon again on every call and does **not** fail when it no longer fits (for example the products went below the minimum after an item was removed):

```json
"discount": 0,
"coupon": {
  "id": 5,
  "applied": false,
  "code": null,
  "reason": "coupon_min_purchase_not_met",
  "message": "Your products are below this coupon's minimum"
}
```

`total` then leaves the coupon out. When `coupon.applied` is `false`, show `coupon.message` next to the coupon field and do not send the coupon on the order. Recheck after every cart change: adding or removing items, changing quantity, changing store.

A coupon of a restaurant also works on its branches. A customer can use the same coupon on several orders while it has uses left for them.

## 5. Place an order

```
POST /order
```

```json
{
  "items": [{ "productId": 1, "quantity": 1 }],
  "storeId": 1,
  "addressId": 10,
  "couponId": 5,
  "deliveryStatus": "HOME_DELIVERY",
  "payWithWallet": false,
  "paymentMethod": "CASH"
}
```

- Send `HOME_DELIVERY` only when `homeDelivery` was `true` for this address. `addressId` is required for it.
- Do not send `deliverySource` or a company id; the API decides who delivers.
- A store with home delivery off returns `home delivery is not supported for this store`.
- `couponId` is optional: send it only when the last cart call returned `coupon.applied: true`. `couponsId` is deprecated (one id at most, like the cart).
- A store that can't take orders yet (no tax or no commission set) returns `400` `This store can't take orders yet`.
- All error `message`s are translated by `Locale`. Show them as they are; never compare them with a fixed string.

### Coupon on the order

`POST /order` checks the coupon again and holds one use of it for the customer. On `400`, show `message`: it can be any reason from the [coupon table](#coupon), or `coupon_changed_try_again` ("The coupon changed. Check the cart and try again") when the coupon was edited between the cart and the order. Then reload the cart and let the customer confirm again.

The use is given back when the order ends without delivery: `CANCELLED`, `REJECTED`, `MISSED` or `PAYMENT_FAILED`. The customer can then use the coupon again while it is valid. A delivered order keeps the use, even after a refund (`REFUND`).

### Order money

Show the order's money fields as described in [common.md](common.md#order-money-fields): `price` "Products", `tax`, `shipping` "Delivery", `discountAmount` "Coupon", `paidWithWallet` "Paid from wallet", and `totalPrice` "Total to pay". `finalPrice` is the value **before** coupon and wallet; it is not an amount to pay. Never compute the total in the app.

### Card payment (`paymentMethod: "VISA"`)

1. `POST /order` as usual. The response `data.price` is the **amount still to charge on the card** (order total minus any wallet used). Charge Moyasar for exactly that amount (minor units = `round(price * 100)`).
2. After the gateway returns a paid payment id:
   ```
   POST /order/{id}/payment
   { "paymentId": "<moyasar payment id>" }
   ```
3. Success marks the order `paymentStatus: PAID`. A wrong amount, unpaid payment, or gateway error returns `400` with `Payment failed, please try again` (translated) and may set the order to `PAYMENT_FAILED`.
4. Do not charge `finalPrice` / full cart total when `payWithWallet` was true — only `data.price` from the create response (or `order.totalPrice` on reload). Idempotent: calling payment again on an already-paid order succeeds without re-charging.

### Pickup in the car

The customer drives to the restaurant, waits in the car, and staff bring the order out. The restaurant finds the car by its details. No driver and no delivery fee.

Saved cars:

| Call | Body |
| --- | --- |
| `GET /user/car-delivery` | — (the customer's cars) |
| `POST /user/car-delivery` | `car`, `model`, `color`, `plate`, `license` (all required) |
| `PATCH /user/car-delivery` | `carId` plus the fields to change |
| `DELETE /user/car-delivery/{id}` | — |

- A second car with the same `plate` returns `409` `Car already exists`.
- A car that is not the customer's (or was deleted) returns `404`.

Order with `"deliveryStatus": "CAR_DELIVERY"` and `carDeliveryId`, no `addressId`:

```json
{
  "items": [{ "productId": 1, "quantity": 1 }],
  "storeId": 1,
  "deliveryStatus": "CAR_DELIVERY",
  "carDeliveryId": 3,
  "payWithWallet": false,
  "paymentMethod": "CASH"
}
```

| `message` | When |
| --- | --- |
| `car delivery id is required` | No `carDeliveryId` |
| `car delivery is not supported for this store` | Store has `carDelivery: false` |
| `car delivery is not supported now` | Turned off for the whole platform |

The order returns the car as `Car`. When the customer reaches the restaurant, show an "I've arrived" button:

```
PATCH /order/{id}
{ "arrived": true }
```

The restaurant gets a push and brings the order out. The order then has `customerArrived: true`; hide the button. Repeated taps do not resend the push.

| `message` | When |
| --- | --- |
| `Only car delivery orders can be marked as arrived` | Order is not `CAR_DELIVERY` |
| `Order is already closed` | Order is `DELIVERED`, `CANCELLED`, `REJECTED`, `REFUND`, `MISSED` or `PAYMENT_FAILED` |

### Send a parcel

The parcel price is the fee of the size the customer picks. It does not depend on the distance or on the contents' value.

Sizes:

```
GET /parcel-size
```

```json
{
  "data": [
    { "id": 1, "name": "Small", "description": "Up to 30×30×30 cm, 5 kg", "fee": 15, "sortOrder": 1, "isActive": true },
    { "id": 2, "name": "Medium", "description": "Up to 50×50×50 cm, 15 kg", "fee": 25, "sortOrder": 2, "isActive": true }
  ],
  "total": 2
}
```

`name` and `description` come in the `Locale` language. The list is already sorted; show it in this order. Show each size as a choice (name, description, fee). The customer must pick one before continuing. Show the chosen size's `fee` as "Delivery fee" and as the total.

Price check (optional, returns the same number as the size `fee`):

```
POST /order/calculate-shipping
{ "parcelSizeId": 2 }
```

Response: `data.data` is the price, e.g. `25`.

Create the parcel order:

```
POST /order/parcel
```

```json
{
  "parcelSizeId": 2,
  "senderPoint": "24.7136,46.6753",
  "receiverPoint": "24.7743,46.7386",
  "paymentMethod": "CASH",
  "payWithWallet": 0,
  "details": "Documents",
  "place": "Office 3",
  "quantity": 1,
  "price": 300
}
```

| Field | Rule |
| --- | --- |
| `parcelSizeId` | Required. An active size from `GET /parcel-size` |
| `senderPoint`, `receiverPoint` | Required. `"lat,lng"` |
| `paymentMethod` | Required. `CASH` (the sender pays the driver at pickup), `VISA` or `WALLET` |
| `payWithWallet` | Required. `1` to use the customer wallet first, `0` not to |
| `details`, `place`, `quantity` | Optional |
| `price` | Optional. Declared value of the contents, display only: never charged or used for any fee |

Response (`201`):

```json
{ "orderId": 91, "shipping": 25, "price": 25, "paymentMethod": "VISA" }
```

`price` is what is left to pay after the wallet: `0` when the wallet covered it all.

- `CASH`: show "Pay the driver {price} at pickup".
- `VISA` with `price > 0`: charge Moyasar for exactly `price` (minor units `round(price * 100)`), then `POST /order/{orderId}/payment` with `{ "paymentId": "..." }`, as for a [card order](#card-payment-paymentmethod-visa). Drivers are notified only after this succeeds.
- `price` is `0`: paid from the wallet, nothing to charge.

| Error | Status | `message` (`en`, translated by `Locale`) |
| --- | --- | --- |
| Size missing, inactive or deleted | `404` | `Choose an available parcel size` |
| No `parcelSizeId` (on `calculate-shipping` or `parcel`) | `400` | Validation message |

### Track the driver

Reload the order every 15–30 seconds while it is `WAITING_DELIVERY`, `ON_THE_WAY` or `DRIVER_ARRIVED`:

```
GET /order?id={id}
```

| Field | Use |
| --- | --- |
| `status` | Order step |
| `DeliveryMan.User` | Driver name and phone |
| `DeliveryMan.lat`, `DeliveryMan.lng` | Driver position on the map (the driver's last reported location) |
| `estimationTime` | Estimated time to arrive |

The `/location` socket does not send driver locations to the customer app. Do not use `location_update` or `active_location_{id}` events.

## 6. Rate the driver

```
POST /review
```

```json
{
  "deliveryId": 45,
  "orderId": 1203,
  "rating": 4,
  "ratingQuality": 5,
  "ratingCommitment": 4,
  "ratingCommunication": 3,
  "comment": "Polite, a bit late"
}
```

| Field | Label | Required |
| --- | --- | --- |
| `ratingQuality` | Service quality | Yes (1–5) |
| `ratingCommitment` | Punctuality | Yes (1–5) |
| `ratingCommunication` | Communication | Yes (1–5) |
| `rating` | Not shown | Yes: average of the three, rounded to a whole number |
| `comment` | Comment | No |

Each value is an integer from 1 to 5. A second review of the same `orderId` returns `409` with `message`: `You Reviewed this before`. Show it as it is.

## 7. Table booking

### Reserve button

Enable Reserve from `reservationsEnabled` only. A store can be `closed: true` and still take a booking for another day. Reload the store when opening the store screen and the booking form.

### Opening hours and timezone

`StoreSchedule` times are the store's own clock (`08:00` is 08:00 where the store is). `Store.timezone` says where that is, e.g. `Europe/Warsaw`.

- Show hours converted to the phone's timezone: Warsaw 09:00 to 17:00 shows as 10:00 to 18:00 in Cairo. A day can change when converting; convert the day with the time.
- Send `reservedAt` as an ISO instant (`2026-11-11T16:59:00.000Z` or with an offset). The API checks it in the store's timezone. A time at or after closing is refused with the `400` below.
- Show the booking time (`reservedAt`) in the phone's timezone.

### Fee

Before booking, read the fee from `GET /settings?domain=CUSTOMER` (values are strings):

| `setting` | Meaning |
| --- | --- |
| `tableReservationFeeAmount` | Full fee per booking |
| `tableReservationCustomerSharePercent` | Customer's share in percent |

Customer fee = amount × share / 100, rounded to 2 decimals. Show it as "Reservation fee"; hide it when `0`.

### Create

```
POST /table-reservation            (logged in)
POST /table-reservation/public     (guest)
```

`guestPhone` uses the phone format. A refused booking returns `400` with `message` in `en`, `ar`, `pl` or `uk`:

| `en` | `ar` |
| --- | --- |
| Reservations are currently closed for this restaurant | الحجوزات مغلقة حاليًا لهذا المطعم |
| This time is outside the restaurant's opening hours | هذا الوقت خارج ساعات عمل المطعم |

### After booking

`GET /table-reservation` and `GET /table-reservation/{id}` return:

| Field | Use |
| --- | --- |
| `customerFeeAmount` | "Reservation fee". Fixed at booking time; later fee changes do not affect it. |
| `feePaid` | `true` when nothing is owed |
| `Store.reservationCancelHours` | Always present. The key is `Store` with a capital S. |
| `feeAmount`, `storeFeeAmount` | Do not show |

### Cancel

Customers can cancel up to `Store.reservationCancelHours` hours before `reservedAt`. Use that number; do not assume one.

```
PATCH /table-reservation/{id}/cancel
```

- Before the deadline: show Cancel and "Cancel before {deadline}". Show the hours from `reservationCancelHours` on the booking form too, e.g. "Free cancellation up to {n} hours before".
- After it: hide Cancel and show "This reservation can no longer be cancelled".
- Never show Cancel for `CANCELLED`, `COMPLETED` or `NO_SHOW`.
- Still handle the `400` (the phone clock can differ): `Cancellation must be at least 2 hour(s) before reservation time`, translated in all four languages.

`customerFeeAmount` is fixed when the booking is created. The API does not charge a card and does not refund: `feePaid` is `true` only when the fee is 0. Cancelling in time sets the status to `CANCELLED` and does not move money.

## 8. Refund of a delivered order

Since 2026-11-19 ([handoff](update-2026-11-19-settlements.md#1-customer-app-refund-request)). A refund is **money only**: the amount goes to the customer's wallet, and nothing is picked up.

### Rules
- **Delivered orders only** (`status = DELIVERED`).
- **Time window:** within the days the admin set after `deliveredAt` (3 by default). The admin can also turn refund requests off.
- **One open request per order**, and an order is refunded once at most.
- **The admin decides:** approves with an amount (up to what the customer paid), or rejects with a reason.

### Reasons

```
GET /refund/reason
```

### Ask

```
POST /refund/requests        (multipart/form-data)
orderId=1593  reasonId=2  note=...  image=<file, optional>
```

`201` returns the request in status `PENDING`. A `400` returns a translated `message`, shown as is. The cases:
- Refunds are off.
- The order isn't delivered.
- The window has passed.
- A request is already waiting.
- The order was already refunded.

### My requests

```
GET /refund/requests?orderId=1593
GET /refund/requests/{id}
```

| Field | Show |
| --- | --- |
| `status` | `PENDING` "Under review", `APPROVED` "Refunded", `REJECTED` "Rejected" |
| `amount` | Refunded amount (when approved) |
| `rejectReason` | Why it was rejected |
| `paid` | What the order can give back at most |
| `source` | `ADMIN`: the admin refunded the order without a request |

### After a decision
- **Push:** `data.type = "REFUND_STATUS"` with `orderId`, `refundRequestId` and `status`. The in-app notification is in the `Locale` language.
- **When approved:**
  - The amount is in the wallet: reload it. The wallet history has an `ORDER_REFUND` line with reference `refund:{id}`.
  - The order status is now `REFUND`.

## Checklist

- [ ] Country code picker and spaced phone on OTP and login
- [ ] Store list sends `moduleId`; category chips reload stores
- [ ] Heart reads `isFavorite` on every store list and the store screen; toggle with `GET /store/{id}/favourite` and set the heart from its `isFavorite`
- [ ] Store screen sends `lat`/`lng`; home delivery follows `homeDelivery`
- [ ] Menu from `GET /category/subCategory`; empty Featured tab hidden
- [ ] Product details show allergens, calories, color, size and type when present
- [ ] Cart lists add-ons and options; delivery row from `shipping`; total as returned
- [ ] One coupon: `apply-discount-code` sends the cart `price`; cart and order send `couponId` (not `couponsId`); a second coupon replaces the first
- [ ] After every cart call, read `coupon.applied`; when `false`, show `coupon.message` and drop the coupon from the order
- [ ] Coupon and order `400`s show `message` as returned; `coupon_changed_try_again` reloads the cart
- [ ] Store page coupons: no `type` / `Zone`, no code; dates in the phone's timezone; no free-delivery coupon handling
- [ ] `This store can't take orders yet` (`400`) shown on cart and order
- [ ] Order details show `totalPrice` as "Total to pay", coupon and wallet as separate lines; never `finalPrice` as the amount to pay
- [ ] Order sends no `deliverySource`
- [ ] Parcel: sizes from `GET /parcel-size`; order sends `parcelSizeId`; card parcels charge `price` from the create response, then `POST /order/{id}/payment`
- [ ] Car pickup follows `carDelivery`; saved cars list; order sends `carDeliveryId`; "I've arrived" until `customerArrived` is `true`
- [ ] Driver tracking reloads `GET /order?id=` and reads `DeliveryMan.lat` / `lng`; no location socket
- [ ] Driver rating sends the three criteria and their rounded average
- [ ] Reserve follows `reservationsEnabled`; fee and cancel deadline shown; cancel `400` handled
- [ ] Delivered order: "Request a refund" (reason, note, photo) while no request is open; the request status is shown on the order; `REFUND_STATUS` push reloads the wallet and the order
