Integrating Belpost into a mobile app: where logistics breaks
Integrating Belpost into a mobile app doesn't break at the "get a tracking number" stage, but at the stage when delivery statuses in the app have to live a life of their own.
While orders number in the dozens, everything looks functional: a request goes out, a response comes back, the buyer sees "accepted." The problem shows up later — when parcel tracking becomes a daily operation rather than a demo.
The first typical failure is status desynchronization.
The external service returns events in batches and not always in the order in which they occurred: "delivered" may arrive before "arrived at the branch." If the app simply overwrites the latest status, the buyer sees movement backward, calls support, and the operator manually reconciles the tracking number.
This isn't fixed with a "repeat request" but with event normalization: your own state reference, a priority rule, and idempotent writes, where a repeated event doesn't move the order.
The second failure is stuck tracking numbers. The order has shipped, a number has been assigned, but no events come in for it: the parcel hasn't yet been accepted at the branch, or the number was issued with a delay.
An app that polls the status on every screen open quickly hits rate limits and starts getting rejections.
What works here is background refresh on a schedule with increasing intervals, plus a separate branch for orders with no events longer than expected — they go into a queue for manual review instead of hanging forever in the "in transit" status.
The third failure is drop-offs under peak loads. A mass mailing, a sale, a seasonal spike: the number of simultaneous requests to the logistics service grows severalfold, and without a queue and concurrency limiting, some requests are silently lost.
The user sees an empty screen instead of a status, even though the order is alive. That's why requests to the external service go through a queue with retries and a split into priority (the buyer is waiting on the screen) and background (list refresh) ones.
All three failures share a single root cause: logistics is treated as "just another request" rather than as a stream of events with its own delay, ordering, and failures.
Below we break down how this is closed at the app architecture level and what the customer gets as a result.
What a correct logistics integration into an app delivers
A correct logistics integration is not about "bolting on tracking" but about structuring the exchange of statuses so that data arrives on time, is not duplicated, and does not bring the app down during peak periods.
The effect is measured across three dimensions: the freshness of delivery statuses, the load on support, and the resilience of the app under load.
The freshness of delivery statuses rests on the timely exchange of events: the app receives a change in order state almost immediately after scanning at the sorting center or at the branch, rather than the next time the screen is opened.
The customer sees "arrived at pickup point" when the parcel is actually there — this removes the main cause of frustration and repeated checks.
The load on support drops in direct proportion to how fully the app answers the questions "where is my parcel" and "when can I pick it up." When the status, timeframe, and pickup point address are visible in the order card, and a push arrives at key transitions, the share of "where is my order" inquiries falls severalfold — operators switch to complex cases instead of mass identical requests.
The resilience of the app is ensured by isolating the external delivery service from the main flow: unavailability or a delayed response does not block the catalog, checkout, and payment.
Requests are sent with a time limit, retried according to a clear policy, and the last successful status is cached — the app remains functional even if the logistics service responds slowly.
The speed of tracking updates is a balance between polling frequency and the consumption of battery and data. A sensible scheme: active orders update frequently, delivered ones rarely or on demand, and state transitions are reinforced with a push notification.
This way the customer gets fresh data without unnecessary background activity, and the system gets a predictable load during peak hours.
It is worth checking the integration against a checklist: the status in the app matches the actual one, a push arrives on a state change, the app does not crash when the service is unavailable, support is not drowning in identical inquiries, and tracking updates without manually refreshing the screen.
Ways to Connect Logistics Services: Comparing Approaches
There are three workable ways to receive shipment statuses and pass order data to logistics. The choice between them determines how quickly the customer sees tracking, what happens when an external service is unavailable, and how much manual work remains for your team. Let's break down each option by its conditions of use and limitations.
Direct Integration
The application or your server calls the logistics operator's API directly: creates a shipment, requests statuses, processes returns. It's suitable when the scenario is single and stable, and the shipment volume is predictable.
The limitation is a rigid dependency on the external service's format and limits: changing fields or request frequency breaks the client, and a failure on the operator's side affects the entire user journey.
Intermediate Layer
Your intermediary service sits between the application and logistics: it caches statuses, retries failed requests, and normalizes responses from different operators into a unified format. It's suitable if there are several operators or you plan to add new ones.
The limitation is that it requires separate infrastructure and monitoring: the layer becomes a critical component that must be watched.
Manual Data Export
An employee exports a shipment registry and uploads statuses as a file on a schedule. It's suitable for small volumes and one-off campaigns, when a delay of a few hours is acceptable.
The limitation is that tracking in the application always lags, and growth in the number of orders runs up against manual labor.
| Option | When It's Suitable | Limitations |
|---|---|---|
| Direct integration | One operator, stable scenario, predictable volume | Dependency on the external service's format and limits, operator failure is visible to the customer |
| Intermediate layer | Several operators, need for a unified format and fault tolerance | Requires its own infrastructure, monitoring, and maintenance |
| Manual export | Small volume, one-off campaigns, delay is acceptable | Tracking lags, manual labor grows with the number of orders |
In practice, the choice of connection method is rarely either-or: teams often start with an intermediate layer, while keeping manual export as a backup channel during failures. Describe your scenario — we'll come back with an estimate and a plan.
Stages of integrating Belpost into a mobile application
Integrating a logistics service into an application is not "connecting an API" but embedding delivery into existing ordering scenarios so that statuses, timelines, and addresses do not diverge from reality.
We start with an integration audit: we look at how the application currently stores addresses and the cart, what order states already exist, and where synchronization with the external service will be required. Based on the audit results, it becomes clear what we can reuse and what will have to be rebuilt.
Next, we design the data exchange scheme: which events the application initiates, which come from the service, and how we handle discrepancies and repeated requests.
Separately, we define the behavior when the external side is unavailable — the order must not "hang" in an unknown status.
- Audit of the current architecture: analysis of order models, addresses, user profiles, and the points where logistics is embedded.
- Designing the exchange scheme: events, formats, rules for status synchronization, and error handling.
- Logistics setup: connection to the service, branch directories, calculation of delivery timelines and cost.
- Implementation of user scenarios: choosing the delivery method, entering the address, tracking the shipment.
- Testing delivery scenarios: order, cancellation, address change, service unavailability, resending.
- Verification on real shipments: comparing application statuses with the actual movement of the parcel.
- Handover: exchange documentation, support instructions, and regulations for updating directories.
Testing delivery scenarios is a key stage: this is exactly where discrepancies surface between the service statuses and what the user sees. We run not only the happy path but also cancellations, returns, and address changes after checkout.
After handover, the client's team receives a working integration and a clear regulation for supporting it.
What we hand over to the client after implementation
After implementing the Belpost integration into the mobile app, the client receives not only working functionality, but also a complete set of artifacts that the team can use to maintain and evolve the solution without us. Below is exactly what we hand over and why each document matters in practice.
- Integration documentation — a description of all Belpost workflows: shipment tracking, delivery cost calculation, order placement, status change notifications. It specifies which data is sent to the service, what is returned, and how errors are handled.
- Data flow diagrams — visual maps showing the path of an order from the in-app cart to the Belpost tracking number and back. With these, a new developer understands within a day where to look for the cause of a failure.
- Access policies — separation of rights for API keys, test and production environments, and access to integration logs. We separately record who can change credentials and how.
- Environment configurations — connection parameters for Belpost services for the test and production environments, timeout and retry settings for network failures.
- Support regulations — what to do when the Belpost service is unavailable, how the app degrades, who to escalate an incident to and within what timeframes.
- Update instructions — the procedure for when Belpost changes its API: how to check compatibility, update the configuration, and roll out a new version without downtime.
- Acceptance checklist — a list of checks the client can use to verify that all workflows function: from order placement to receiving a delivery notification.
We walk through each artifact with the client's team during the handover — we don't just hand over a folder of files, we go through the diagrams and regulations together. Describe your task — we'll come back with an estimate and a plan.
Case study: how in-app logistics stopped losing statuses
What it was before
The online store's app displayed order status based on its own database: an operator manually transferred stages from the carrier's dashboard.
At peak — 800-1000 shipments per day — some orders got "stuck" in the "in transit" status even after delivery, and tracking updated with a delay of up to several hours.
Support was receiving around 400 inquiries per week on the "where is my order" topic alone, and up to a third of them were about orders that had already been delivered.
What was changed
Our engineers connected the app to Belpochta logistics services directly: they set up API access, configured background synchronization of statuses by tracking numbers, and mapped external codes to internal order states.
They also added idempotent event processing — a repeated webhook does not create a duplicate status, and any discrepancy between the systems is highlighted in monitoring rather than surfacing to the customer.
What it became
| Metric | Before | After |
|---|---|---|
| Status update delay | up to 3 hours | minutes |
| "Where is my order" inquiries | ~400/week | ~120/week |
| Orders with a "stuck" status | up to 8% | less than 0.5% |
The status in the app now matches the actual delivery stage, and support deals with real issues instead of manually reconciling tracking numbers.
If you have a similar task — logistics integration into a mobile app — describe your scenarios, and we will come back with an estimate and a plan.
How does direct integration differ from an intermediary layer?
Direct integration is when a mobile app calls the logistics service API directly: the client gets the shipment status, places an order, or calculates the delivery cost with a request from the app.
The scheme is simple and fast at the start, but every external call becomes part of the customer journey: if the service responds slowly or changes the response format, users see it immediately, and updating the logic requires a new app release and passing store reviews.
An intermediary layer is a dedicated service between the app and the logistics provider. The app communicates with it through a single stable contract, and it in turn calls the necessary methods, normalizes responses into a unified form, and caches reference data and queues.
Such a layer lets you change the provider or add a second one without rewriting the client, and it takes the work of dealing with third-party formats and timeouts off the app.
The difference shows up during failures. With direct integration, an unavailable external service means a blank screen for the user. With an intermediary layer, requests are buffered, served from cache, and statuses are updated once the provider is available again.
Logging and incident investigation are also simpler: all calls to external systems are visible in one place instead of being scattered across device logs.
The cost of the intermediary layer is an additional component that needs to be deployed, monitored, and updated. For a single provider and a couple of methods, this may be overkill, and direct integration is justified if logistics is not critical to the scenario.
But as soon as there are several delivery services, an offline mode, or response-time requirements, the intermediary layer pays off: the app stops depending on third-party releases and outages.
In practice, we more often choose a hybrid: data critical for the user goes through an intermediary layer with caching, while rare operations allow a direct call.
We make the decision based on load, the number of providers, and availability requirements — and we lock it into the connection architecture before development begins, so we don't have to rebuild the client later.
Common technical concerns about logistics integration
Integration with an external logistics service is almost never "green" from day one — and this is a normal engineering scenario, not a sign of a bad solution.
Below are the concerns that most often come up among technical teams during the evaluation and acceptance stages, and how we address them in practice.
We already have a logistics integration deployed — do we need to rewrite everything from scratch?
No. First, we examine the current setup: which calls go to the logistics service, where shipment statuses are stored, how errors and retries are handled.
We reuse part of the code and isolate part of it behind a separate access layer to the external service — so that replacement or modification doesn't affect the rest of the application.
A rewrite from scratch is justified only if the current implementation doesn't separate business logic from calls to the external service.
What should we do if the external service responds unstably or with delays?
We don't control the external service, so we design things so that its failures don't bring down the application.
Status requests go through a queue with retries and increasing delays, responses are cached, and the user is shown the last known state with an honest note "data is being updated." If the service is unavailable, the order is placed and queued — the operation isn't lost.
How do we make sure shipment statuses are displayed correctly?
Statuses are the most sensitive part: a discrepancy between the application and the actual position of the parcel immediately triggers support requests.
We define a finite set of states and the transition rules between them, verify them against what the service actually returns, and cover edge cases with checks: cancellation, return, re-delivery, a stuck parcel. Separately, we verify that the application doesn't show a stale status as current.
These concerns are resolved at the design stage, not after launch. If your team has its own list of questions about integration — we'll go through them together with your scenario.
Let's discuss your logistics integration task
To come back with an estimate and a plan rather than generalities, we need to understand your current picture: what stack the app is built on, whether there is already a checkout module, how the user account area is structured, and where shipment statuses are stored.
This determines whether we embed the integration into existing screens or design the delivery scenarios from scratch.
Send whatever you have on hand — we'll take it from there:
- scenario descriptions: creating a shipment, calculating cost and delivery times, tracking by number, status change notifications, returns;
- what data is already collected in the app — addresses, recipient profile, order history, cart;
- how delivery currently works: manual tracking number entry, calls to support, a separate page on the website;
- authorization and access requirements — is account login needed to place an order, or is a guest scenario sufficient;
- platforms and minimum system versions that must be supported;
- timeline and release cycle constraints — when the app must go live in the store;
- who on your side makes decisions on delivery logic and approves notification texts.
Based on these inputs, we prepare an integration estimate: a list of scenarios with priorities, a data exchange scheme between the app and the logistics service, and a phased work plan with acceptance checkpoints.
We separately define what we do in the first release and what we move to the second — so that the launch doesn't stretch over months.
Describe the task in whatever form is convenient: a short message, a voice note, or a list from an email. We'll come back with an estimate and a work plan, and as we go through it we'll clarify the details that affect timelines and scope.