REACT's Calculated Events feature helps you to stay on top of shipments that may have gone missing, or which have passed their delivery promise date. This page explains the shipment properties that REACT can calculate, how calculated events work, and how best to use calculated events
What is a Calculated Event?
A calculated event is an event that is generated by REACT's internal processing, rather than as a result of an external tracking update.
Each shipment has two properties that REACT can change without receiving a carrier tracking update. They are:
may_be_missing- Indicates whether REACT believes that the shipment may be missing. REACT marks shipments as
may_be_missingif they are not updated within a set time period after registration, or if they are not marked as delivered, lost, or refused within a different set time period.
lateness. Contains two sub-properties -
lateness.hours_late. These properties indicate whether REACT believes a shipment to be late, and (where applicable) how many hours late this shipment is.
When REACT updates one of these properties, it creates a calculated event to record the change. You can retrieve calculated events in the same way you would retrieve regular, carrier-derived events.
May Be Missing
If REACT believes that a shipment may be lost, it sets that shipment's
may_be_missing property to true. By default, the
may_be_missing property is set to false.
may_be_missingis always set based on REACT's internal calculations. A
may_be_missingvalue of true does not mean that the carrier has notified Sorted that the shipment may be missing.
REACT sets a shipment's
may_be_missing property to true if either of the following conditions are met:
No state changing tracking event has been received for that shipment within 12 hours of the shipment being registered with REACT (as recorded in the
created_on property) OR within 12 hours of the
shipped_date (whichever is earlier). Note that
shipped_date is an optional field.
All of the following conditions are met:
- The shipment has never been in any of the final states.
- The shipment has a country ISO code registered for both its origin and destination addresses (via the
- It has been more than 24 hours since a tracking event was received for a domestic shipment, OR more than 72 hours since a tracking event was received for an international shipment.
Shipments are classed as domestic if their origin and destination
addresses.country_iso_code is identical. Otherwise, they are classified as international.
lateness.is_late property denotes whether REACT believes a shipment to be late. By default, the
is_late property is set to false. REACT sets
is_late to true if all of the following conditions are met:
- The shipment has a
- The date and time recorded in
- The shipment did not enter any of the final states before the
If a shipment does not have a
promised_date recorded, then REACT cannot perform
lateness calculations for that shipment.
If a shipment is marked as late, then REACT records how many hours late it is in the
lateness.hours_late property. This information is refreshed every time the shipment is retrieved from the Tracking, Shipment or Events APIs.
is_late flag is reset if the shipment is updated with new
promised_date information (as long as the new
promised_date has not also already elapsed). If
is_late is reset to false, then
hours_late is reset to NULL.
is_lateshipment property should not be confused with the Late shipment state. Like all other shipment states, the Late shipment state is assigned on the basis of a carrier tracking event that REACT has received. Simply put, the
is_lateproperty is used when REACT notices a shipment is late, while the Late shipment state is used when a carrier tells Sorted that the shipment is late.
To optimise performance, REACT periodically marks old shipments as "non-trackable". The system only performs
lateness calculations on trackable shipments.
A shipment is deemed to be non-trackable if any of the following criteria are met:
- The shipment is domestic (i.e. the
addresses.country_iso_codeof its origin and destination addresses is identical) AND Sorted has not received a tracking event for it in seven or more days.
- The shipment is international (i.e. the
addresses.country_iso_codeof its origin and destination addresses is different) AND Sorted has not received a tracking event for it in 10 or more days.
If we do not know whether a shipment is domestic or international (i.e. it does not have a
addresses.country_iso_coderecorded for both its origin and destination addresses), then it is assumed to be domestic.
- The shipment is in a final state AND Sorted has not received a tracking event for it in three or more days.
REACT uses the concept of "final shipment states" when determining whether shipments are lost or potentially missing. The list of final states covers all the potential outcomes for a shipment delivery. Once a shipment enters a final state, its journey is considered to have ended and REACT no longer tracks it.
The full list of final states is:
Using Calculated Properties
Although set by REACT, the
may_be_missing flags are standard properties and can be integrated in exactly the same way as any other shipment data. They are returned by the Shipments and Events APIs,as part of the Shipment and Shipment Events resources.
For more information on retrieving data via REACT's APIs, see the Retrieving Shipment and Event Data page.
Learn more about integrating with REACT: