# Statuses

## Life cycle

To complete a delivery, it must go through a series of state changes, which we detail in the following image.

<figure><img src="https://content.gitbook.com/content/3sizVsCVOI8uyboT6DNP/blobs/NzgGDtTWaJaM9FGCftQ5/image.png" alt=""><figcaption><p>Estados de una entrega</p></figcaption></figure>

### Inicial states

When a delivery is created in the system, it can be created with a **'Processing'** status, which means the task was created successfully and is ready to be assigned. When created as **'Pending Review,'** it's because there was an error in geolocation, either in the pickup or delivery address, and it's necessary for an operator to correct the address so it can move to 'Processing' and continue the flow.

### Assignation

To link a delivery with a driver, there are two options: either put it in **'broadcasting'** status (the delivery is published in the network of drivers for one of them to take it in the mobile application) or assign it directly to a driver (this process is carried out by an operator in the dashboard; when assigned, it doesn't mean the driver has accepted the task).

### Collecting

When a driver takes the delivery from the mobile app or an operator assigns it from the dashboard, and the driver accepts the delivery in the app, it moves to **'confirmed for collection'.** After confirming the collection, the driver indicates from the app when they are on their way for the collection. Finally, upon arriving at the warehouse, the driver marks in the app that they are at the collection point. Throughout this process, the driver can reject the delivery, changing its status to **'not collected'.**

### **Failed to collect**

Throughout this collection process, the driver can reject the delivery, changing its status to '**not collected'**, thus leaving the delivery without an assigned driver. Under this state, reasons can be configured to describe the reason for the change or rejection, such as vehicle issues

### Delivery

When the driver is at the warehouse, they proceed to scan and verify the packages for delivery. If the delivery belongs to a route, the same process must be carried out for each one. During this process, the task is in the **'in delivery'** status. After completing the verification, it moves to '**on the way to delivery'**, and subsequently to **'at delivery point'** when it arrives at the agreed-upon address.

### Failed attempt to deliver

Throughout this delivery process, the driver may abstain from completing the delivery by changing it to the status **'hold by courier'**. Under this status, reasons can be configured to describe the reason for the change, for example, the customer was not at the address. The driver can attempt delivery up to a maximum of 3 times, in case the delivery is successful, the task continues in the green flow, otherwise, it follows the red flow that returns the package to the warehouse, leaving the delivery as **'returned'**.

### Final states&#x20;

After delivering the packages to the recipient, proof of delivery is requested in the app, such as photos or a signature from the person receiving the package. Once the proof is provided, the task changes to the **completed** state, thus ending the task lifecycle.

### Cancelation

At any step of the flow, the delivery can be canceled, either through the external API integration or from the dashboard. When canceled, the delivery is left without a driver. Under this state, reasons can be configured to describe the reason for the change, for example, customer canceled the order.

## **Statuses codes**

<table><thead><tr><th>Delivery States</th><th>Code</th><th width="321">Description</th></tr></thead><tbody><tr><td>Pending to review</td><td>pending_to_review</td><td>A delivery is created with missing pickup or delivery information (contact, location) and needs review</td></tr><tr><td>Processing</td><td>processing</td><td>A delivery is successfully created on the platform</td></tr><tr><td>Broadcasting</td><td>broadcasting</td><td>A delivery has been broadcasted to a network of drivers</td></tr><tr><td>Assigned</td><td>assigned</td><td>A delivery has been assigned to a driver</td></tr><tr><td>Confirmed to pickup</td><td>confirmed_to_pickup</td><td>A delivery has been confirmed for a driver to carry out</td></tr><tr><td>Going to pickup</td><td>going_to_pickup</td><td>A driver is heading to the pickup location</td></tr><tr><td>At pickup</td><td>at_pickup</td><td>A driver is at the pickup location</td></tr><tr><td>On delivery</td><td>on_delivery</td><td>Driver en route to delivery</td></tr><tr><td>Going to dropoff</td><td>going_to_dropoff</td><td>A driver is heading to the delivery address</td></tr><tr><td>At dropoff</td><td>at_dropoff</td><td>A driver is at the delivery address</td></tr><tr><td>Dropped off</td><td>dropped_off</td><td>A driver is awaiting the delivery receipt (photo, signature, recipient's information)</td></tr><tr><td>Completed</td><td>completed</td><td>A driver has successfully completed a delivery</td></tr><tr><td>Canceled </td><td>canceled</td><td>A delivery was canceled </td></tr><tr><td>Going to return</td><td>going_to_return</td><td>A driver is heading to the pickup address to return a delivery</td></tr><tr><td>At return point</td><td>at_return_point</td><td>A driver is at the pickup address to return a delivery</td></tr><tr><td>Returned</td><td>returned</td><td>A driver has successfully returned a delivery</td></tr><tr><td>Not picked up</td><td>not_picked_up</td><td>A driver has reported that a delivery was not picked up</td></tr><tr><td>Not picked up payable </td><td>not_picked_up_payable</td><td>A driver has reported that a delivery was not picked up, but they will still be paid</td></tr><tr><td>Hold by courier</td><td>hold_by_courier</td><td>The delivery is held by the assigned driver until a new attempt is made or it is returned to the pickup address</td></tr></tbody></table>

## **Problems and Reasons**&#x20;

If you need to specify the reason why a task changed to a certain state, you can configure the reasons you want for the state of your preference. These reasons will explain or provide more detail about the change. If in your external system you have a state that does not exist in our list, you can link it to the one that most closely resembles it and create a reason under it that identifies it better. Generally, these reasons are added to the 'hold\_by\_courier' and 'canceled' states.

### &#x20;Examples

<table><thead><tr><th width="195">State in Shippify</th><th>Reason</th><th>External state</th></tr></thead><tbody><tr><td>hold_by_courier</td><td>Recipient rejected the package</td><td>Recipient rejected the package</td></tr><tr><td>hold_by_courier</td><td>Recipient can't be reached</td><td>Recipient can't be reached</td></tr><tr><td>canceled</td><td>Lost package</td><td>Lost package</td></tr><tr><td>canceled</td><td>Canceled by client</td><td>Canceled by client</td></tr></tbody></table>

### Creation

You can create these reasons within the dash by accessing the state and reason configuration [through this link](https://dash.shippify.co/settings/sections/deliveries/status-info). Here you will find system reasons that you can reuse, and if you don't find the one you need, you can create it.

#### Steps

1. Click on [this link](https://dash.shippify.co/settings/sections/deliveries/status-info).
2. Select a state.&#x20;
3. Check if there is no similar reason in the system to yours. If it exists, add it to your company; otherwise, create one.

<figure><img src="https://content.gitbook.com/content/3sizVsCVOI8uyboT6DNP/blobs/9YffFiBYpEe1BdPiV1ZJ/image.png" alt=""><figcaption><p>Motivos de problemas de entrega</p></figcaption></figure>

## Linking states with an external platform

Since you know the states and reasons within our system, you can proceed to link them with your system. For a better understanding of this, you can fill out [this spreadsheet](https://docs.google.com/spreadsheets/d/1UIZlIxcRq-iOfRq9-VyE8jzF9FKl-oEJ04Yxwt3n4JI/edit?usp=sharing).

Here's a table where you can fill in the information about the states in your system and their equivalent in Shippify.

<figure><img src="https://content.gitbook.com/content/3sizVsCVOI8uyboT6DNP/blobs/9i53lZNIhvtvZZdV1wzN/image.png" alt=""><figcaption><p>Plantilla</p></figcaption></figure>

### Steps

1. List the states of your platform in the blue column&#x20;
2. Find the equivalent state in Shippify. You can help yourself by asking the following questions:
   1. Is it a state that occurs before the collection of packages in the warehouse?
      1. [When you recently create/schedule it.](#estados-iniciales)
      2. [When its broadcasting.](#asignacion)
3. [Is it a state that occurs during the pickup process?](#recoleccion)
4. [Is it a state that occurs during the delivery process? ](#entrega)
5. Is it a state that indicates there was an issue?
   1. [During the pickup process?](#recoleccion-fallida)
   2. [During the delivery process?](#entrega-fallida)
   3. [General](#cancelacion)
6. [Is it a state that indicates a successful delivery? ](#estados-finales)
7. If you need more details for a state or if you got the same state in Shippify for 2 or more states from your platform, then [you can add them to a specific state.](#motivos-de-problemas)

Once you have your table filled out, you can proceed to configure the [state synchronisation](https://docs.shippify.co/developers/en/integration-guide/basic-processes/status-update) in your system.