Shipment
Shipment Overview
A shipment in Cargamos refers to the service of delivering packages. Shipments are requested by shippers through the "integration" of an order. When requesting a shipment, it's necessary to provide the following information:
- Shipper Identification Information: Depending on the mechanism used to perform the integration (i.e. API, SDK, spreadsheet, etc.), this information is usually provided implicitly (i.e. access tokens, logged-in user in the console, etc.).
- Recipient Information: The recipient's location (delivery address) is required, along with basic contact information that is used in case there are issues locating the address. The location, particularly the postal code field, is used to determine coverage for the delivery, meaning if there's a logistical network to deliver the package to the specified location.
- Package Details: The weight and dimensions of the package are required, and if available, the information required for Carta Porte.
- Information Associated with the Shipment's Service Level: This includes the expected date to transfer custody of the package to the designated Cargamos last-mile distribution center, the promised delivery date, and additional (optional) identifiers associated with the package.
Shipment Lifecycle
The process of delivering a package by Cargamos can be described through various stages. These stages can be represented in a Finite State Machine (FSM) using states. The shipper can request to be notified if the FSM transitions to a new state and/or can query the status of their shipment service. For this purpose, the webhook API and/or the shipment-tracking API should be used, which are described in other sections of this documentation.
Fig. States and Events in the Shipment Service
In the figure, states with a bold border are final states. A description of each of these states can be found in the table below.
| State | Desciption |
|---|---|
| CREATED | The order is integrated after completing the coverage validations and converted into a shipment with its own Id which serves as a unique identifier and reference to be tracked (as well as the value of the shipper tracking Id). |
| ARRIVAL SCAN | The package is physically received and scanned at one of the distribution centers operated with Cargamos technology. |
| OUT FOR DELIVERY | The package is confirmed on a route to be delivered within the day |
| NEXT IN ROUTE | The package is next to be delivered and is on its way to the delivery point |
| SHIPMENT AT LOCATION | The delivery man is at the delivery point waiting to receive the package |
| DELIVERY ATTEMPTED | After a delivery attempt, the package is scanned and the delivery is validated in one of the distribution centers operated with Cargamos technology, |
| MISHAP | The package was identified as broken, lost or stolen and is being prepared to be returned as it is not operable. |
| DELIVERED | The package has been delivered to the recipient |
| FLAGGED AS RETURNED | The package exceeded delivery attempts or could not be delivered and is on its way to the distribution center to be marked as returned to Shipper |
| RETURNED | The Shipper received the package in a distribution center operated with Cargamos technology |
| CANCELLED | The shipment was canceled and the order will not be processed |
Dates of Custody Change and Expected Delivery
In relation to the dates associated with the shipment's service level described above, they correspond to the following stages:
- Delivery of the package to Cargamos' last-mile distribution center: This should occur approximately on the date (day) that the shipper establishes in the shipperDropoffDate field.
Fig. Package Dropoff by the Shipper in the Last-Mile Distribution Center Network
- Delivery of the Package to the Final Customer: Cargamos ensures that the first delivery attempt (ideally successful) will be made on the date (day) set by the shipper in the expectedDeliveryDate field.
Fig. Delivery of the Package to the Final Customer
Please note that in order to meet the promised delivery date, the shipper must perform the package dropoff at the distribution center within the time specified in shipperDropoffDate, and the time span between shipperDropoffDate and expectedDeliveryDate must be in accordance with the terms agreed upon in the service contract signed with Cargamos.
:::