Warehouse service: reservations, supervisor panel and merchant stock

Purpose#

The warehouse service is optional: the platform runs warehouses where merchants store goods. The super admin reserves pallets for a merchant for a monthly wallet fee, a warehouse supervisor records goods in and out with parcels, and the merchant follows the stock.

Who can use it#

• The super admin manages everything from "Warehouse service" in the menu.
• A warehouse supervisor account (user type 7) sees only the panel («لوحة المستودع», Arabic in the English interface too) of its own warehouse; anyone else gets a 403 page.
• A platform merchant sees the "Warehouses" page when the service is enabled for them or they hold an active reservation. Delivery-company merchants never see it.

The service is off by default until the super admin turns it on. For a merchant it is enabled when it is on, the merchant is in the chosen scope and their plan has the warehouses feature, unless the super admin enabled it manually for them. The plan feature is checked only when merchant plans are active, and a plan whose features were never configured allows it.

Set up the service (super admin)#

1. Turn the service on

   Open "Warehouse service", tick "Enable warehouse service", choose "Which merchants can see it" (all except those it is disabled for, or only those you enable it for) and save; "Enable per merchant" adds exceptions by merchant number, mobile or shop name.

2. Add a warehouse

   Use "New warehouse": name (required), governorate, address, phone, opening hours, map location, "Cost per parcel" and extra terms shown to merchants. The cost is for information only; the system does not charge it. To take storage, tick «يقبل تخزين للتجار (حجز طبليات)» and enter the capacity in pallets (at least 1, never below what is reserved).

3. Reserve pallets for a merchant

   From the warehouse's «إدارة» button choose a platform merchant, enter pallets, the monthly fee and a note, then «حجز»; a request beyond the remaining capacity is refused. A new reservation adds a pickup place «مستودع: …» for the merchant and charges the first month at once if the balance allows; an existing active reservation there is edited instead. «إنهاء» disables the pickup place; older parcels stay linked.

4. Create the supervisor account

   On the same page enter the supervisor's name, mobile, optional email and a password (at least 8 characters). The supervisor signs in with mobile or email from the usual sign-in page and lands on the warehouse panel. Removing the supervisor deactivates the account.

12345

1. Choose the pickup place
2. Choose the delivery company
3. Enter the recipient's name and phone
4. Set the cash-on-delivery amount
5. Your invoice number, to recognise the parcel later

The monthly fee from the wallet#

The instalment moves from the merchant's platform shipping balance (the recharge wallet) to platform revenue once a month from the reservation date, through the daily warehouses:charge command (03:10), which runs only while the server's scheduler cron is active. If the balance is too low the reservation is flagged «ما انخصم — رصيده ما كفى» ("not charged") for the super admin and «ما انخصمت الأجرة — اشحن رصيدك وبتنخصم تلقائياً» for the merchant; with the scheduler running it retries daily until the merchant tops up. The reservation is never cancelled automatically.

The supervisor panel#

1. Open the panel

   After signing in, the supervisor lands on the warehouse panel with four tabs: «طرود طالعة» (parcels going out), «إدخال بضاعة» (goods in), «المخزون» (stock, searchable by merchant, product or SKU) and "Transactions" (last 100 movements).

2. Record goods coming in

   In «إدخال بضاعة» pick the merchant (with an active reservation in your warehouse) and enter products with name and quantity (SKU optional), pallets and a note. With a SKU the quantity is added to the product that has that SKU; without one, to a product with the same name that has no SKU; otherwise a new product is created.

3. Hand over a parcel with its goods

   «طرود طالعة» lists parcels whose pickup place is your warehouse and that have not left yet (up to 300). Open «تطليع البضاعة وتسليم الطرد», check the quantities pre-filled from the merchant's request and press «سلّمته للمندوب»: the quantities are deducted from the merchant's stock and an out movement is logged. The parcel's own status does not change.

What the merchant sees and does#

• The "Warehouses" page shows reserved space, fee, next instalment date, stock, recent movements and the available warehouses.
• When you create a parcel in the merchant panel or through the API with the pickup place «مستودع: …», you must select products and quantities from your stock; orders imported from connected stores may omit them (matched by SKU when sent). The quantity is reserved for that parcel: available = on hand − reserved for waiting parcels.
• API: GET /api/v1/warehouse/stock with the merchant's key returns, per active reservation, warehouse_id, pickup_location_id, pallets and items (item_id, sku, name, qty, reserved, available). To create a parcel send pickup_location_id and warehouse_items. Platform merchants only (company merchants get HTTP 403); with merchant plans active the plan needs the api feature.

Common mistakes#

• "Warehouse service is not enabled for your account": the service is off, the merchant is outside the scope, or the plan lacks the warehouses feature.

Limits and permissions#

• A reservation works even while the general service is off, and its holder still sees their space and stock; the stock API route checks neither the general switch nor the warehouses feature.
• The monthly fee is a ledger entry between the merchant's wallet and platform revenue; no real money moves.
• Most panel and reservation labels appear in Arabic in the English interface.