An overview of the Stalls Logistics API.
Use cases
The Logistics API can help you build delivery solutions for the following business models:
- Direct to consumer: Provide a direct delivery option from your warehouse to customers.
- Marketplace: Connect all users within your app and facilitate commerce between them.
- Platform: Build delivery infrastructure between your customers and their customers.
Objects
Delivery points
Delivery points are simply the location involved in the delivery and some extra information regarding the location for how the delivery should be made or who is involved in the delivery. This can be a pickup location and dropoff location and can be represented with an address in words, or just latitude and longitude coordinates.
Supported actions for delivery points
- Creating delivery points with either street addresses or geo-coordinates
- Viewing your delivery points
- Updating information about your delivery points
- Deleting your delivery points
Reusing delivery points
Delivery points are saved so you can reuse or search for them easily for future deliveries.
Delivery requests
Delivery requests are simply a created intent to perform a delivery via the API. They must include the pickup and dropoff locations, as well as items to be delivered and information about them.
Supported actions for delivery requests
- Creating a new delivery request with delivery points (pickup and dropoff) and items
- Fetching delivery requests and data about them
- Refreshing a delivery request to get new quotes
- Canceling a delivery request
Deliveries
Deliveries are individual instances of dispatch from one delivery point (pickup) to another (dropoff). These are initiated by selecting one of the quotes returned from creating a delivery request.
Supported actions for deliveries
- Creating a delivery with a delivery request's quote
- Viewing deliveries and data about them
Multiple deliveries
It is possible to have multiple deliveries per delivery request.
Tracking Status Codes
The real-time status of each delivery can be tracked using the status field of the delivery. Below is a list of status codes and a description of what they mean regarding a delivery's status.
| Status Code | Description |
|---|---|
| pending | Delivery has been accepted but does not yet have a courier assigned. |
| pickup | Courier is assigned and is en route to pick up the items. |
| pickup_complete | Courier has picked up the items. |
| dropoff | Courier is moving towards the dropoff. |
| delivered | Courier has completed the dropoff. |
| canceled | Delivery has been canceled. |
| returned | The delivery was canceled and a new delivery created to return items to the sender. |
| ongoing | Delivery has been accepted and not yet delivered. |
Standards
The Logistics API uses the metric system for length and weight. Dimensions are saved and returned in cemtimeters (cm) and weights are in kilograms (kg).
Rounding
All dimensions and weight measurements are rounded up to the nearest second decimal place.
Dimensions
| Name | Lower bound (cm) | Upper bound (cm) | Description |
|---|---|---|---|
| small | >= 0.01 | <= 10.00 | can be hand carried |
| medium | >= 10.01 | <= 30.00 | can fit in a dispatch messenger bag or box |
| large | >= 30.01 | <= 60.00 | can fit in the trunk of a car |
| xlarge | >= 60.01 | <= 240.00 | can only fit in a van |
Weights
| Name | Lower bound (kg) | Upper bound (kg) | Description |
|---|---|---|---|
| feather | >= 0.01 | <= 1.00 | can be held in your palm |
| not_heavy | >= 1.01 | <= 5.00 | can be carried with one hand |
| quite_heavy | >= 5.01 | <= 10.00 | can be lifted with one hand |
| heavy | >= 10.01 | <= 20.00 | can be carried with two hands |
| very_heavy | >= 20.01 | <= 30.00 | can be lifted with two hands |
| extremely_heavy | >= 30.01 | <= 50.00 | can be lifted by two adults |