App Fixes — Change Log

Author: Josh S. Sakweli, Backend Lead Team Last Updated: 2026-10-25 Version: v1.0 Backend version / branch: 1.2.4 · fet/location_service (+ notification server fet/location_service, File Thunder fet/shipping) Deployed to: not yet — staging first Compared with: the staging branch as deployed (448f06a0, 2026-10-06) — "Before" means what the app sees on staging today

Base URL: https://api.nexgate.co/api/v1 (staging: https://dev.api.nexgate.co/api/v1)

Short Description: Shops now have a real place on the map, buyers keep an address book, and every shop in a checkout is either pickup at the shop or delivery by a shipper with a real price. This changes existing shop, product, cart, checkout and order endpoints — the old fake shipping fields (shippingAddressId, shippingMethodId, trackingNumber, carrier) are gone. The release also carries app fixes: digital downloads, chat avatars, profile cover, donation target, the sign-in alert. Android, iOS and web must update before this goes to production; the admin dashboard has a few changes.

Audience: mobile team · web team · admin dashboard

Related docs — the new endpoints are not repeated here, they live in their own docs:

• docs/location/location_api_doc.md — pin → area, area lists, shop location, my addresses, recent pins
• docs/shipping/shipping_api_doc.md — delivery options, cart delivery, every pickup / delivery order action, shippers, admin
• docs/shipping/campaigns/campaigns_api_doc.md — delivery discounts run by shops, shippers and NexGate
• notifications_inapp_bell_api_doc.md — the bell list, targetType / targetId

Also new since staging, each with its own doc (already shared, not repeated here):

• event_group_tickets_api_doc.md — event tickets "buy together": groupBuying on tickets, group on POST /e-events/checkout, ticket groups (open, by code, mine, transfer, withdraw), 4 notifications
• product_group_purchase_api_doc.md — product group buys: whole-payment transfer, withdraw, orders always created, true savings, 15-minute expiry

This log covers what changed in endpoints, fields, rules and notifications that already existed, plus the few new endpoints that sit inside an existing service and have no other doc.

How to read this

Change types

HTTP methods

• GET - GET
• POST - POST
• PUT - PUT
• PATCH - PATCH
• DELETE - DELETE

Rules this log follows

• Grouped by service. Inside a service: what changed, the flow (when the order of steps changed), the endpoint table, then one block per endpoint.
• Every changed endpoint shows Before and After for the request and the response — only the parts that changed.
• Samples are short: the changed fields and one or two around them.
• Coded refusals are HTTP 409 with data.code (and now, sometimes, data.details). New codes are listed per endpoint and again in the index (§16).

0. At a glance

0.1 Breaking changes — do these first

0.2 Removed

1. Shops

What changed in this service: a shop's place is no longer typed text (city, region, landmark). It is a pin on the map, turned by the backend into ward / district / region, set with the shop location endpoint (location doc). Every shop response now carries that location, and an availability block (open now, paused, taking orders). Paused shops stay visible. Shop reviews finally show the owner's reply.

1.0 Flow — before and after

Before

flowchart LR
    A[Create shop<br/>type city, region, street, landmark, lat/lng] --> B[Shop live]

After

flowchart LR
    A[Create shop<br/>no location fields] --> B[Shop location step<br/>drop a pin: PUT /shops/id/location] --> C[Shop can sell physical items]
    A -. no location yet .-> D[Physical items refused at checkout:<br/>SHOP_LOCATION_REQUIRED]

What the user notices: the seller drops a pin instead of typing an address; buyers see "Kariakoo, Ilala, Dar es Salaam" with a Directions and a Call button; shops show "Open now · closes 18:00" or "Paused until …".

1.1 Endpoints in this service

New, documented elsewhere: shop location PUT/GET /e-commerce/shops/{shopId}/location → location doc §6–§7.

1.2 BREAKING Create / update shop — location fields removed

Endpoint: POST {base_url}/e-commerce/shops · PUT {base_url}/e-commerce/shops/{shopId}

In one line: the shop's place is no longer part of create / update; set it with the shop location step.

Request

{
  "shopName": "Mama Yoyo Shop",
  "phoneNumber": "+255744742944",
  "city": "Dar es Salaam",
  "region": "Dar es Salaam",
  "landmark": "Opposite the clock tower"
}

{
  "shopName": "Mama Yoyo Shop",
  "phoneNumber": "+255744742944"
}

App to do

• Remove city / region / street / landmark / lat / lng inputs from the shop form.
• After create, open the Shop location step (PUT …/location, location doc §6); editing uses the same screen.

1.3 BREAKING Shop responses — location, hasLocation, availability

Endpoint: every shop response — GET /e-commerce/shops/{shopId}, /{shopId}/detailed, /shops/all, /featured, /my-shops (and paged / category forms), create / update / approve.

Response

{
  "shopName": "Mama Yoyo Shop",
  "city": "Dar es Salaam",
  "region": "Dar es Salaam",
  "landmark": "Opposite the clock tower",
  "latitude": -6.819, "longitude": 39.2768
}

{
  "shopName": "Mama Yoyo Shop",
  "hasLocation": true,
  "location": { "lat": -6.819, "lng": 39.2768,
    "areaLabel": "Kariakoo, Ilala, Dar es Salaam",
    "landmark": "Opposite the clock tower",
    "phone": "+255744742944", "…": "…" },
  "availability": { "status": "ACTIVE", "acceptingOrders": true,
    "paused": false, "pauseMode": null, "pausedUntil": null, "pauseReason": null,
    "hours": { "hasHours": true, "openNow": true,
               "closesAt": "2026-10-25T18:00:00+03:00", "nextOpensAt": null } }
}

Behaviour

• availability.acceptingOrders is false when the shop is paused with STOP_ORDERS, suspended or closed → Buy is off.
• pauseMode: KEEP_SELLING (shows "paused" but orders still come in, accepted later) or STOP_ORDERS.
• hours.openNow is null when the shop has set no hours. All times are East Africa Time with the offset.
• Paused shops stay visible. Product pages, product and shop search, subscribe, profile shop counts, linking a shop to an event and shop tags on posts / clips now accept a paused (TEMPORARILY_OFFLINE) shop — before, its products 404'd.

App to do

• Show area / map / Directions (lat,lng → Google / Apple Maps) / Call (phone) from location.
• Owner: when hasLocation is false show "Add your shop location to start receiving orders".
• Shop page: "Open now · closes 18:00" / "Opens Mon 08:00" / "Paused until …"; Buy off when acceptingOrders is false.

1.4 BREAKING Shop search and global search

Endpoint: GET {base_url}/e-commerce/shops/search · GET {base_url}/e-commerce/search?query=…

Reference: §7, §8

1.5 CHANGED Shop reviews — the owner's reply is returned

Endpoint: shop review list, /paged, /my-review, create / update responses.

In one line: the reply the owner saved with POST /shops/reviews/{shopId}/{reviewId}/reply was never returned; now it is.

FIX: the shop's average, rating count and the 5★…1★ breakdown (/summary, and the rating on shop responses) counted every review whatever its status; now only ACTIVE reviews count, so a hidden review leaves the stars at once.

App to do

• Show the shop's reply under a review when replyText is set.

1.6 NEW Shop opening hours

Purpose: the hours that drive availability.hours ("Open now · closes 18:00"), the seller's 24-opening-hour accept window and the buyer's pickup times.

Endpoint: PUT {base_url}/e-commerce/shops/{shopId}/hours · GET {base_url}/e-commerce/shops/{shopId}/hours

Access Level: 🔒 PUT: shop owner, or a super / staff admin · GET: any logged-in user

Authentication: Bearer token

Request JSON Sample (PUT — send the whole week every time; it replaces what was there):

{
  "weekly": [
    { "day": "MONDAY", "open": "08:00", "close": "18:00" },
    { "day": "SATURDAY", "open": "09:00", "close": "13:00" },
    { "day": "SATURDAY", "open": "14:00", "close": "17:00" }
  ],
  "specialDays": [
    { "date": "2026-12-25", "closed": true, "ranges": [], "note": "Christmas" },
    { "date": "2026-12-31", "closed": false, "ranges": [ { "open": "08:00", "close": "12:00" } ] }
  ]
}

Request Body Parameters:

Success Response JSON Sample (PUT and GET):

{ "success": true, "httpStatus": "OK", "message": "Opening hours saved",
  "data": { "weekly": [ { "day": "MONDAY", "open": "08:00:00", "close": "18:00:00" } ],
            "specialDays": [ { "date": "2026-12-25", "closed": true, "ranges": [], "note": "Christmas" } ],
            "sameDayCutoff": null, "timeZone": "Africa/Dar_es_Salaam", "updatedAt": "2026-10-25T10:12:00" } }

Success Response Fields:

Errors:

Rules: a shop with no hours counts as always open (availability.hours.hasHours: false, openNow: null). The status on shop responses updates at once after a save.

App to do:

• Seller: "Opening hours" screen (a row per day, add a second range, special days) → PUT the whole thing.

