YellowBIRD's Logistics API: The Technical Stack Powering Real-Time Last-Mile Delivery in Uganda

When most people think about delivery logistics, they think about riders, routes, and parcels. Engineers think about something different: the data architecture that makes a rider appear at the right location at the right time, with the right information, without a single manual instruction being issued. This is the engineering story behind YellowBIRD's logistics API — how it was designed, what it does at a technical level, and why its architecture matters for the future of delivery infrastructure across Uganda and East Africa.

YellowBIRD's Logistics API: The Technical Stack Powering Real-Time Last-Mile Delivery in Uganda

Dev.to · Logistics Engineering · API Design · Real-Time Systems · African Tech

When most people think about delivery logistics, they think about riders, routes, and parcels. Engineers think about something different: the data architecture that makes a rider appear at the right location at the right time, with the right information, without a single manual instruction being issued. This is the engineering story behind YellowBIRD's logistics API — how it was designed, what it does at a technical level, and why its architecture matters for the future of delivery infrastructure across Uganda and East Africa.

The Engineering Problem: Coordinating a Real-Time Physical Network Through Software

Last-mile delivery is one of the more technically interesting logistics problems you can work on, because it sits at the intersection of two fundamentally different domains: the deterministic world of software systems and the non-deterministic world of physical geography.

In software, you can define exact states and transitions. An order is placed. It is assigned. It is in transit. It is delivered. These are clean, enumerable states with clear triggers. In the physical world, none of this is clean. A rider gets stuck in Kampala traffic on Jinja Road. A customer gives an address in a neighbourhood where buildings have no numbers. A merchant is not ready when the rider arrives. The real world does not follow a state machine.

The engineering challenge YellowBIRD's logistics API had to solve was bridging these two domains — creating a system that is precise enough to coordinate a high-volume, real-time delivery operation, and flexible enough to handle the inherent unpredictability of physical logistics in an urban African market. That is a genuinely hard problem. And the architecture of the API reflects the specific choices made to solve it.

The Core Architecture: Event-Driven, Real-Time, Bidirectional

YellowBIRD's logistics API is built on an event-driven architecture. This is the foundational design decision that shapes everything else about how the system behaves.

In an event-driven system, every meaningful state change in the delivery chain — order received, zone identified, rider assigned, pickup confirmed, delivery confirmed — is treated as a discrete event that triggers downstream processing automatically. Rather than a request-response model where the commerce platform asks "what is the status of this order?" and waits for an answer, the YellowBIRD API pushes status events to all registered endpoints the moment they occur.

This event-driven design has significant implications for the real-time performance of the system. When a rider confirms pickup at a merchant on the rider mobile application, that confirmation is not stored and retrieved on the next polling cycle. It triggers an event that is immediately propagated — to the operations dashboard, to the merchant's order management interface, to the customer's tracking endpoint, and to the analytics layer — simultaneously, in real time, without any polling overhead.

For a system processing thousands of order events per day across a city-wide rider network, the difference between a polling architecture and an event-driven one is not cosmetic. It is the difference between a system that feels live and a system that always feels slightly behind. In last-mile delivery, slightly behind is operationally significant. An operations manager who sees order status with a thirty-second lag is making decisions on stale data. A customer whose tracking interface updates in real time versus one that updates every five minutes has a completely different experience of the same delivery.

Order Ingestion: The Inbound API Layer

The first layer of the YellowBIRD API handles order ingestion — receiving structured order data from integrated partner platforms and passing it into the Logistics Management System for processing.

When a commerce platform like MoMo Market sends an order to YellowBIRD, it makes a POST request to the order ingestion endpoint, carrying a JSON payload that contains the full order data. The payload schema is standardised across all integrations — every partner platform maps its internal order data structure to YellowBIRD's defined schema before sending. This standardisation is critical: a logistics API that accepts differently structured data from each integration partner creates a maintenance burden that compounds with every new partner added.

