Parcels life cycle

What does the parcel life cycle mean in our platform?

The parcel life cycle is the different states that it passes through from the moment it is created until it is delivered to the recipient or returned to the sender.

The states that a parcel can go through are:

• ready: The parcel has been created and is ready to shipment request.
• readytopickup: The parcel is ready in your warehouse or store and we can go to pick it up.
• receivedonfinalhub: The parcel has been received at our last mile delivery hub.
• readytodispatch: The parcel is in our hub ready to be dispatched in the next last mile delivery.
• scheduled: The sender schedules the parcel pick up.
• qualifiedforpickup: The parcel has been assigned to a last mile delivery route.
• onroutetopickup: Driver is assigned to the last mile delivery route, and is on the way to pick up the parcel.
• pickingup: The driver is picking up the parcel.
• intransit: The route of last mile delivery where the parcel is, is in progress.
• onroutetodelivery: The parcel is the next delivery in the last mile delivery route.
• delivering: The driver is in the drop-off location delivering the parcel.
• delivered: The parcel has been delivered to the recipient.
• undelivered: The parcel could not be delivered to the recipient, this state has several substates with the reason:
  • recipient not found.
  • rejected by recipient.
  • wrong address.
  • unsafe delivery zone.
  • invalid proof.
  • other.
• onroutetofinalhub: The parcel is on the way to our last mile delivery hub.
• onroutetoreturn: The parcel is on the way to the sender.
• returning: The driver is in the parcel pick-up location returning the parcel to the sender.
• returned: The parcel has been returned to the sender.
• returnrejected: The return to the sender is not required and the delivery cannot be completed.
• incident: The parcel has been involved in an incident (this state has several substates with the reason).
  • payment_method_declined: There is a problem with your payment method, and the delivery has not been accepted. Check your payment methods in the business web
  • no_payment_methods: There is no payment method configured. Check your payment methods in the business web
    requester_no_found_or_unauthorized: The requester sent in this request is not valid.
  • invalid_pick_up_location: There is no fleet available for your delivery area, or it's not properly configured. Please get in touch with the Logistics Team to check if we can cover your delivery area.
  • delivery_already_exists: This parcel has been delivered already.
  • unknown: Something has happened but, unfortunately, we haven't detected the reason. If the problem persists, please get in touch with the Logistics Team.
• requestercancel: The sender has canceled the shipment request.
• pickupfailed: The driver could not pick up the parcel, this state has several substates with the reason:
  • Sender not found.
  • Sender arrived to late.
  • Sender address wrong.
  • Sender address not safe.
  • The parcel is suspicious.
  • The parcel packaging is not suitable.
  • The parcel is too big or heavy for the driver's vehicle.
  • A payment was requested.
  • Other with comments.
  • The place was closed.
  • Sender not found the parcel.
  • Already picked up.
  • Delivery cancelled.
• returnfailed: The driver could not return the parcel, this state has several substates with the reason:
  • sender not found.
  • rejected by sender.
  • wrong address.
  • unsafe delivery zone.
  • other.
• internalcancel: The shipment request has been canceled by the system.
• deleted: You have deleted the parcel in our system (note that is an state not a real deletion).

Which states are final

Five states are final: the parcel stops there on its own, and no further
notification will arrive for it unless you act on it again.

Every other state is still in motion, including the ones that read like an
ending:

• undelivered and pickupfailed are not final. A parcel that could not be
  delivered or collected usually continues into the return flow
  (onroutetoreturn, returning, returned).
• requestercancel and internalcancel are not final either. A cancellation
  is not always the last thing that happens to a parcel, so keep reading it
  until it reaches one of the five above.

This matters if you poll. Stop polling a parcel when it reaches a final state,
and only then: treating a non-final state as an ending leaves you believing a
parcel finished where it did not, and treating a final state as ongoing means
polling it forever.

📘

Final is not the same as immutable

A parcel in returned came back to you and is not moving, but it is still a
valid parcel: requesting its shipment again puts it back into the flow and
notifications resume. delivered, returnrejected, incident and deleted
do not work that way — nothing you send will move them, and a new delivery
needs a new parcel.

So "final" means the parcel will not change by itself. It does not mean the id
is dead.

As you can see, some of the states of the parcel involve a warehouse but, depending of the shipping type that you choose, they may be omitted. Regarding this, we have two separate life cycles for the parcel: one for the parcels that pass through a warehouse and another for the parcels that do not.

• Parcel life cycle without warehouse or express operations
• Parcel life cycle with warehouse or cross-dock operations