Appearance
Cart, discounts, orders and payments
12.1 PUT /api/v1/mobile/syncBag (customer) · PUT /api/v1/mobile/open/syncBag (guest)
Handler: syncBagWithClient (syncBag_controller.js) — one handler, two mounts. This is the cart-pricing call: send the whole bag, get back totals, taxes and applied discounts.
Body payload:
| field | type | req | notes |
|---|---|---|---|
bag | array | ✅ | items: hubProductId ✅ (number), quantity ✅ (number), packageId (string), points_source (bool, default false), isPromotional (bool) |
modification | array | — | items: hubProductId ✅, plus created / updated / deleted (bools), quantity, points_source |
syncBag | boolean | — | persist the cart server-side |
addressId | number | — | for delivery-fee/tax calculation |
points | number | — | ≥0, points to burn |
discounts | string[] | — | discount codes, uppercased |
12.2 DELETE /api/v1/mobile/emptyCart
Auth: Customer · Handler: emptyCart · No params.
12.3 PUT /api/v1/mobile/explicitDiscount
Auth: Customer · Handler: applyExplicitDiscount Body payload: discounts ✅ (string[], uppercased), addressId (number), points (number ≥0).
12.4 POST /api/v1/mobile/open/discount/applicable (guest) · POST /api/v1/mobile/discount/applicable (customer)
Handler: getApplicableDiscounts (discount_controller.js)
Body payload: bag (array of { hubProductId ✅, quantity ✅, packageId, isPromotional, index }, default []), addressId (number). Query: hubId (required unless present on the token — otherwise "Hub is required"), roomId, userId. On the guest variant an empty bag is rejected ("Bag cannot be empty"); for logged-in users an empty bag is allowed.
12.5 GET /api/v1/mobile/discount/reward/:discountId
Auth: Customer · Handler: createPromotionForUser · Path: discountId (number) ✅. Claims a discount as a personal reward. (It's a GET that mutates — intentional in this codebase.)
12.6 GET /api/v1/mobile/discount/reward
Auth: Customer · Handler: getAllUserRewards · Query: includeExpired (boolean, default false).
12.7 POST /api/v1/mobile/create-order — guest order
Auth: Brand · Handler: createGuestOrder (order_controller.js)
Body payload:
| field | type | req | notes |
|---|---|---|---|
customer | object | ✅ | needs one of email / phoneNumber / userId, and exactly one (xor) of userId / name |
bag | array | ✅ | items: hubProductId ✅ (int), quantity ✅, packageId, isPromotional, index |
deliverySchedule, deliveryInstruction, transporterId | string | — | |
posId | enum | — | keys of orderSourceType |
method | enum | — | keys of orderMethod |
discounts | string[] | — | uppercased codes |
customer object: userId, name, password (≥8), dateOfBirth (ISO), email, phoneNumber (≥8) + phone_prefix, address, billingAddress, user_documents. address / billingAddress: { addressId, name, type, address1, county, city, state, short_state, zip, country (ISO), addressString, latLng {lat ✅, lng ✅} } — must contain addressId or address1. user_documents[]: { governmentId ✅, expiration ✅ (date), fileName ✅, type ✅, isValid ✅ (bool) }.
Query: source, medium, device (enums). Order type comes from the token (tenant.type), defaulting to delivery.
12.8 POST /api/v1/mobile/createOrder — customer order
Auth: Customer · Handler: createNewOrder Body payload (all optional; the bag comes from the synced server-side cart): addressId, billingAddressId, governmentId, deliveryCharges, points (≥0) — numbers · deliverySchedule, deliveryInstruction — strings · isPrepaidOrder — boolean · posId / method — enums · discounts — uppercased string[].
12.9 GET /api/v1/mobile/order/:orderId
Auth: Customer · Handler: getOrderByOrderId · Path: orderId (number) ✅ (scoped to the caller).
12.10 GET /api/v1/mobile/orders
Auth: Customer · Handler: getAllOrdersForCustomer · Query: withLineItems (boolean, default false).
12.11 PUT /api/v1/mobile/order/cancel/:orderId
Auth: Customer · Handler: cancelOrder · Path: orderId (number) ✅.
12.12 Payments
Source: payment_controller.js
| Endpoint | Auth | Handler | Params |
|---|---|---|---|
GET /api/v1/mobile/payment/gateways | Brand | getAllPaymentGateway | none — gateways for the token's hub |
POST /api/v1/mobile/payment/link/:paymentGatewayId | Customer | getPaymentLink | path paymentGatewayId (number) ✅; body payload: currency ✅ (string), orderId (number), email (defaults to the token's email) |
GET /api/v1/mobile/payment/gateways/user-info/:paymentGatewayId | Customer | getPGCustomerDetails | path paymentGatewayId (number) ✅ |
POST /api/v1/mobile/payment/gateways/user/confirm | Customer | confirmPGCustomer | body payload: user_pg_id ✅, phone_number ✅, code ✅ (strings), paymentGatewayId ✅ (number) |