A typical order payload carries the following data fields: a unique order reference identifier generated by the partner platform, the customer's full name and contact number, the delivery address as a street-level string, the delivery location as a coordinate pair for zone mapping, the merchant identifier referencing the pickup location in YellowBIRD's merchant registry, the line items being delivered with quantities, the order total and payment confirmation status, and a webhook URL for the partner platform to receive delivery status callbacks.

The ingestion endpoint performs synchronous validation on receipt — checking that all required fields are present, that the merchant identifier resolves to a known pickup location, that the coordinate pair falls within a serviced delivery zone, and that the authentication token is valid. A successful validation returns a 201 response carrying YellowBIRD's internal order identifier, which the partner platform stores for subsequent status lookups and reconciliation. A failed validation returns a structured error response with field-level detail — not a generic 400 — so that partner platform developers can identify and resolve data issues without ambiguity.

Zone Resolution: Translating a Physical Address Into a Logistics Decision

Once an order clears ingestion validation, the first significant processing step is zone resolution — the process of mapping the customer's delivery location to a specific delivery zone in YellowBIRD's operational geography.

This is where the logistics domain logic sits closest to the engineering implementation, and it is worth understanding in some detail because zone resolution is the decision that determines which rider pool is eligible for the assignment, which directly determines dispatch speed and delivery success probability.

YellowBIRD's zone resolution system takes the coordinate pair from the order payload and runs a point-in-polygon check against the zone boundary definitions stored in the system's geography layer. Kampala's delivery geography is defined as a set of non-overlapping polygons, each representing a delivery zone with its own identifier, associated rider pool, capacity parameters, and operational status. The point-in-polygon check determines which polygon contains the customer's coordinates — and therefore which zone owns the delivery.

This coordinate-based approach is specifically important for Uganda's urban geography, where street addresses are frequently informal, incomplete, or non-unique. A system that relies solely on street address parsing to determine delivery zone will fail frequently in a market where the same street name may appear in multiple areas, where many residential locations have no formal address at all, and where "behind the big tree near the school" is a legitimate delivery instruction. By anchoring zone resolution to coordinates rather than address strings, YellowBIRD's API makes the zone decision on the most reliable data point available — the customer's physical location — rather than the most ambiguous one.

For orders where coordinates are not available or fall outside defined zone boundaries, the system falls back to a string-matching algorithm that attempts to resolve the address to a zone through a combination of landmark matching, area name recognition, and historical delivery pattern data. Orders that cannot be resolved to a zone through either method are flagged for manual review on the operations dashboard rather than failing silently.

Rider Assignment: The Allocation Logic

With the delivery zone determined, the system moves to rider assignment — selecting the specific rider from the zone's allocated pool to whom the order will be dispatched.

The rider assignment logic runs against a real-time rider state index that tracks every active rider in the network: their current zone assignment, their availability status, the number of active deliveries currently in their queue, their real-time location, and their historical performance metrics. Assignment decisions are made against this index on every order, meaning the allocation logic always operates on current state rather than a cached or delayed view of rider availability.

The assignment algorithm weights multiple factors simultaneously. Geographic proximity between the rider's current position and the merchant pickup location is the primary factor — minimising the distance the rider must travel before beginning the delivery directly reduces dispatch-to-pickup time. Queue depth is the secondary factor — riders who already have multiple active deliveries in their queue receive new assignments with lower priority than riders with lighter loads. Performance metrics inform a tertiary weight — riders with consistently higher delivery success rates and customer feedback scores are preferred for assignments when primary and secondary factors are otherwise equal.

The output of the assignment algorithm is a single rider identifier. The system writes the assignment to the order record, updates the rider's state in the rider index to reflect the new active assignment, and triggers the job dispatch event that pushes the complete job brief to the rider's mobile application.

The Rider Mobile Application Interface: Pushing Jobs in Real Time

