Auto refresh interval based on parcel status

[peternijssen]

Currently integrations poll on a fixed interval. This idea proposes a dynamic poll cadence based on the current status of a tracked parcel, e.g.:

• 15 min tier for parcels that are actively moving / out for delivery
• 30 min tier for parcels in transit with no imminent delivery
• 120 min tier for parcels with no expected status change soon (e.g. pre-transit, delivered)

Fully designed already (including an options-flow label and diagnostics), just not yet implemented in any carrier integration.

Open question: should "auto" also apply to an outgoing-coordinator (present in some integrations for return/outgoing shipments), or only to inbound polling?

[JelleKoster]

I would say having "auto" be applicable to both outgoing and ingoing parcels would be more consistent / transparant.

The status driven approach is an interesting one which could overlap or be complementary with my time window based idea.

Based on my experience supporting & consulting for a multi-country multi-directional Customs software package, I am a bit cautious with status matrixes having a functional impact. The parcel contract abstraction layer and the passiveness of this functionality mitigate most risks (user's can't mess the status up). Which frequency tier would you allocate the "unknown" status group to?

Overall I'd personally lean a bit more conservative.
E.g.

• For "delivered" parcels, I'd expect no further polling is required given that it is an end state.
• for parcels pre-transit or in transit, I'd opt for a daily morning polling given that their exact status change timing adds very little functionality
• For parcels out for delivery, I'd only start the frequent polling an hour before the delivery window start.

This, along with a lower polling frequency for the detection of new parcels, would help reduce the amount of API calls towards carriers noticeably.

[peternijssen]

What is your thought on this @JelleKoster ?

Barcode-based (manually added tracking codes — most carriers)

• Quiet window (~00:00–06:00, fixed for now): no polling.
• 06:00 and ~00:00: anchor poll for overnight/end-of-day updates.
• During the day, poll frequency follows status:
  • out_for_delivery / problem / returning → every 15 min, starting 1h before planned_from.
  • registered / in_transit / at_pickup_point / unknown → every 30–60 min.
  • delivered → stop polling that parcel.
• If every tracked parcel is delivered (or none are configured): stop polling entirely — nothing can appear on its own, the user has to add a tracking code manually, which triggers an immediate refresh anyway.

Account-based (credentials variant, e.g. PostNL/DHL — a single call returns everything)

• Same quiet window (fixed) + anchor polls at 06:00 / ~00:00.
• During the day: always poll every 30–60 min, regardless of whether there are pending parcels — this covers both status updates and detecting new shipments that appear on the account without any user action.
• Switches to the hot 15-min tier only when an active parcel is out_for_delivery / problem / returning, starting 1h before planned_from.
• No separate discovery mechanism needed — every poll already returns the full account state, so this is purely a matter of frequency, not an extra API call.

[JelleKoster]

Overall that sounds like a good approach.

One thing which draws my attention is the account-based 30-60 minute polling without any pending parcels.
I'd like to explore the scenarios for this with you.
The way I see it there are two types of users:

• with frequent parcel deliveries (e.g. a few a week)
• with infrequent parcel deliveries (e.g. a few a month)

In the first case, the total amount of polls is not significantly reduced by avoiding these polls. In the second, it is.
The challenge is same day deliveries. While I haven't personally seen these B2C, it is fair to assume that internationally, we'll encounter them.
This is the main use case of a frequent new parfel detection.
For all other usages, the only benefit to early detection is slightly earlier visibility of the pending parcel and the scheduled delivery dates & timewindows. Keeping in mind there is always a delay between the webshop order and the carrier registration, I propose we don't poll for these every 30-60 minutes but at anchor moments, we could expand the Midnight and 6am timeslots to every 6 hours for example.

Aside from this, are the following already in place / have they been considered?

• API call staggering in place to avoid the simultaneous thundering herd
• exponential backoff on 429 too many requests

[peternijssen]

Thanks for the input. I see the amount of carriers doing same day delivery growing. So 6 hour window sounds too much in my opinion.

I'll take your input along, together with the staggering and the 429 header and devise a build plan to implement in all carriers. I prefer to keep, if possible, all carriers similar in set up.

Note to self: PostNL is currently the only carrier implemented with mail delivery. More carriers could come in the near future. Currently a poll once a day in the morning seems sufficient.

[peternijssen]

Over the past week, several updates to all carriers have been rolled out. After today, all carriers are automatically refreshed based upon the rules set here. Closing this discussion.