# Mobile changelog

What changed in the API for the mobile apps, newest first. Each item links to the section that describes the current behaviour.

## 2026-11-19 — answers to the app requests

Handoff: 🆕 [update-2026-11-19-app-requests.md](update-2026-11-19-app-requests.md).

### Restaurant app

- 🆕 `GET /order/statistics`: `waitingDeliveryAcceptanceOrders`, `waitingDeliveryOrders` (home delivery only).
- 🆕 Vendor `GET /product?id=` and `GET /addon` always return `translations`; ❗ PATCH product/category/addon now **merges** `translations` per language and field.
- ❗ `PATCH` / `DELETE /addon/{id}` return `403` for another store's addon.
- ❗ Decimal variation option / addon `price` returns `400` (whole numbers only).

### Customer app

- ❗ `POST /order/{id}/payment`: a `paymentId` is single-use (`400 PAYMENT_FAILED` on reuse), and only the order's customer can pay (`403`).

### All apps

- `X-Timezone` is optional: a missing or invalid header is not rejected. Payment currency is not checked yet (decision pending).

## 2026-11-19 — settlements and refunds (phase 6)

Handoff: 🆕 [update-2026-11-19-settlements.md](update-2026-11-19-settlements.md).

### Customer app

- 🆕 Refund of a delivered order: `POST /refund/requests` (reason, note, photo) within the admin's window, `GET /refund/requests`, and the `REFUND_STATUS` push. The amount goes to the wallet; the order becomes `REFUND`. [Customer app](customer-app.md#8-refund-of-a-delivered-order)

### Restaurant app