The rider mobile application is the consumer of the rider-facing layer of YellowBIRD's logistics API — the interface through which assignment events, job details, and navigation data are delivered to riders in the field.

When an assignment event is triggered, the API pushes a push notification to the assigned rider's device through the mobile notification service. The notification carries the order identifier and a summary of the job. The rider opens the application, which makes an authenticated GET request to the job detail endpoint carrying the order identifier. The job detail response includes the complete merchant pickup information, the customer delivery address and coordinates, the order line items, the customer contact number for delivery coordination, and the order reference for confirmation at both pickup and delivery.

The rider application maintains a persistent connection to the YellowBIRD real-time event stream for status event propagation. When the rider takes a status action in the application — confirming pickup, marking in transit, confirming delivery — the application makes a PATCH request to the order status endpoint with the new status and a timestamp. The API validates the status transition against the order's current state, writes the update to the order record, and emits the status change event to all registered listeners — the operations dashboard, the partner platform's webhook, and the customer tracking endpoint — simultaneously.

Webhooks: Closing the Loop With Partner Platforms

The outbound layer of YellowBIRD's API is webhook-based. When a partner platform integrates with YellowBIRD, it registers a webhook URL as part of the integration configuration. This URL is the endpoint to which YellowBIRD's API sends delivery status events throughout the lifecycle of every order.

The webhook payload structure is consistent across all event types, with an event type field identifying the specific status change and an order data object carrying the full current state of the order. Event types cover the full delivery lifecycle: ORDER_RECEIVED, RIDER_ASSIGNED, PICKUP_CONFIRMED, IN_TRANSIT, DELIVERY_CONFIRMED, and DELIVERY_FAILED, with the last event type carrying a failure reason code and a re-attempt flag where applicable.

Webhook delivery operates on an at-least-once guarantee with exponential backoff retry logic. If the partner platform's webhook endpoint returns anything other than a 2xx response, the API schedules a retry after an initial delay, doubling the delay on each subsequent failure up to a defined maximum retry count. This ensures that transient network issues or temporary partner platform unavailability do not result in lost status events, which would leave the partner platform's order records in a stale state.

Partner platforms that need to query order status outside the webhook flow — for reconciliation, customer service lookup, or historical reporting — can use the order status GET endpoint, which returns the current state and full event history of any order within the retention window.

The Analytics Layer: Every Delivery as a Data Event

Every status event that flows through YellowBIRD's logistics API is simultaneously written to the analytics data store — a separate persistence layer from the operational order store, optimised for aggregation and reporting queries rather than transactional operations.

This separation is architecturally important. The operational order store is optimised for low-latency reads and writes on individual order records — the access pattern of the real-time delivery operation. The analytics store is optimised for aggregate queries across large datasets — the access pattern of performance reporting and operational intelligence. Running both access patterns against the same data store would compromise the performance characteristics of both.

The analytics layer powers the reporting dashboards that give YellowBIRD's operations team and its merchant partners visibility into delivery performance over time. Metrics computed from the event stream include average dispatch-to-pickup time, average pickup-to-delivery time, delivery success rate by zone and by rider, customer feedback score distribution, order volume by time of day and day of week, zone capacity utilisation, and failed delivery reason code frequency.

These metrics are not computed on-demand from raw event data. They are maintained as pre-aggregated views that are updated incrementally as new events are written, meaning dashboard queries return results immediately rather than requiring expensive real-time computation across the full event history.

Authentication and Security

Every integration with YellowBIRD's logistics API is authenticated through API keys issued at the partner platform level. Keys are scoped to specific permissions — a partner platform's inbound integration key has permission to POST to the order ingestion endpoint and GET from the order status endpoint, but not to access rider management, zone configuration, or any other operational endpoints. This principle of least privilege limits the blast radius of a compromised key to the specific operations that key is authorised for.

All API traffic is transmitted over TLS. Order payloads, which contain customer personal data including name, contact number, and delivery address, are treated as sensitive data throughout their lifecycle — stored encrypted at rest in the operational data store and excluded from log output at the middleware layer to prevent accidental exposure in application logs.

