In Parcelizer, an order is a specific request to have an item picked up from one location and delivered to another (in the case of single stop orders, only the delivery location is used).
To retrieve an order by specifying its ID, you can use the Get Orders API:
Endpoint GET https://api.parcelizer.com/ex/orders/{orderId}
Headers
api_key: YOUR_API_KEY (taken from Settings > General Settings)
Response
{
"routePlanType": "VRP",
"orderCode": "PM2GAHZDN9Z",
"orderRef": "PM2GAHZDN9Z",
"requiredSkills": ["vip", "on-demand"],
"deliveryDate": "2023-07-29T00:00:00.000Z",
"deliveryTimeStart": "9:00",
"deliveryTimeEnd": "11:00",
"status": "COMPLETED",
"errorDetails": [],
"notes": "weight: / time_window: / door_code:",
"driverNotes": "Delivered safely ",
"packageWas": "Received by Person",
"pickupEta": null,
"pickupStatus": "ASSIGNED",
"deliveryName": "Irma Henry",
"deliveryAddress": "766 Calverhall St, North Vancouver, BC V7L 1X6, Canada",
"deliveryLat": 49.3137055,
"deliveryLng": -123.0513728,
"deliveryPhone": "+6593654527",
"deliveryEta": "22:48",
"deliveryDuration": 15,
"deliveryNotes": "pls leave package in lobby",
"fields": {},
"pods": [
"https://parcelizer.s3.us-east-1.amazonaws.com/60e5c88f502c618b521d2565/ZRVLfZAJze0wZU2lOc3eQ.jpg"
],
"signature": "https://api.parcelizer.com/ex/orders/64c3564336d82c1e3c709834/signature.jpg",
"logs": [
{
"status": "ASSIGNED",
"notes": "",
"createdAt": "2023-07-28T05:46:59.684Z"
},
{
"status": "DELIVERY_ARRIVED",
"notes": null,
"createdAt": "2023-07-28T05:48:43.063Z"
},
{
"status": "COMPLETED",
"notes": "Received by Person",
"createdAt": "2023-07-28T05:49:42.021Z"
}
],
"company": "60e5c88f502c618b521d2565",
"routePlan": "64c3563136d82c1e3c709802",
"createdAt": "2023-07-28T05:46:43.276Z",
"updatedAt": "2023-07-28T05:49:42.026Z",
"labels": [],
"_id": "64c3564336d82c1e3c709834",
"driver": {
"companies": [
{
"roles": [
"driver"
],
"company": "60e5c88f502c618b521d2565"
}
],
"groups": [],
"partnerNames": [],
"name": "will-yvr",
"email": "delivery.driver@afi.io",
"startAddress": "1132 E Hastings St, Vancouver, BC V6A 1S2, Canada",
"startLat": 49.2806937,
"startLng": -123.080293,
"skills": [],
"phone": "+18077098998",
"color": "00a2b9",
"shiftStart": "08:00",
"shiftEnd": "12:00",
"speed": "NORMAL",
"status": true,
"createdAt": "2021-12-07T07:18:33.880Z",
"updatedAt": "2023-07-28T23:07:59.383Z",
"_id": "61af0ac95c292adbb74829c0"
}
}
Note: The above JSON is representative of a single stop order. Pickup and delivery orders have a similar structure but have additional fields that describe the pickup stop.
Order Object Attributes
routePlanType (string)
The type of route plan this order can be added to.
VRP: for single stop orders that are routed with the Vehicle Routing Problem algorithm.
PDP: for pickup and delivery orders that are routed with the Pickup and Delivery Problem algorithm.
orderCode (string)
The unique 11 digit alphanumeric code used to uniquely identify this order.
orderRef (string)
A (hopefully) unique reference number (typically an invoice number) that you can use to identify the order. If none is supplied, Parcelizer will set its value to be the same as orderCode.
requiredSkills (array)
An array of driver skills (fields that let you match specific orders with drivers that are equipped to do those orders e.g. a driver with the "VIP" skill can pickup and deliver "VIP" orders) that is associated with this order.
deliveryDate (string ISO 8601)
The date and time the order is scheduled to be delivered.
deliveryTimeStart (string)
The earliest time in hh:mm format you need to deliver this order. For example, if the customer specified that he wanted his package delivered between 3 pm and 5 pm, put "15:00" in this field.
deliveryTimeEnd (string)
The latest time in hh:mm format you need to deliver this order by. For example, if the customer specified that he wanted his package delivered between 3 pm and 5 pm, put "17:00" in this field.
status (string)
The status of the order. It can be one of:
DRAFT: The order has not yet been added to a route plan.
ERROR: There is missing or bad data associated with the order e.g. "pickup lat must be a latitude string or number" and the order cannot be added to a route plan
GEOCODING: The order is being geocoded (Parcelizer uses the Google Maps API for this)
UNASSIGNED: The order has been added to a route plan but has not been added to a route plan.
ASSIGNED: The order has been assigned to a driver (either manually or via route optimization.
UNSCHEDULED: Parcelizer tried to optimize routes and assign this order to a driver, but could not do so.
GONG_NEXT: The driver has marked on the app that he is heading directly to this order's pickup or delivery.
SKIPPED: The driver has skipped a pickup or delivery on this order.
PICKUP_ARRIVED: The driver has arrived at the pickup location.
PICKUP_FAILED: The driver marked the pickup as failed.
COLLECTED: The driver has successfully collected a package from the pickup location.
IN_TRANSIT: The driver has collected a package from the pickup location and has started heading to the next stop (he clicked "next stop" on the app).
DELIVERY_ARRIVED: The driver has arrived at the delivery location
DELIVERY_FAILED: The driver has marked the delivery as failed.
COMPLETED: The driver has successfully completed both the pickup and delivery.
errorDetails (array)
An array of error message strings that explain why the order has a status of ERROR e.g. "pickup lat must be a latitude string or number".
notes (string)
Notes shown on the driver app to help your drivers complete the delivery successfully. These are typically instructions from customers e.g. "please leave the package in the lobby".
driverNotes (string)
Notes entered by the driver (on the app) when completing a delivery.
packageWas (string)
The delivery option selected by the driver. It can be one of:
Received by person: Handed to a customer.
Safe dropped: Placed somewhere safe where it can be retrieved by the customer later.
pickupEta (string)
The estimated arrival time at the pickup location.
pickupStatus (string)
The status of the pickup e.g. "PICKUP_ARRIVED" (see the status field for a list of valid statuses.
deliveryName (string)
Name of the customer receiving the delivery.
deliveryAddress (string)
The address of the customer you are delivering this order to. Ideally, it includes a zip code e.g. "198 W 18th Ave, Vancouver, BC V5Y 2A5, Canada".
deliveryLat (number)
The geocoded (Parcelizer uses the Google Maps API) latitude of the delivery address.
deliveryLng (number)
The geocoded (Parcelizer uses the Google Maps API) longitude of the delivery address.
deliveryPhone (string)
Phone number of the customer you are delivering this order to. Ideally this will include the country code and plus sign e.g. +17789123456 for US/Canada numbers or +6593456789 for Singapore numbers.
deliveryEta (string)
The estimated arrival time at the delivery location.
deliveryDuration (number)
The service time at the delivery location (note: this is not the actual time spent by the driver at the location - this can be calculated by going to the logs object and taking the difference between the DELIVERY_ARRIVED and COMPLETED time stamps).
deliveryNotes (string)
Notes shown on the driver app to help your drivers complete the delivery successfully. These are typically instructions from customers e.g. "please leave the package in the lobby". This is a duplicate of the notes field.
fields (object)
A hash of custom fields and their attributes e.g. "company_name": "pantagonia" that you'd like to associate with this order.
pods (array)
An array of URL strings that link to the compressed proof of delivery ("pods") images e.g. https://parcelizer.s3.us-east-1.amazonaws.com/60e5c88f502c618b521d2565/ZRVLfZAJze0wZU2lOc3eQ.jpg used for photo and/or signature proof of delivery.
logs (array)
An array of log objects that describe events such as completion of a delivery.
log object properties
status: the order status e.g. "COMPLETED" associated with the event.notes: any notes captured during the event e.g. the driver marks that a delivery was "received by person".createdAt: the ISO 8601 timestamp of the event.
company (string)
The uuid of the company that created this order (for internal Parcelizer use only).
routePlan (string)
The uuid of the route plan that this order is associated with (you can use this to retrieve information about the route plan using the Get Routeplan API.
createdAt (string ISO 8601)
The date and time that the order was created.
updatedAt (string ISO 8601)
The date and time that the order was last modified.
labels (array)
An array of strings with the names of the labels associated with this order.
_id (string)
The unique ID of the order. This is different from the orderRef property, which is the ID used by the customer. The underscore in "_id" indicates that it serves as a primary key.
driver (object)
The driver associated with this order (if one is assigned).
driver object properties:
companies: an array with a single object inside it that contains information about the company this driver belongs to.groups: not applicable to drivers.partnerNames: not applicable to drivers.name: the name of the driver.email: the email address of the driver.startAddress: the driver's start location (used in route optimization).endAddress: the driver's end location (used in route optimization).startLat/startLng: the starting location coordinates.endLat/endLng: the ending location coordinates.skills: an array of driver skills (used to match specific drivers with orders).phone: the phone number of the driver (used to dispatch routes via text message).color: the assigned color of the driver (used to color the driver's route).shiftStart: the driver's start time.shiftEnd: the driver's end time.speed: the relative speed of the driver (used to calculate ETAs)status: not applicable to drivers.createdAt: the date and time the driver was created.updatedAt: the date and time the driver was last modified._id: the unique ID of the driver.