- ❗ Withdraw requests are closed for restaurants: `POST /withdraw` returns `403`. Payouts come by **settlements** each cycle, to the default bank account. New `GET /settlements`, `/settlements/summary`, `/settlements/{id}`, `/settlements/{id}/entries`, and `PATCH /store-bank/{id}/default`. [Restaurant app](restaurant-app.md#11-wallet-and-settlements)
- New ledger types: `REFUND`, `SETTLEMENT_HOLD`, `SETTLEMENT_PAID`.

### Driver app

- No change: drivers keep withdraw requests.

## 2026-11-19 — store registration and "Company fleet"

Handoff: 🆕 [update-2026-11-19-full.md, section 8](update-2026-11-19-full.md#8--store-registration-full-spec) (added in the second version of that file).

### Restaurant app

- ❗ The registration form now has **Default delivery source**. With **Company fleet** (`STORE_FLEET`) the user picks the fleet company (`fleetCompanyId`) from the new public `GET /driver-company/fleet-options`. [Store registration](store-registration.md#delivery-settings)

### All apps

- The label "Store fleet" is now "Company fleet" in every language. The value stays `STORE_FLEET`.

## 2026-11-19 — delivery price

Handoff: [update-2026-11-19-delivery.md](update-2026-11-19-delivery.md).

### Customer app

- ❗ Delivery is priced by the platform only, by distance from the branch. Store cards: `shippingCharge` is the full price, `null` with no home delivery; new `homeDeliveryAvailable` and `freeDeliveryFrom`. [Customer app](customer-app.md#2-stores-and-categories)
- ❗ No home delivery outside the store's zone: the cart returns `homeDeliveryAvailable: false` with a reason, and `POST /order` returns `400`. [Customer app](customer-app.md)
- Cart: new `deliveryFee` (full fee) and `freeDeliveryBy`. Free delivery comes from the platform or the store threshold.

### Restaurant app

- ❗ `deliveryFee` is removed from the registration form and `PATCH /store` (ignored if sent). [Store registration](store-registration.md)
- New `freeDeliveryOver`: free delivery from a products total, paid by the restaurant. [Restaurant app](restaurant-app.md#free-delivery)
- Order money: `waivedShipping` / `waivedShippingByStore`; `storeNet` takes off the delivery the restaurant paid. [Restaurant app](restaurant-app.md#8-order-money)

## 2026-11-19

Handoff: [update-2026-11-19-packages.md](update-2026-11-19-packages.md).

### Restaurant app

- ❗ A package is a commission and a listing priority only. No feature switches, and no limit on orders or products. Duration is `durationValue` + `durationUnit`. [Restaurant app](restaurant-app.md#10-subscription-packages)
- ❗ No new package while one runs (`canSubscribe`). Renew only in the last 3 days, starting at the current end (`canRenew`). [Restaurant app](restaurant-app.md#10-subscription-packages)
- New: cancel with `POST /plan/my-subscription/cancel { confirm: true }`, after the full warning. Stops at once, no refund. [Restaurant app](restaurant-app.md#cancel)
- ❗ `POST /store/{id}/payment` (old platform subscription) is removed.

### Customer app

- `GET /store` lists stores with a running package first, then by rating, unless the app sends `orderBy`. [Customer app](customer-app.md#2-stores-and-categories)



Handoffs: [update-2026-11-18.md](update-2026-11-18.md), [money](update-2026-11-18-money.md), [driver tiers](update-2026-11-18-driver-tiers.md), [coupons](update-2026-11-18-coupons.md), [store commission](update-2026-11-18-store-commission.md), [wallet and withdrawals](update-2026-11-18-wallet-withdraw.md). The app files below now include all of them.

### All apps

- Error messages, validation errors included, come back in the `Locale` language. Never compare `message` with a fixed string. [common.md](common.md#errors)
- Two driver pushes now carry `data`: `DRIVER_TIER_CHANGED` and `WITHDRAW_STATUS`. [common.md](common.md#pushes)
- No commission is ever added for the customer. [Order money fields](common.md#order-money-fields)

### Customer app

- One coupon per order: send `couponId` (`couponsId` still works with one id). The cart says whether the coupon applies and why. No free-delivery coupons. Admin coupons can be used on several orders. [Customer app](customer-app.md)
- Parcels are priced by size: `GET /parcel-size`, then the order with the size. The contents' value is shown only. [Customer app](customer-app.md)
- A store without a commission set can't take orders yet: `400` with a translated message. [Customer app](customer-app.md)

### Driver app

- ❗ What to collect: read `paymentMode` (`PAID` / `COLLECT_CASH`) and `collectAmount` on the order. Nothing is ever paid to the store. [Driver app](driver-app.md)
- ❗ Earnings follow the driver's tier (and company). The tier on the profile shows the terms. A driver without terms gets no orders. [Driver app](driver-app.md)
- ❗ Top up any amount: `POST /delivery/wallet/topup` (`payroll` still works, same way). Debt is covered first. Wallet shows `available`, `debt`, `held`, `debtLimit`. [Driver app](driver-app.md)
- ❗ Above the debt limit (500 on staging) no cash orders: `400` `driver_debt_limit_reached`. [Driver app](driver-app.md)
- ❗ Withdraw statuses: `PENDING_REVIEW` → `APPROVED_AWAITING_TRANSFER` → `TRANSFERRED`, or `REJECTED` (reason). No instant payout. [Driver app](driver-app.md)
- Wallet history: `GET /ledger`. [Driver app](driver-app.md)

### Restaurant app

- Commission is per store, set by the admin, read only in the app (`currentCommission` on `GET /store`). A package's commission replaces it while the subscription runs. A paid package no longer means 0%. [Restaurant app](restaurant-app.md)
- Paid packages are activated only with a paid Moyasar payment. [Restaurant app](restaurant-app.md)
- ❗ Withdraw statuses changed (same 4 as the driver), with `rejectReason` and `transferReference`. [Restaurant app](restaurant-app.md)
- New: `GET /plan/my-subscription` gives the running subscription (status, end date, days left, commission) and the history. [Restaurant app](restaurant-app.md)
- Wallet history (`GET /ledger`) shows the store's own rows; a branch sees its own, like its wallet.

## 2026-11-17

Handoff: [update-2026-11-17.md](update-2026-11-17.md).

- Order money fields: `totalPrice` is what is left to pay, `finalPrice` is before coupon and wallet. [common.md](common.md#order-money-fields)
- Fixed-amount coupons give their full amount, and coupons with no usage limit work. [Customer app](customer-app.md)
- Marking an order delivered is safe to retry. A withdraw request only touches the requester's own wallet. [Driver app](driver-app.md)
- The restaurant's earnings include the wallet-paid part, and platform coupons are no longer charged to it. [Restaurant app](restaurant-app.md)

## 2026-11-12

### Rewards and loyalty points (customer app)

- **Rewards:** `POST /rewards/use` `{ code }` is unchanged. The reward's value lands in the profile's `rewards` (a **locked** balance, not spendable). When an order is delivered and its item subtotal reaches the reward's minimum order, the value moves from `rewards` to `wallet`, and the customer can pay with it (`payWithWallet`) on the next order. Label `rewards` as pending, not as available balance, and refresh the profile after an order is delivered.
- **Points are earned on delivery, not when the order is placed:** `floor(item subtotal x points per currency)`. A cancelled order earns nothing. `earningPoints` on the profile no longer jumps at checkout.
- `POST /transaction/convert-points` `{ points }`: customer role only; `points` must be a whole number of 1 or more. It converts at the admin-set rate (points needed per 1 currency) and moves the points to `wallet`. It returns `400` when loyalty is switched off, below the minimum, not enough points, or fewer points than 1 currency needs. Before this, any amount above 1 point was refused. Show the error message.

### Store registration: delivery and booking fields (b065)

- The register form was missing fields the admin form has. `POST /store` already accepted them (no API change); the docs wrongly said not to send `deliveryFee`, and did not list the booking fields. Add a **Delivery and booking** block: `reservationsEnabled` (`true`/`false`, default `true`), `reservationCancelHours` (whole number, default `2`) and `deliveryFee` (optional; leave it out when blank, the fee is then calculated from the distance. `0` means free delivery).
- `defaultDeliverySource` stays off the app form: `STORE_FLEET` needs a fleet company that only an admin can link, so a new store is always `PLATFORM` until an admin changes it. [Store registration](store-registration.md#delivery-settings)

## 2026-11-11

### Store hours were saved an hour earlier (b091)

- `POST /store/schedule` saved the typed time in the server's timezone, so `09:00` could be stored as `08:00`. It now stores exactly the time sent (`HH:MM`). `openingTime` and `closingTime` come back as `1970-01-01T09:00:00.000Z`: the clock is the **UTC part** of the value, not the phone's local time.
- Restaurant app: read the hour and minute from the UTC part when showing or editing saved hours (do not convert to the phone's timezone), and send `HH:MM` as typed. [Restaurant section 7](restaurant-app.md#7-store-hours). The customer app converts from the store's `timezone` ([customer section 7](customer-app.md#opening-hours-and-timezone)).
- Hours saved before this fix can be 1 to 2 hours early. Edit them once: delete the day and add it again.

### Table booking and opening hours use the store's timezone (b110)

- A customer could book a table outside the opening hours. The hours (`StoreSchedule`) are the store's own wall-clock times with no zone, and the API compared them in the server's zone. Every store now has `timezone` (IANA, e.g. `Europe/Warsaw`), taken from its country, and the booking check and `closed` use it. A booking at or after the closing time is refused with `400` "This time is outside the restaurant's opening hours".
- `Store.timezone` is returned wherever a store is returned. The app must not show `StoreSchedule` as-is: convert each time from `timezone` to the phone's timezone before showing it, so a customer in Cairo sees a Warsaw 09:00 as 10:00. Show the booking time in the phone's timezone as before. Send `reservedAt` as an ISO instant (with `Z` or an offset). [Section 7](customer-app.md#7-table-booking)

### Names stay in English after switching to Polish / Ukrainian (b088)

- `GET /modules`, `GET /category` and `GET /category/subCategory` already return `name` in `pl` and `uk` when the request carries `Locale: pl` / `Locale: uk`. The only server fix: the Featured tab (`id: 0`) of `GET /category/subCategory` was "Recommended" for every language except Arabic. It is now `Polecane` (`pl`) and `Рекомендовані` (`uk`).
- If a screen still shows English after the language change, the app is not sending the new `Locale` or is showing a cached response. Set the header per request from the current language, and refetch modules, categories, stores and products when the language changes. [Common rules](common.md#requests)

### Customer cart: product sold out while in the cart (b102)

- `GET /product/{id}` no longer fails for a customer when the product just sold out. Before, it returned nothing and the server answered `500`, which the app showed as "An unexpected error occurred". Now it returns the product with `stock: 0`. Product **lists** still hide sold-out items.
- The app must not show a generic error here. When the cart gets `400` "Insufficient stock. Only N available" (N can be `0`), show that message on the line and set it to N; at `0`, mark the line "Out of stock" and let the user remove it. [Cart](customer-app.md#4-cart)

### Customer cart: coupon discount now applied (b100)

- `POST /cart` accepts `couponsId` (ids of the applied coupons) and returns `discount` plus a `total` that already has the discount taken off. Before, the cart ignored coupons, so applying a coupon changed nothing in the summary.
- The app must send `couponsId` on every `POST /cart` while a coupon is applied, show `discount` as its own line, and use `total` as returned (do not subtract the coupon locally). A free-delivery coupon returns `shipping: 0` and `freeDelivery: true`. [Cart](customer-app.md#4-cart)

### Customer cart: quantity above stock (b099)

- `POST /cart` and order create now check the **combined** quantity of a product across all cart lines (same product with different options shares one stock), and the `400` message is translated and includes the count: "Insufficient stock. Only 3 available". Quantity must be a whole number of at least 1.
- `maxPurchase` is now enforced too: if the combined quantity of a product exceeds it (`maxPurchase > 0`), `POST /cart` and order create return `400` "You can buy at most N of this product per order". `maxPurchase` is returned on product detail **and** list items (`GET /product`, `/product/recommended`, `GET /category/subCategory`).
- Order create decrements stock atomically: if another order took the last units a moment earlier, it returns the same "Insufficient stock" `400` and nothing is saved, instead of letting stock go negative.
- The API only rejects; it cannot stop the counter. The app must cap the "+" button at the product's `stock` (when not `null`), summed over lines of the same product. [Cart](customer-app.md#4-cart)

### Driver app: profile edit needs the renewed document first

- `POST /delivery/profile-edit-request` (and `PATCH /user/profile` / `PATCH /delivery`, which create the same request) now returns `400` when the driver's licence or ID is expired and the request does not include the new expiry date and both new photos for that document. Before, a driver suspended for an expired document could send any other change (name, email…) and skip the renewal. Keep Update disabled until `expiredDocuments` rows have a new date and photos. [driver-app.md](driver-app.md#9-expired-documents)

## 2026-11-08

### Admin customer detail: Total Orders matches the orders table

- `GET /customer/:id` (and the customer list) now sets `User.totalOrders` / `User.totalPrice` from live `order` aggregates for that customer. The nested `_count.Orders` field was returning `0` on detail while the orders table listed real rows.

### Orders list pagination no longer repeats/skips rows

- `GET /order` (and driver-company orders) sorts by `createdAt desc, id desc`. Equal timestamps no longer reshuffle across pages, so page 2+ shows the remaining orders instead of duplicates. Admin customer order tables pass an explicit `limit` with the pager.

### Orders: partial `name` / `search` finds order ids by prefix

- `GET /order?name=` (and alias `?search=`) digit terms match the order id as a **prefix** (`150` → `1501`, `1502`, …), not only exact id. Still matches customer/driver/store/product/phone/note/status words. Prefer `name`; `search` is accepted so clients that copy the reservation param do not get `400 property search should not exist`.

### Restaurant app: product create no longer fails on empty discount fields

- `POST /product` treats empty multipart fields (`discountType=`, `discount=`, `calories=`, `unitId=`, empty `allergens`/`addon`) as omitted instead of invalid enum / Prisma 500. `discountType` is a single enum (`PERCENTAGE` | `AMOUNT` | `NONE`), not an array. Missing thumbnail returns `400` with a clear message. Vendor `POST /category` fills `moduleId`/`storeId` from the logged-in store. Show API `message` on failure. [restaurant-app.md](restaurant-app.md#add-product-post-product)

### Every app: currency from settings (not hardcoded Riyal)

- `GET /settings?domain=BUSINESS` includes `generalCurrencyCode`, `generalCurrencySymbol`, `generalCurrencyNameEn`, `generalCurrencyNameAr`, `generalCurrencyPosition`. Product price/discount placeholders and amount labels must use these — do not hardcode "Saudi Riyal" / SAR. Default for new installs is PLN. [common.md](common.md#currency)

### Customer cart: free delivery only when it is really free

- `POST /cart` no longer returns `shipping: 0` just because the fee could not be priced (missing store fee / zone). It falls back to `minimumDeliveryPrice`. Free delivery is only when the store fee is `0` or the cart reaches `businessFreeDeliveryOver`. Response includes `freeDelivery`. Show the free-delivery banner only when that flag is true. [Cart](customer-app.md#4-cart)

### Customer checkout: card payment verification

- `POST /order/{id}/payment` compares Moyasar’s minor-unit amount to the order’s due total (after wallet), not a rounded whole-currency value — fractional totals no longer false-fail. Already-paid orders succeed idempotently. Charge exactly `data.price` from `POST /order`. [Customer place order](customer-app.md#card-payment-paymentmethod-visa)

### Driver edit profile: always creates a company/admin review request

- `PATCH /delivery` no longer applies name/phone/docs when the body also includes `readyToReceiveOrders`. Profile/document fields (and uploads) always become a `POST /delivery/profile-edit-request`-style review (`PENDING_COMPANY` for company drivers). Only the availability flag is written immediately. The company gets an in-app notification for new requests. Prefer `POST /delivery/profile-edit-request` for edits. [Section 4](driver-app.md#4-edit-profile-sent-for-review)

### Driver / restaurant login: wrong email no longer shows the phone-format error

- `POST /authentication/login`: a value with `@` sent as `phone` is treated as `email`. Invalid email/phone identifiers return `Enter a valid email or phone number` — not `email must be an email` and not `enter valid phone like this +999 999999999`. Still decide email vs phone on the device when you can. [Driver login](driver-app.md#2-login)

## 2026-11-04

Consolidated week of 2026-10-29 → 11-04. Full per-app action list: [update-2026-11-04.md](update-2026-11-04.md).

### Every app: pl/uk text is now really translated

- Many list/detail responses were returning English for `pl`/`uk` because the translations column was not read. It now is, so `name`/`description` come back in the requested language across stores, menu (products, categories, brands, units), order details, banners, reels, rewards, referral, reviews, zones and plans. No code change if you already send `Locale` and read `name`/`description` — but **re-test every pl/uk screen**. For `pl`/`uk` only, a raw `translations` object is left on the entity; ignore it. [common.md](common.md#requests)

### Every app: list responses include `createdAt` / `updatedAt` again

- A soft-delete fix: list (`findMany`) endpoints used to drop all `*At` timestamps, so `createdAt` was missing. Now only `deletedAt` is hidden. You can show dates in list views.

### Every app: multipart with several file fields no longer drops files

- When a request sent several named file parts and some were empty, provided files could be silently dropped. Fixed — all provided files are saved, empty fields skipped. Remove any "one file at a time" workaround; confirm your field names match the server's.

### Driver & Restaurant: resend-OTP now has a 60s cooldown

- New `POST /delivery/resend/:id` (driver) and `POST /store/resend/:id` (store), body `{ phone }`. Too-soon resends return `400` `OTP_RESEND_WAIT` ("Please wait {seconds} seconds…"); already-verified returns `ALREADY_VERIFIED`; success `OTP_RESENT`. Disable the button for 60s and show a countdown. Customer OTP is unchanged. [driver register](driver-app.md#1-register) · [store verify](store-registration.md#4-verify-the-phone)

### Customer app: `stock` now on every product object

- Sold-out items (`stock: 0`) were already hidden from the menu; now `stock` is also returned on **list** items, not just detail (`null` = unlimited). Read it in lists to disable Add. [Menu](customer-app.md#menu)

### Restaurant app: store name is separate from company name (NIP no longer renames the store)

- `POST /store` / `PATCH /store`: new `storeName` (2–100) is the merchant's display name. A resolved Polish `nip` no longer overwrites the name — the registry name comes back in new `companyName`, with server-set `companyId` linking stores that share a NIP. The store display name is now **editable** on `PATCH /store` (`type` and owner address stay locked). [Store registration](store-registration.md#3-poland-nip-and-company-lookup)

### Restaurant app: add-bank success message is now a key

- `POST /store-bank` returns `message: "bank_created_successfully"` (a raw key, not localized text). Don't show it — rely on `201` and your own copy. Vendor request body is unchanged (omit `storeId`). [Store profile](restaurant-app.md#3-store-profile-and-delivery-source)

### Restaurant app: branch without a manager login

- `POST /branch`: the `vendor` block is now optional. Omit it to create a branch managed under the main-store owner. [Store profile](restaurant-app.md#3-store-profile-and-delivery-source)

### Restaurant app: send `translations` on catalog create/edit

- `product`, `addon`, `unit`, `brand`, `category`, `plan`, `zone`, `city`, `country`, `bank` create/update accept an optional `translations` object `{ pl: { name, description }, uk: {…} }`. The server keeps any language you fill and auto-fills the blanks; fill all four on the client.

### Restaurant app: localized store-flow errors; `idNumber` any national ID

- `POINT_OR_ZONE_REQUIRED`, `LAT_LNG_REQUIRED`, `VENDOR_REQUIRED`, `PAYMENT_FAILED` now come translated on `POST /store`, `GET /store`, `POST /store/:id/payment` — show the server message. `vendor.idNumber` accepts any national ID / passport up to 50 chars. [Store registration](store-registration.md)

### Driver app: broader order search; vehicle-edit conflict fixed

- The orders `name` search now matches order id, customer/driver/store/product fields, address, note, and status/payment words (e.g. `on the way`, `cash`). `PATCH /vehicle/:id` no longer throws a false "name already exists" on partial or unchanged updates. [My orders](driver-app.md#7-my-orders)

### Not a mobile app: driver-company fleet portal

- The new `driver-company` module (role `DRIVER_COMPANY`) is a **web portal** (Next.js, cookie auth), not a mobile app. Nothing for the mobile team to build now. [details](update-2026-11-04.md#not-a-mobile-app-the-driver-company-fleet-portal)

## 2026-11-03

### Customer app: out-of-stock products hidden from menu (b053)

- `GET /category/subCategory`, `GET /product`, and `GET /product/recommended` no longer return products with `stock: 0`. Untracked products (`stock: null`) stay listed.
- List/detail payloads include `stock`. Do not show a full product card with Add for sold-out items — they are omitted from the menu. [Customer menu](customer-app.md#menu)

### Restaurant app: owner / branch-manager ID is not Saudi-only (b063)

- `vendor.idNumber` on `POST /store` and `POST /branch` (and vendor create) accepts any non-empty string up to 50 characters. The API does **not** require a Saudi national ID / Iqama (`Must start with 1 or 2`, or `^[1-3]\d{9}$`).
- Remove client-side rules that reject IDs unless they start with `1` or `2`. Polish PESEL, passport numbers, and other national IDs are valid. [Store registration](store-registration.md#2-register)

### Restaurant app: register uploads + map pin (b060 / b061)

- **Documents (b060):** send `commercialRegistryOrSelfEmploymentDocument` and `commercialRegistryOrSelfEmploymentCertificate` as **multipart file parts** with those exact field names (same request as `logo` / `cover`). Document = image; certificate = image or PDF. Do not send paths or base64 strings in the body. If a field is missing the API creates the store without that file. [Store registration](store-registration.md#2-register)
- **Map (b061):** every pin change must send a fresh `point` JSON string `{"lat":…,"lng":…}` on `POST /store` / `POST /branch`. The API does not cache a previous map pick. Re-selecting another place must overwrite `point` before submit. [Store registration](store-registration.md#2-register)

### Restaurant app: zone picker must use city `id` (b059)

- `GET /zone?cityId={id}` never returns "You should select city first" / "city must be selected first". That text is app-side only.
- After the user picks a city from `GET /city`, keep that row's numeric `id` and pass it as `cityId` when loading zones. Do not send the city name, an empty `cityId`, or open the zone sheet while the selected city id is still null.
- If the city is selected and `GET /zone?cityId=` returns `data: []`, show "Not available in this city yet" — not "select city first". [Store registration §1](store-registration.md#1-pickers)

### Customer app: account created only after OTP login

- `POST /authentication/requestLoginOTP` no longer creates a `User`/`Customer`. It only stores the OTP for that phone.
- `POST /authentication/login` with a valid OTP creates the customer on first success, then returns the token. Numbers that never complete OTP do not appear in the admin customers list. [Customer section 1](customer-app.md#1-login-with-phone)

### Restaurant app: branch without mandatory login data

- `POST /branch`: `vendor` is optional. Omit it to create a branch managed by the main store owner. Send `vendor` only when the branch needs its own manager login. [Store registration](store-registration.md)

## 2026-10-28

### Restaurant app: store registration, what to do

Full description: [Store registration](store-registration.md). In short:

- **Form layout.** Country and module first, then the NIP and its fetch button (Poland only), then city and zone, then the rest. Put a label above every input (`*` for required). Details and the full field order: [Store registration](store-registration.md#screen-layout).
- **Poland needs a NIP.** A store whose zone is in Poland (country `phoneCode` `48`) must send `nip` on `POST /store`. Older app builds cannot send it, so they can no longer register a store in Poland. Elsewhere nothing changes.
- **One name, three address fields.** Send `nameDefault`, `street`, `buildingNumber`, `postalCode` (not `nameAr`/`nameEn`/`address`). The old fields still work outside Poland.
- **City picker must search and page.** Poland has about 1,020 cities now (it had 4). Use `GET /city?countryId=&name=&limit=&page=`. Most new cities have no zones yet, so `zoneId` (required) cannot be chosen there: show "not available yet".
- **The registry decides.** On `POST /store`, when the registry knows the NIP, its record replaces the `name`, `street`, `buildingNumber`, `postalCode` and `type` the app sent, and is saved with the store; the zone must be in the company's city. Show those fields read-only after a successful lookup, and let the user type them when the lookup finds nothing. On `PATCH /store` a store with a registry record cannot change its name, type or (main store) address.
- **Company lookup** `GET /company/lookup?nip=` now also returns `phone`, `email`, `website`, `legalForm`, `startedOn`, and `cityId` and `suggestedType` to pre-select the city and store type.
- **Messages in four languages.** Error and success messages exist in `en`, `ar`, `pl` and `uk` (before, `pl` and `uk` got English). Send the `Locale` header.
- **Data fix.** Riyadh and Dubai were filed under Poland; they are now under Saudi Arabia and the UAE. `GET /city?countryId=1` no longer lists them.

## 2026-10-26

### Restaurant app: store registration form

- **One name:** `POST /store` and `PATCH /store` accept `nameDefault` (no language) and store it as both `nameAr` and `nameEn`. `nameAr` and `nameEn` still work; `POST /store` with none of the three returns `400`. [Store registration](store-registration.md)
- **Split address:** new optional `street`, `buildingNumber` and `postalCode`. When they are sent without `address`, the API builds `address` from them plus the city of `zoneId`. `address` is no longer required if `street` is sent. `GET /store/{id}` returns the three new fields.
- **NIP:** new `nip` on `POST /store` and `PATCH /store`, required when the store's zone is in Poland, validated with the NIP check digit, and locked once set (a later change returns `400`). `GET /store/{id}` returns it. New `GET /company/lookup?nip=` pre-fills the name, address, city (`cityId`) and store type (`suggestedType`) from the Polish registry. `GET /store/{id}` also returns `companyRegistry`, the registry record saved with the NIP, including everything GUS returned (`registry`). The lookup also returns `phone`, `email`, `website`, `legalForm` and `startedOn` when the registry has them. [Store registration](store-registration.md)
- **Phone:** the store `phone` must be unique across stores. A second registration with the same phone returns `409`. It may still equal `vendor.phone`; show a warning, not an error.

## 2026-10-15

### Restaurant app: delivery source required when marking ready

- `PATCH /order/{id}` with `{ "status": "WAITING_DELIVERY_ACCEPTANCE" }` on a home-delivery order now needs `deliverySource` (`PLATFORM` or `STORE_FLEET`) in the same body. Without it the API returns `400` "Choose platform drivers or the store fleet before marking the order ready for a driver". Before, the order went to drivers with the restaurant's default source without the restaurant choosing. Pre-select the order's current `deliverySource`. [Restaurant section 2](restaurant-app.md#2-home-delivery-orders)

### Customer app: discount type on products

- `GET /product` (including `?isOffer=true`), `GET /product/{id}` and `GET /product/recommended` now return `discount` and `discountType` (`PERCENTAGE`, `AMOUNT` or `NONE`) on every product. Before, these endpoints returned only `price`, `totalPrice` and `isOffer`, so the app could not show "-20%" or "-12". Products in `SubProduct` already had both fields. [Customer section 3](customer-app.md#product-fields)

### Customer app: `isFavorite` on stores

- Every store now has `isFavorite: true | false`: `GET /store` (all filters), `GET /store/nearest` and `GET /store/{id}`. Before, the app had to check `FavoriteStore` was not empty. `FavoriteStore` is still returned. [Customer section 2](customer-app.md#favourite-stores)
- `GET /store/{id}/favourite` now returns `data: { "isFavorite": true | false }`, the state after the toggle. Before, it returned only the message, so the app could not tell an add from a remove.

### Driver app: profile edit review

- A company driver's edit now applies as soon as the company approves it: `PENDING_COMPANY` goes straight to `APPROVED`. Before, it went to `PENDING_ADMIN` and waited for admin too. Platform drivers are unchanged: admin reviews them. [Section 4](driver-app.md#4-edit-profile-sent-for-review)

### Reply: favourite stores

Confirmations for the heart icon request:

- **Shape:** `FavoriteStore` array on every store. No `isFavorite`. One entry when the signed-in customer has the store as a favourite, `[]` otherwise. [Customer section 2](customer-app.md#favourite-stores)
- **Endpoints:** `GET /store` (all filters, search and offers), `GET /store/nearest` and `GET /store/{id}`.
- **Toggle:** `GET /store/{id}/favourite`, not `POST /favorite`. The next request reflects it; no cache.

Behaviour changes:

- `GET /store/nearest` now returns `FavoriteStore`. Before, it had no favourite field.
- Guests now get `FavoriteStore: []`. Before, the field was missing on guest requests.
- The toggle on a main store `id` now saves the favourite on its default branch, the store `GET /store/{id}` returns. Before, the heart showed empty on the store screen after favouriting a main store.

## 2026-10-14

### Reply: tiers, bookings, documents, pushes

No new screen. Confirmations for the remaining FLD questions:

- **Tiers:** the driver app only displays `DriverTier` from `GET /user/profile`. It is not given tier names or the rating each tier needs; admin can change both. `DriverTier: null` hides the badge. [Section 3](driver-app.md#tier-and-rating-read-only)
- **Order priority:** no tier delay. Eligible drivers see the order at once. The push goes to the 20 nearest, then highest rating. [Section 6](driver-app.md#6-available-orders)
- **Reviews:** the three criteria are integers 1–5. A second review of the same order returns `409` `You Reviewed this before`. [Section 6](customer-app.md#6-rate-the-driver)
- **Bookings:** store status changes are unchanged. Cancel hours and the fee come from the API; the app does not hardcode them. `storeFeeAmount` is display only. No booking push. No card charge and no refund; `feePaid` is true only when the fee is 0. [Restaurant section 4](restaurant-app.md#4-table-bookings), [customer section 7](customer-app.md#7-table-booking)
- **Documents:** one `accountNotice.reason`, `DOCUMENTS_EXPIRED`. The notice clears after the renewal is approved, not when the photos are uploaded. [Section 9](driver-app.md#9-expired-documents)
- **Pushes:** FCM is title and body only. Do not read an event key from `data`. [common.md](common.md#pushes)
- **Location socket:** production `wss://api-back.deliverus.pl:1234/location`, dev `ws://<server>:1234/location`. [Section 5](driver-app.md#sharing-the-location)
- **Vendor store:** `GET /store/{id}` already includes `lat` and `lng`. [Restaurant section 4](restaurant-app.md#settings)

### Driver app

New work:

- **Share the location** over the `/location` socket at least every 2 minutes while available. Without it the driver gets no orders. [Section 5](driver-app.md#5-availability-and-location)
- **Expired documents:** the suspended driver still logs in. Login and `GET /user/profile` return `accountNotice` (`action: "UPDATE_DOCUMENTS"`, `message`, `expiredDocuments`): open the profile with the note and let the driver send the renewal. Any `401` after login logs out. [Section 2](driver-app.md#2-login), [section 9](driver-app.md#9-expired-documents)
- **Profile** shows tier, rating and the assigned company vehicle, read-only. [Section 3](driver-app.md#3-profile)
- **Orders tab** sends the four in-progress statuses. [Section 7](driver-app.md#7-my-orders)
- **Available list** shows the distance from `Store.lat` / `Store.lng`. [Section 6](driver-app.md#6-available-orders)
- **Background location:** keep sending the location with the app in the background (Android foreground service, iOS background location). [Section 5](driver-app.md#5-availability-and-location)
- **New push `ORDER.DELIVERY.AVAILABLE`** when an order near the driver is ready. On tap, open the available list. [Section 6](driver-app.md#new-order-alert)
- **Wallet card:** a negative `currentBalance` (normal after cash orders) shows as "You owe the platform" with the positive amount, and withdraw is hidden. [Section 8](driver-app.md#8-wallet)
- **Automatic assignment:** after 3 minutes without an accept, the API assigns a driver. Handle the `ORDER.DELIVERY.ASSIGN` push by reloading the Orders tab. [Section 7](driver-app.md#automatic-assignment)

Behaviour changes:

- Profile edit works for platform drivers too. Their first status is `PENDING_ADMIN`. [Section 4](driver-app.md#4-edit-profile-sent-for-review)
- `PATCH /user/profile` and `PATCH /delivery` no longer change a driver's profile. They create a review request. `PATCH /delivery` is only for `readyToReceiveOrders`. [Section 4](driver-app.md#4-edit-profile-sent-for-review), [section 5](driver-app.md#5-availability-and-location)
- Available orders are limited to the driver's kind (platform or company) and zone, nearest first. A company driver no longer sees orders of restaurants without a company. [Section 6](driver-app.md#6-available-orders)
- Accepting an order can return nine new errors, including `This order was already assigned to another driver`. [Section 6](driver-app.md#accept-or-reject)
- The `/location` socket only takes locations from driver accounts and no longer sends driver locations to the apps.
- The available list shows an order only once the restaurant marked it ready for a driver, and is empty while the "available" switch is off or the driver has an order in progress. Accepting with the switch off returns `This driver is not available to receive orders`. [Section 6](driver-app.md#6-available-orders)
- History returns only this driver's orders.
- **Register screen:** remove the nationality dropdown (`GET /nationality` no longer exists, `nationalityId` is ignored) and add an optional passport photo (`passportImage`). [Section 1](driver-app.md#1-register)

### Customer app

- The cart lists `addons` and `variationOptions` per line. [Section 4](customer-app.md#4-cart)
- Product details: `allergens`, `calories`, `color`, `size`, `type`. [Section 3](customer-app.md#product-fields)
- Hide the Featured tab when it is empty (optional). [Section 3](customer-app.md#menu)
- Driver rating on three criteria. [Section 6](customer-app.md#6-rate-the-driver)
- Table booking fee and cancellation deadline. The cancel error is now translated. [Section 7](customer-app.md#7-table-booking)
- **Driver tracking:** the `/location` socket no longer sends driver locations to the customer app. Reload `GET /order?id=` and read `DeliveryMan.lat` / `lng`. [Section 5](customer-app.md#track-the-driver)
- **Pickup in the car** (`CAR_DELIVERY`) is now documented: saved cars, order with `carDeliveryId`, and the "I've arrived" button. Fixed in the API: the order now keeps the chosen car, only the customer's own cars can be used, edited or deleted, and "arrived" works only on an open car order. [Section 5](customer-app.md#pickup-in-the-car)
- Fixed in the API, no app change: store filters `isOffer=true` and `freeDelivery=true`.

### Restaurant app

- **Choose who delivers when marking the order ready:** send `deliverySource` together with `status: "WAITING_DELIVERY_ACCEPTANCE"`. Drivers see the order and get a push from that moment; `auto-assign` is now optional. [Section 2](restaurant-app.md#2-home-delivery-orders)
- A card order that is not paid yet does not reach drivers; assigning it returns `This order is paid by card and the payment is not complete yet`. [Section 2](restaurant-app.md#2-home-delivery-orders)
- New: table bookings list, status buttons and booking settings. [Section 4](restaurant-app.md#4-table-bookings)
- Auto-assign picks the nearest driver, then the highest rated. New error: `No available driver in the store's zone right now`. [Section 2](restaurant-app.md#2-home-delivery-orders)
- `STORE_FLEET` needs an active fleet company, for auto-assign and for saving the profile. Do not send `fleetCompanyId`. [Section 3](restaurant-app.md#3-store-profile-and-delivery-source)
- The order now has `Store.FleetCompany` (`name`, `status`, `deletedAt`). Disable "Store fleet" unless it is `ACTIVE`. [Section 2](restaurant-app.md#2-home-delivery-orders)
- Marking an order ready now alerts nearby drivers. If none accepts within 3 minutes, the API assigns one. Reload the order on the `ORDER.UPDATE` push. A late assign returns `This order was already assigned to another driver`. [Section 2](restaurant-app.md#when-no-driver-accepts)
- **Car pickup orders:** the order now has `Car` (the customer's car details). Show it, reload on the `CUSTOMER.ARRIVE` push, and enable "Delivered" only after `customerArrived`. [Section 6](restaurant-app.md#6-car-pickup-orders)

## 2026-10-13 and before

Already sent. Now merged into the app files:

- Delivery fee from the API (customer, [section 4](customer-app.md#4-cart))
- Driver registration and phone verification (driver, [section 1](driver-app.md#1-register))
- Country code picker and phone format ([common.md](common.md#phone-format))
- Store categories and menu (customer, [sections 2–3](customer-app.md#2-stores-and-categories))
- Reserve button from `reservationsEnabled` (customer, [section 7](customer-app.md#7-table-booking))
- Auto-assign a driver (restaurant, [section 2](restaurant-app.md#2-home-delivery-orders))
- Driver login and profile edit requests (driver, [sections 2 and 4](driver-app.md#2-login))
- Home delivery availability by address (customer, [section 3](customer-app.md#3-store-screen))
- Image compression ([common.md](common.md#images))
