The integration between a POS or order management system and a dispatch platform seems like a plumbing problem. In theory: order confirmed in POS, event fires, dispatch system receives it, sequencing begins. In practice, the integration layer is where most of the dispatch quality problems we diagnose at stores turn out to originate. Stale order status, delayed event delivery, missing delivery zone information, inconsistent order IDs across systems: these are the failure modes that turn a functional dispatch system into a source of confusion for counter staff.
This post is a walkthrough of the technical decisions that matter most when connecting a POS or order management system to PickNGo (or any dispatch platform). It's aimed at store IT leads or developers handling the integration, not operations staff.
Event Architecture: Webhook vs. Polling
The first decision is how the POS communicates order status changes to the dispatch system. There are two basic patterns: webhook-based (the POS pushes events to the dispatch platform on each status change) and polling-based (the dispatch platform periodically queries the POS for updated order states).
Webhook-based integration is almost always preferable for pickup dispatch. Dispatch sequencing needs to respond to order status changes within seconds for accurate courier assignment. A polling interval of even 30 seconds introduces a meaningful lag: an order that goes to "bag ready" at 12:15:10 may not appear as ready in the dispatch queue until 12:15:40, which is 30 seconds of avoidable lag on every order during peak hours.
The case for polling is simpler implementation on the POS side, particularly for older POS systems that don't natively support outbound webhooks. If your POS cannot emit webhooks, you can build a thin middleware layer that polls the POS API and translates updates to webhook events before forwarding to the dispatch system. This adapter pattern adds one component to maintain but preserves the latency characteristics of the webhook approach end-to-end.
The Status Transition Map
Most POS systems use their own status vocabulary. "Confirmed," "in preparation," "ready for collection," "handed over," and "complete" are common states, but the exact names and transition rules vary across POS vendors. Before connecting the two systems, you need to produce an explicit status transition map: a table that shows which POS status corresponds to which dispatch status, and which POS status transitions are meaningful events for dispatch sequencing.
The states that matter most for dispatch are:
- Order created: the event that adds the order to the dispatch queue for sequencing. Must fire reliably or orders are never sequenced.
- Bag ready: the event that makes an order eligible for courier assignment. If this fires late (or not at all), premature courier assignments occur.
- Courier departed: the event that closes the order in the dispatch queue. If this is delayed or missing, the dispatch queue becomes stale with orders that have already left.
Events that are less critical for sequencing but useful for analytics and exception detection: order modified (SKU substitution or quantity change), order cancelled, and pick confirmation (when the picker confirms they've started assembling the order).
Order ID Consistency
A subtle but frequent problem in POS-dispatch integrations is order ID inconsistency. The POS generates an internal order ID (often a sequential integer or UUID). The order management system may assign a separate customer-facing order number. The courier platform may use yet another reference. When a counter staff member needs to look up an order across two systems to resolve a dispute, they may be working with three different identifiers for the same order.
The integration layer should normalize this at ingestion. The dispatch system should store all known identifiers for each order: the POS internal ID, the customer-facing order number, and any platform reference IDs for couriers who've been assigned. When a courier arrives citing their platform reference, counter staff should be able to pull up the full order with one query regardless of which identifier they use.
This sounds like a detail, but the cost of getting it wrong compounds during peak windows. At 12:45 pm with 8 orders pending, a staff member who spends 90 seconds trying to match a courier's platform reference to an order in the dispatch queue is experiencing a system design failure, not an operations failure.
Delivery Zone Data
The dispatch sequencing algorithm uses delivery zone as one of the primary inputs to courier assignment scoring. If the POS doesn't pass delivery zone information in the order creation event, the dispatch system has to derive it from the delivery address. Derivation from address requires geocoding, which adds 200 to 500 ms latency and introduces a failure mode if the geocoding service is unavailable.
The cleaner architecture is to have the POS (or the order management system upstream of the POS) assign the delivery zone at order creation time and include it as a field in the event payload. Zone assignment rules (which postcodes or barrios belong to which zone) should be maintained in one place and referenced by both systems. If zone definitions change (a new delivery contract covering a previously excluded area, for example), the change propagates automatically without requiring re-integration work.
Minimum Required Fields: Order Creation Event
| Field | Type | Purpose |
|---|---|---|
| order_id | string | Primary key for cross-system lookup |
| customer_reference | string | Displayed to couriers for verification |
| delivery_zone | string | Zone-A / Zone-B: direct courier scoring input |
| sla_minutes | integer | Time-urgency factor for priority scoring |
| pickup_type | enum | curbside / counter / locker: routing logic |
| created_at | ISO 8601 ts | SLA deadline calculation base |
Handling POS Downtime
Every integration needs a defined behavior for POS unavailability. When the POS is offline (planned maintenance, connectivity outage, system crash during peak), the dispatch system needs a fallback path. Two options are common: graceful degradation to manual entry, where counter staff enter orders directly into the dispatch system using a simplified input form; or queue buffering, where the integration layer queues events during outage and replays them when connectivity restores.
Queue buffering works well for short outages (under 10 minutes). For longer outages, buffered events replaying in bulk can cause temporary queue depth spikes that overwhelm the dispatch system. The practical approach is buffering with a maximum replay window (10 to 15 minutes) and a fallback to manual entry for longer outages.
This is worth designing and testing before production deployment, not after. POS outages during peak windows are uncommon but not rare, and the first time staff encounter them without a documented fallback procedure is always the worst time to improvise one.