Webhook deliveries carry an HMAC signature in the request header, generated using a shared secret established at integration time. Partner platforms are expected to validate this signature on receipt of every webhook delivery, rejecting payloads with invalid or missing signatures. This prevents third parties from injecting fraudulent delivery status events into partner platform order records by sending requests directly to registered webhook endpoints.

What This Architecture Enables — And Why It Matters for African Tech

The technical architecture described above is not unique to last-mile delivery. Event-driven systems, webhook-based outbound APIs, coordinate-based zone resolution, and real-time allocation algorithms are patterns used across logistics, ride-hailing, food delivery, and asset tracking systems globally. What is specific to YellowBIRD's implementation is how these patterns are applied to the operational realities of Uganda's market — the address informality, the zone-based delivery geography, the multi-merchant platform structure, and the connectivity constraints that affect both riders in the field and customers receiving deliveries.

Building production logistics technology for a market like Uganda requires making architectural decisions that global logistics API templates do not anticipate. Falling back gracefully when coordinates are unavailable. Handling the operational complexity of multi-merchant orders within a single delivery zone. Designing webhook retry logic that accounts for the connectivity inconsistencies that affect partner platform servers in emerging market infrastructure. These are engineering decisions that are invisible in the final product but that determine whether the system actually works in practice.

YellowBIRD's logistics API works in practice. It processes thousands of orders daily across Kampala's delivery zones, maintains real-time rider state across an active field network, and pushes status events to partner platforms with the reliability that production commerce operations require. The architecture is the reason it works — and the architecture is designed to scale beyond Uganda's current market as YellowBIRD's operations expand across East Africa.

For Developers: What Integration Looks Like

If you are building on a commerce platform that operates in Uganda and you are evaluating logistics integrations, the YellowBIRD API integration path is straightforward from a technical standpoint. The core implementation on the partner platform side involves three components: an outbound order POST to the ingestion endpoint triggered on order confirmation, a webhook receiver endpoint to accept delivery status events, and a signature validation implementation for webhook security.

The integration does not require your platform to implement any routing logic, zone mapping, rider management, or delivery tracking. All of that lives in YellowBIRD's system. Your platform sends an order, receives status events, and surfaces delivery information to your merchants and customers through whatever interface your product provides. The logistics complexity is abstracted entirely behind the API.

The data mapping work — translating your platform's order data structure to YellowBIRD's defined payload schema — is the primary implementation effort. YellowBIRD provides a sandbox environment for integration testing, with test merchant identifiers and simulated rider state transitions so that partner developers can validate the full event flow before going live.

The Bigger Picture: API as Infrastructure

There is a tendency in the technology industry to think about APIs as product features — capabilities that a platform exposes to developers who want to build on top of it. YellowBIRD's logistics API is better understood as infrastructure — a shared technical resource that multiple commerce platforms depend on to fulfil a core operational function.

Infrastructure APIs are different from product feature APIs in a few important ways. They need to be more reliable, because the businesses depending on them have no fallback. They need to be more carefully versioned, because breaking changes affect production operations across multiple partner platforms simultaneously. They need to be more thoroughly documented, because the integration effort required from partner developers is a direct cost of the infrastructure's adoption. And they need to be designed for the long term — not for the current set of integrations, but for the ecosystem of integrations that the market will eventually require.

YellowBIRD's logistics API is being built to that standard. Because in Uganda's rapidly digitalising commerce ecosystem, the API that connects commerce platforms to logistics infrastructure is not a nice-to-have developer tool. It is the technical foundation on which the country's digital commerce runs. Getting the architecture right is not a product decision. It is an infrastructure decision. And infrastructure, once embedded at the ecosystem level, defines the terms of the market for years.

YellowBIRD Logistics — API-First. Event-Driven. Built for East Africa.
www.yellowbird.mobi