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 delivery could not be completed and our support team is handling the parcel.
• 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.
• internalcancel: The shipment request has been canceled by the system. When we rejected the request, failure_reason says why:
  • payment_method_declined: There is a problem with your payment method, and the delivery has not been accepted.
  • no_payment_methods: There is no payment method configured.
  • requester_not_found_or_unauthorized: The requester sent in this request is not valid.
  • product_does_not_exist: No product is configured for this shipping type and your account.
  • 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_exist: A delivery already exists for this parcel.
  • unknown: Something has happened but, unfortunately, we haven't detected the reason. If the problem persists, please get in touch with the Logistics Team.
• 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.

This list applies to every modality. The express
and cross-dock pages describe how a parcel
gets here.

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 usually continues into the return flow (onroutetoreturn,
  returning, returned), or ends in returnrejected or incident. A parcel
  in pickupfailed can be shipped again.
• requestercancel is not final either: you can update the parcel and ship it
  again, or delete it.
• internalcancel cannot be shipped again. Nothing you send moves it on except
  a delete, so create a new parcel to try the delivery again.

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