1.7 NEW Pause / reopen the shop

Purpose: the seller takes a break — with or without still taking orders.

Endpoint: PUT {base_url}/e-commerce/shops/{shopId}/pause · DELETE {base_url}/e-commerce/shops/{shopId}/pause

Access Level: 🔒 shop owner, or a super / staff admin

Authentication: Bearer token

Request JSON Sample (PUT):

{ "mode": "STOP_ORDERS", "until": "2026-10-28T09:00:00+03:00", "reason": "Stock taking" }

Request Body Parameters:

Success Response JSON Sample (PUT "Shop paused", DELETE "Shop reopened") — the availability block (§1.3):

{ "success": true, "httpStatus": "OK", "message": "Shop paused",
  "data": { "status": "TEMPORARILY_OFFLINE", "acceptingOrders": false, "paused": true,
            "pauseMode": "STOP_ORDERS", "pausedUntil": "2026-10-28T09:00:00+03:00", "pauseReason": "Stock taking",
            "hours": { "hasHours": true, "openNow": true, "closesAt": "2026-10-25T18:00:00+03:00", "nextOpensAt": null } } }

Errors:

Rules:

• Pausing a paused shop replaces its mode / until / reason. DELETE on a shop that is not paused changes nothing and returns its availability.
• A paused shop stays visible everywhere (§1.3).
• KEEP_SELLING: orders are not auto-cancelled while paused; their 24-opening-hour accept deadline restarts when the pause ends.

App to do:

• Seller: "Pause shop" sheet (stop orders / keep selling, optional until, optional reason) and a "Reopen" button.
• Buyer: "Paused until …" on the shop page from availability.

2. Products

What changed in this service: product responses carry the shop's location (for "Pickup at …" and Directions), a new bulky flag tells shippers a parcel is big or heavy, and a refused save no longer half-saves.

2.1 Endpoints in this service

2.2 CHANGED Product responses — shop location

Same location object as the shop's, or null when the shop has none. Reference: §9

"shopLocation": { "lat": -6.7889, "lng": 39.2083, "areaLabel": "Ubungo, Ubungo, Dar es Salaam", "phone": "+255700111222", "…": "…" }

App to do

• Product page: "Pickup at Ubungo, Ubungo" + Directions; optionally disable Buy for a physical product when shopLocation is null.

2.3 CHANGED Products — bulky

Shippers that do not carry bulky parcels are left out of its delivery options. The backend also ticks it by itself after two different shippers report the product too big. Reference: §19, §45

App to do

• Seller product form: "Bulky / heavy item" switch.

2.4 FIX Refused product saves / used installment plans

Reference: §27, §71

3. Cart

What changed in this service: the cart now knows about delivery. It keeps one delivery address and, per shop with physical items, pickup or delivery with a held price. Each item has a tick: checkout buys only ticked items. Adding, changing or removing items answers with what that did to delivery.

3.0 Flow — before and after

Before

flowchart LR
    A[Add to cart] --> B[Cart: items only] --> C[Checkout: pick address + DHL placeholder] --> D[Pay the whole cart]

After

flowchart LR
    A[Add to cart<br/>+ pickup / delivery for that shop] --> B[Cart: one address,<br/>a choice per shop, held prices, ticks]
    B --> C[Checkout: takes the cart's choices,<br/>ticked items only] --> D[Pay: items + delivery]
    D --> E[Bought items leave the cart;<br/>unticked ones stay]

What the user notices: the cart is grouped by shop, each shop shows "Pickup at the shop" or "Delivery by Dar Cargo · TZS 3,500 · Tue–Wed", the total includes delivery, and a change of address re-prices every shop and says what changed.

3.1 Endpoints in this service

New, documented elsewhere: PUT /e-commerce/cart/destination, POST /e-commerce/cart/destination/change-back, PUT /e-commerce/cart/shops/{shopId}/fulfillment → shipping doc §B.

3.2 CHANGED Add to cart / change / remove an item

Endpoint: POST {base_url}/e-commerce/cart/add · PUT {base_url}/e-commerce/cart/items/{itemId} · DELETE {base_url}/e-commerce/cart/items/{itemId}

In one line: the product sheet can send the shop's pickup / delivery choice, and every cart change says what it did to delivery.

Request (add only)

{
  "productId": "5f0e…",
  "quantity": 2
}

{
  "productId": "5f0e…",
  "quantity": 2,
  "fulfillment": { "type": "DELIVERY", "quotationId": "3c1f…", "optionId": "o-1" },
  "dropoff": { "addressId": "9b1d…" }
}

Response (add, change, remove)

{ "success": true,
  "message": "Product added to cart successfully",
  "data": null }

{ "success": true,
  "message": "Product added to cart successfully",
  "data": { "deliveryBefore": 10500, "deliveryAfter": 13000,
            "switchedToPickup": 1, "canChangeBack": false,
            "message": "Delivery 10,500 → 13,000, 1 shop switched to pickup",
            "changes": [ { "shopId": "cfb6…", "shopName": "My Shop",
                           "before": { "type": "DELIVERY", "businessName": "Dar Cargo", "total": 3500 },
                           "after":  { "type": "PICKUP", "businessName": null, "total": 0 },
                           "message": "…" } ] } }

Behaviour

• A sheet quotation that no longer fits (other items, other address, expired) is not an error: the item is added and the shop falls back to the cart rules.
• FIX: two add-to-cart taps at the same moment for a new product used to fail one of them; now both succeed.

App to do

• Send fulfillment (and dropoff when changed) from the product sheet.
• Show data.message after add / change / remove.

3.3 CHANGED Get the cart

Endpoint: GET {base_url}/e-commerce/cart

Response

shops[]:

{ "shopId": "cfb6…", "shopName": "My Shop", "itemIds": ["…"],
  "type": "DELIVERY", "chosenBy": "BUYER",
  "quotationId": "3c1f…",
  "selected": { "optionId": "o-1", "businessId": "c4bc…", "name": "Dar Cargo", "logoUrl": "…",
                "reason": "BUYER_CHOICE", "cost": { "total": 7000 }, "eta": { "…": "…" },
                "offer": { "listPrice": 7000, "price": 7000, "buyerPays": 3500, "shares": [ … ] } },
  "pricesHeldUntil": "2026-10-25T14:30:00+03:00",
  "notice": { "code": "NO_ADDRESS", "message": "Add a delivery address to see delivery prices" },
  "nudge": { "campaignId": "…", "funder": "SELLER", "kind": "FREE", "value": null, "addMore": 4995.05,
             "message": "Add 4,995 more from My Shop for free delivery" } }

Behaviour

• Reading the cart refreshes expired or outdated quotations.
• No address → pickup + "Add a delivery address…"; an address nobody covers → pickup + "Delivery is not available to X yet".
• A pickup the buyer chose never changes by itself; a pickup set by default turns into delivery once a shipper covers.
• chosenBy: "BUYER" ↔ selected.reason: "BUYER_CHOICE" now always agree. A shipper picked on an earlier cart shows with the option label USED_BEFORE (not selected). (§49)
• selected.offer (delivery campaigns, campaigns doc): show buyerPays, not cost.total. deliveryTotal and the change messages count what the buyer pays.
• nudge appears only while a campaign's minimum order is not reached; it follows the ticked items.
• New items come in ticked; adding more of an unticked item ticks it again.
• DELETE /cart/clear keeps destination.
• FIX: after a paid cart checkout the bought quantities now leave the cart (before: nothing was removed). Units added after the checkout stay; unticked items stay.

App to do

• Group the cart by shops; show each shop's choice, notice, nudge, and "Used before" for USED_BEFORE.
• A checkbox per item, per shop and "select all" (§3.4); the pay button shows cartSummary.selectedTotal.
• After a cart payment, re-read the cart instead of clearing it locally.

3.4 NEW Tick / untick cart items

Purpose: choose which cart items the next checkout buys.

Endpoint: PUT {base_url}/e-commerce/cart/selection

Access Level: 🔒 Protected (cart owner)

Authentication: Bearer token

Request JSON Sample:

{ "itemIds": ["a1b2…", "c3d4…"], "selected": false }

Request Body Parameters:

Success Response: the same body as GET /e-commerce/cart (§3.3).

Errors: unknown item → 404 "Cart item not found".

Rules: cart checkout (REGULAR_CART) takes ticked items only; nothing ticked → "Tick at least one item to check out." A shop with nothing ticked leaves shops and keeps its pickup / delivery choice for when it is ticked again. Reference: §48

App to do:

• Checkbox per item, per shop, "select all" → one call each.

4. Checkout & payment

What changed in this service: every shop with physical items in a checkout is PICKUP or DELIVERY. The fake address and DHL method are gone; fulfillment replaces them. Delivery has a real price from a real shipper, held from the quotation; if the price ran out and changed, checkout refuses instead of charging a new price silently. Group purchases and "ships now" installments can now be delivered. The payment response finally separates the seller's money from delivery.

4.0 Flow — before and after

Before

flowchart LR
    A[Create session<br/>shippingAddressId + shippingMethodId: fake] --> B[Shipping = 0] --> C[Pay: one amount]

After

flowchart LR
    A[Create session<br/>fulfillment: per shop PICKUP / DELIVERY<br/>+ dropoff + chosen option] --> B{Held price still valid?}
    B -- yes --> C[Pay: items part + delivery part per shop]
    B -- changed / gone / campaign ended --> D[409 with before → after<br/>re-quote, PATCH, pay]
    D --> C

What the user notices: the buyer picks pickup or delivery per shop, an address, who receives, a note; the total includes delivery; if a price moved they see "was X, now Y" and confirm.

4.1 Endpoints in this service

4.2 BREAKING Create / update a checkout session — fulfillment

Endpoint: POST {base_url}/e-commerce/checkout-sessions · PATCH {base_url}/e-commerce/checkout-sessions/{id}

In one line: tell the backend, per shop, pickup or delivery — and where, who receives, and which shipper option.

Request

{
  "sessionType": "REGULAR_DIRECTLY",
  "items": [ { "productId": "5f0e…", "quantity": 1 } ],
  "shippingAddressId": "1111…",
  "shippingMethodId": "2222…"
}

{
  "sessionType": "REGULAR_DIRECTLY",
  "items": [ { "productId": "5f0e…", "quantity": 1 } ],
  "fulfillment": {
    "byShop": { "cfb6…": "DELIVERY" },
    "deliveries": { "cfb6…": { "quotationId": "3c1f…", "optionId": "o-1" } },
    "dropoff": { "addressId": "9b1d…", "directions": "Blue gate" },
    "receiver": { "name": "Mama Json", "phone": "0712345678" },
    "note": "Call when you arrive"
  }
}

Behaviour

• Digital-only checkouts need no fulfillment.
• Cart checkout (REGULAR_CART) may send no fulfillment: pickup / delivery, the address and the held shipper come from the cart. Sending fulfillment.dropoff overrides the cart's address. Only ticked items are bought.
• Group purchase accepts DELIVERY (same shape). The group's member totals count items + tax only; each member's delivery is on their own session / order. (§55)
• Installment: a plan that ships after the down payment (IMMEDIATE) accepts DELIVERY — pricing = down payment + the whole delivery. A layaway plan (AFTER_PAYMENT) refuses delivery at checkout: LAYAWAY_DELIVERY_LATER. (§56)
• A new pin becomes a recent place (and a saved / recent one is marked used) only after payment; saveAs saves the address at once.
• The fulfillment is frozen when the session is created — later edits to the shop location or the address never change it.

Errors

App to do

• Per shop "Pickup at shop / Delivery"; when any delivery: saved address / recent / new pin (+ "Save as"), receiver "Me / Someone else", optional note.
• Send fulfillment (with deliveries from the sheet / cart); for cart checkout it can be left out.
• Stop sending shippingAddressId / shippingMethodId.
• On DELIVERY_PRICE_CHANGED / DELIVERY_OPTION_GONE: show before → after, get a fresh quotation (sheet: ask again; cart: re-read the cart), retry.

4.3 BREAKING Checkout session response — fulfillment and real delivery prices

Endpoint: the checkout session (create, get, patch).

Response

The fulfillment object (same on the session, the order and the installment agreement):

{ "type": "DELIVERY",
  "pickup":  { "source": "SHOP_LOCATION", "label": "Yoyo Test Shop", "lat": -6.7889, "lng": 39.2083,
               "areaLabel": "Ubungo, Ubungo, Dar es Salaam", "phone": "+255700111222", "…": "…" },
  "dropoff": { "source": "SAVED_ADDRESS", "label": "Home", "lat": -6.77, "lng": 39.25,
               "areaLabel": "Mikocheni, Kinondoni, Dar es Salaam", "directions": "Blue gate", "…": "…" },
  "receiver": { "name": "Mama Json", "phone": "+255712345678" },
  "note": "Call when you arrive",
  "delivery": { "quotationId": "3c1f…", "optionId": "o-1", "businessId": "c4bc…", "businessName": "Dar Cargo",
                "total": 7000, "minMinutes": 120, "maxMinutes": 240, "arrivalFrom": "…", "arrivalTo": "…",
                "pricesHeldUntil": "…", "route": null,
                "offer": { "listPrice": 7000, "price": 7000, "buyerPays": 3500, "shares": [ … ] } } }

• dropoff and delivery are absent for PICKUP. delivery.total is what the shipper is paid; offer shows who paid the rest (campaigns). route is set for station routes (shipping doc §1.8).

4.4 CHANGED Process / retry payment

Endpoint: POST {base_url}/e-commerce/checkout-sessions/{id}/process-payment · /retry-payment

Response

{ "escrowId": "e1…",
  "amountPaid": 16000.99,
  "sellerAmount": 16000.99 }

{ "escrowId": "e1…",
  "amountPaid": 16000.99,
  "sellerAmount": 1000.99,
  "deliveryAmount": 15000,
  "parts": [ { "part": "ITEMS", "amount": 1000.99, "orderId": "…", "…": "…" },
             { "part": "LEG",   "amount": 15000,   "orderId": "…", "…": "…" } ] }

Behaviour

• The money is held per shop in parts: ITEMS (the seller; platform fee on items + tax only) and LEG (the shipper, one per leg). A free delivery has no LEG part.
• Buyer transaction history for a split payment reads "N parts" instead of "N sellers".

Errors

App to do

• Show items from sellerAmount and delivery from deliveryAmount; list each shop's order from parts.
• Handle CAMPAIGN_ENDED like DELIVERY_PRICE_CHANGED (before → after, PATCH, pay).

5. Orders

What changed in this service: every physical order has a fulfillment — pickup or delivery — with its own status ladder, steps and times. Pickup orders and orders a shipper delivers no longer use the old ship / confirm-delivery / regenerate-code endpoints: they use the shipping order actions (shipping doc §C). The delivery code is 4 digits, comes by its own SMS and lasts 24 h. A buyer's cancel follows clearer rules.

5.0 Flow — before and after

Before

flowchart LR
    A[Paid] --> B[Seller: /ship<br/>fake tracking number] --> C[Buyer types 6-digit code:<br/>/confirm-delivery] --> D[Money to seller]

After — pickup

flowchart LR
    A[PLACED] --> B[Seller accepts<br/>ACCEPTED] --> C[Packed & ready<br/>READY + pickup code to buyer] --> D[Seller enters buyer's code<br/>COLLECTED] --> E[Buyer: It's what I ordered<br/>COMPLETED, money released]

After — delivery

flowchart LR
    A[PLACED] --> B[ACCEPTED] --> C[READY<br/>job offer to shipper] --> D[SHIPPER_ACCEPTED] --> E[HEADING_TO_SHOP] --> F[Hand-over at the shop<br/>ON_THE_WAY, code to receiver] --> G[Rider enters code<br/>DELIVERED] --> H[Buyer confirms<br/>COMPLETED: seller + shipper paid]

What the user notices: order screens show where the parcel is, the shipper's name and phone, "Code sent by SMS · valid until …", and buttons that depend on the step (Accept, Ready, Hand over, Collect, "It's what I ordered", Report a problem).

5.1 Endpoints in this service

New, documented elsewhere: every pickup / delivery order action under /shipping/orders/{orderId}/… (accept, ready, pickup-time, code, hand-over, hand-over-rider, collect, confirm, report-problem, delivery-options, switch-to-delivery, change-destination, switch-to-pickup, delivery-decision, cancel) → shipping doc §C.

5.2 BREAKING Order detail and lists — fulfillment

Endpoint: GET {base_url}/e-commerce/orders/{orderId} and the order lists

Response

{ "orderNumber": "ORD-2026-94070",
  "productOrderStatus": "SHIPPED",
  "deliveryAddress": "123 Main Street",
  "trackingNumber": "TRACK-8F2A",
  "carrier": "DHL" }

{ "orderNumber": "ORD-2026-94070",
  "productOrderStatus": "SHIPPED",
  "fulfillment": {
    "type": "DELIVERY", "status": "ON_THE_WAY",
    "parcelNumber": "NX-48213",
    "placedAt": "…", "acceptedAt": "…", "readyAt": "…", "pickedUpAt": "…",
    "code": { "status": "ACTIVE", "expiresAt": "2026-10-26T09:12:00" },
    "shippers": [ { "leg": 1, "name": "Dar Cargo", "phone": "+255745051250" } ],
    "delivery": { "businessName": "Dar Cargo", "total": 7000, "…": "…" },
    "decision": null, "needsShipperSince": null, "…": "…" } }

fulfillment keys added beyond §4.3

Behaviour

• Existing orders were copied over: PENDING_SHIPMENT → PLACED, SHIPPED / DELIVERED / DISPUTED → READY, COMPLETED → COMPLETED, CANCELLED / REFUNDED → CANCELLED.
• Automatic closing: a pickup or delivery order not accepted within 24 opening hours is cancelled; a pickup not collected 14 days after Ready becomes EXPIRED. Both refund in full; the order shows CANCELLED with no cancelledBy.
• shippingFee and totalAmount can change after payment (another shipper at another price; 0 after switching to pickup). shippingFee is what the buyer paid for delivery.
• For now the seller sees the full drop-off (pin, directions, receiver phone).

App to do

• Read fulfillment instead of deliveryAddress / trackingNumber / carrier; pickup orders show the shop's place + Directions.
• Show fulfillment.status and the step times; lists show the fulfillmentType badge and fulfillmentStatus.
• A Call button per entry in shippers; a rider card (photo, plate, Track) for Bolt.

5.3 CHANGED Cancel an order

Endpoint: POST {base_url}/e-commerce/orders/{orderId}/cancel

Old orders without a shipper keep the old rules.

Errors

App to do

• Buyer: show Cancel only while PLACED or while "We're finding a new shipper" / a decision shows; otherwise "Collect it myself instead".
• Seller: hide Cancel on delivery orders from Ready on; send informedBuyer.
• Installment order: the Cancel button calls the agreement cancel (§6.2).

5.4 BREAKING Old ship / confirm-delivery / regenerate-code

Endpoint: POST {base_url}/e-commerce/orders/{orderId}/ship · /confirm-delivery · /regenerate-code

POST /ship no longer takes or returns trackingNumber (it was a fake "TRACK-…").

App to do

• For pickup and shipper orders, stop calling these three; use the buttons from shipping doc §C.

5.5 BREAKING Delivery code — 4 digits, own SMS, 24 h, "I lost my code"

Endpoint: /orders/{orderId}/ship, /confirm-delivery, /regenerate-code (old orders) — and the same code rules for the shipping …/code action.

POST /regenerate-code response — fields added (old ones stay):

{ "orderId": "…",
  "orderNumber": "ORD-2026-94070",
  "codeSent": true,
  "destination": "email",
  "codeExpiresAt": null,
  "maxAttempts": 5 }

{ "orderId": "…",
  "orderNumber": "ORD-2026-94070",
  "codeSent": true,
  "destination": "sms",
  "codeExpiresAt": "2026-10-18T05:03:05",
  "maxAttempts": 5,
  "message": "New code sent by SMS to +255*****2944",
  "code": "4821",
  "sentTo": "+255*****2944" }

code is shown once, on that screen; it is never stored readable, so it cannot be shown again.

Errors

App to do

• 4-digit input; show triesLeft; on CODE_LOCKED / CODE_EXPIRED offer "I lost my code".
• Order screen: "Code sent by SMS to +255•••2944 · valid until …" from fulfillment.code.
• "I lost my code" → show code big, once. Never cache it.

6. Installments

What changed in this service: the agreement carries the fulfillment like an order; "ships now" plans can be delivered; installment orders are cancelled only through their agreement; and two money bugs are fixed.

6.1 CHANGED Agreement — fulfillment, layaway, cancel

Reference: §17, §56, §69

6.2 FIX Installment money

Reference: §56, §57, §70, §71

App to do

• Offer pickup / delivery in the installment sheet for "ships now" plans; layaway: "choose delivery after the last payment".
• Installment order: Cancel = POST /e-commerce/installments/agreements/{agreementId}/cancel.

7. Group purchase

7.1 CHANGED Group checkout with delivery

Reference: §55

App to do

• The group checkout sheet offers pickup / delivery like a direct buy; the group screen keeps showing the group price.

8. Wallet & transactions

8.1 CHANGED Transaction history titles

Known, not changed: a refund also writes "Sale Refund Issued" (debit) into the payee's history although the payee never received that money. Reference: §34, §40, §41

9. Events

What changed in this service: a venue is a pin turned into ward / district / region (like a shop); an in-person event needs that pin to publish. Donation tickets can have a target and show progress.

9.1 CHANGED Venue — area from the pin

Endpoint: PATCH {base_url}/e-events/drafts/{draftId}/location · event responses

"venue": { "name": "Mlimani City Hall", "address": null, "coordinates": { "latitude": -6.77, "longitude": 39.22 },
           "areaLabel": "Mikocheni, Kinondoni, Dar es Salaam", "matchType": "CONTAINED", "ward": { "…": "…" } }

Reference: §78

9.2 BREAKING Publish / reveal location needs a pin

Endpoint: PATCH {base_url}/e-events/{eventId}/publish · {base_url}/e-events/{eventId}/published/reveal-location

TBA and online events unchanged; drafts can still be saved without a pin.

App to do

• Venue step: the same pin screen as the shop location (resolve, show areaLabel, Confirm off when not covered); the address field stays optional ("directions").

9.3 CHANGED Donation target and progress

Endpoint: POST {base_url}/e-events/tickets/{eventId} · PUT {base_url}/e-events/tickets/{ticketId} · PATCH {base_url}/e-events/tickets/{ticketId}/published

Request

Response (ticket details, ticket list, tickets in the event response)

{ "name": "Support the choir",
  "ticketPricingType": "DONATION",
  "price": 0.00 }

{ "name": "Support the choir",
  "ticketPricingType": "DONATION",
  "price": 0.00,
  "donation": { "target": 500000.00,
                "raised": 210000.00,
                "donations": 11 } }

• raised = confirmed donations only (cancelled / refunded bookings do not count). The organiser can set or raise the target after publishing.

Errors

App to do

• Organiser: optional "Target" field on donation tickets.
• Event page: progress bar from donation.raised / donation.target (hide the bar when target is null; still show raised).

10. Profile & account

10.1 CHANGED Profile cover photo

Endpoint: PUT {base_url}/profile/update · GET {base_url}/profile/me, /profile/id/{userId}, /profile/u/{username}

{ "userName": "joshuasakweli",
  "profileMedia": { "fileId": "…", "status": "READY",
                    "variants": { "thumb": "https://…/thumb.webp" } } }

{ "userName": "joshuasakweli",
  "profileMedia": { "fileId": "…", "status": "READY",
                    "variants": { "thumb": "https://…/thumb.webp" } },
  "coverMedia":   { "fileId": "…", "status": "READY",
                    "variants": { "medium": "https://…/medium.webp",
                                  "large": "https://…/large.webp" } } }

Errors: a file uploaded with another context → "File was not uploaded as a cover photo"; someone else's file → 403.

App to do

• Profile banner: upload as COVER_PHOTO, send coverPhotoFileId, show coverMedia.

10.2 CHANGED New-device sign-in alert

AUTH_NEW_DEVICE_LOGIN is now sent by password, SMS-code and Google sign-in (was password only) and never for an account's first device. Its data gains the details the app can show in the bell item:

Browser and system come from the User-Agent header — no new request fields. Email, push and SMS now show them. Reference: §79

11. Interests

11.1 CHANGED Category management is admin only

Picking interests (unchanged, for the onboarding screen): load GET /interests/categories/all, then save at least 3 of those ids with POST /onboarding/secondary/interests { "interestIds": [ … ] }. One unknown or switched-off id → 404 "Some categories are inactive or do not exist" and nothing is saved — always send ids from the list you just loaded. The categories are created by the system at startup. Reference: §79

12. Chat

12.1 FIX Chat avatars and group icons are real links

Endpoint: GET {base_url}/chat/conversations (display.avatar) · group responses (iconMedia: create, get, PUT /chat/groups/{conversationId}/icon)

Applies to groups, people and shops in the chat list. An icon set while its upload was still processing now upgrades to its final images (it stayed stuck before). A failed icon upload now says "Upload failed" instead of "still in progress".

The chat doc said avatar was a plain link string — it is the object { fileId, status, mimeType, variants }. Reference: §80

App to do

• Read the image from display.avatar.variants.thumb / iconMedia.variants.thumb (no prefixing).
• On CHAT_GROUP_UPDATED (§15) refresh the chat list row and the group header.

13. Digital downloads

13.1 FIX Files keep their name and type

Endpoint: GET {base_url}/e-commerce/digital-files/my-downloads/{accessId}/url — then the app downloads the returned url

Response body unchanged (url, expiresInSeconds). Works for files already uploaded. Reference: §80

App to do

• Download the url as bytes and stream it to a file; never read the body as text / string.
• Use the filename from Content-Disposition (or fileName from the order downloads list).

14. Admin dashboard (existing screens)

Reference: §30, §31, §58, §64

New admin endpoints for shipping, Bolt, campaigns, the operations board, reports and the audit log → shipping doc §K and campaigns doc §7–§8.

15. Notifications

New types are listed so the bell list and push taps can handle them; each opens the screen in its targetType / targetId. Four new targets: SHIPPING_JOB, SHIPPER_BUSINESS, SHIPPING_CAMPAIGN, ADMIN_SHIPPING_BOARD — an app that does not know a target yet opens the bell list.

16. Error codes index

All HTTP 409, data.code; some carry data.details.

The codes of the new location, shipping and campaign endpoints are in their docs (location §Part 3, shipping §4.5, campaigns §Part 3).

17. App checklist by screen