Required sections
The following sections are required to create an order.
"PickupAddress":{
"addressLine1":"7250 Mile End",
"addressLine2":"Suite 204",
"city":"Montreal",
"postalCode":"H2R3A4",
"stateProvince":"QC"
},
"DropoffAddress":{
"addressLine1":"426 Rue Saint Gabriel",
"addressLine2":"Suite 101",
"city":"Montréal",
"postalCode":"H2Y2Z9",
"stateProvince":"QC"
},
It is important that suite, apt, etc be added in addressLine2 and not be part of AddressLine1. Adding this information in AddressLine1 will result in an invalid address which will create an invalid order. Invalid orders cannot be auto-dispatched nor priced and will need to be fixed by the dispatcher on the Dispatch Board before they can be dispatched.
Including the location will bypass the address geo-localisation.
Default values
Language in both pickup and dropoff contact info will default to English. This is used for notification purposes.
If the email and/or the phone is omitted, notifications will not be sent if setup in the notification template.
Vehicle if not sent will default to the default vehicle associated to the account pricing.
ReadyAt, if not sent, will default to the order creation date and time in Dispatch Science.
Provided by the Administrator
The Dispatch Science administrator will provide the ServiceLevelIds, VehicleTypeIds, ExtraFeeIds and AttributeIds that can be used for an account in the API.
Invalid Orders
Using an invalid pickup and/or dropoff address without a location will result in an invalid order. The invalid order will not be auto-dispatched.
An invalid vehicle and/or service level will result in an invalid order that can still be auto-dispatched but will not have a valid price.
Detailed information on parameters
VehicleTypeId: This is the vehicle that will be used. This is used to calculate the price of the order. Ids are provided by the administrator. If no vehicletypeid is provided, the default vehicle type will be used in the order.
ServiceLevelId: This is the service level that will be used to calculate the order price. The Ids are provided by the administrator.
CollectOnDelivery: Driver should collect the specified amount from the customer upon delivering the package. This feature must be enabled on the account to be saved on the order.
AllowPartialCollectOnDelivery: Driver is allowed to collect a part of the amount in the CollectOnDelivery from the customer upon delivery the package. This contains true or false. This feature must be enabled on the account to be saved on the order. If it is enabled but omitted in the order creation, it will be set to false.
RequireIdentityValidation: Driver should validate the customer identity upon delivering the package. This contains true or false. If it is omitted in the order creation, it will be set to false.
NumberOfBoxes: Number of boxes that are part of this order. Depending on the account settings, the driver may have to scan each box that are part of the order before being able to complete the pickup and/or drop-off. If this is omitted in the order creation, it will default to 1.
Metadata: User defined key/values pair. You can use this to save custom information relative to this order. This information will not be visible in the order.
WebhookUrl: HTTP POST request to that URL with a JSON payload containing the OrderId on order status change. Please see WebhookUrl section at the end of this document to see what is returned upon each order status change.
ExtraFees: Extra fees, available for the account, can be added by specifying their Ids and a quantity. Quantity must be a positive number, if a negative number is sent, extra fee will be added with a 0 quantity. Quantities with a decimal will be calculated and total rounded up to the next integer when added to the order. An order, created with invalid extra fees or extra fees hidden from the account, will be created but the invalid/hidden extra fees will not be added on the order. The Ids are provided by the administrator
Attributes: Attribute can be added by specifying their Ids. The Ids are provided by the administrator.
Dropoff window, Ready At and Service Level
The dropoff window can be calculated, this requires a service level and Ready At, or it can be used as entered.
If the dropoff window should be calculated, the dropoff window section should not be sent.
Note: the dropoff window and Ready At can be sent in any time zone. A combination of UTC and EDT are used in the example above. Different time zones can be sent by changing the time zone part of the date-time field: "2018-07-12T16:00:00.0000000+00:00" to your time zone and entering the date and time in your current time zone.
When used as entered, the Ready At is used as the Pickup window start time, the service level will be used to calculate the price of the order. There is no validation that the dropoff window matches the service level hours of operations, pickup, order creation cut-off time and delivery time. The service level in this case is only used to calculate the price.
If no Ready At is available, the time of the order creation will be used as the Pickup start time.
If a Ready At is set after the end of the dropoff window, the pickup will use the start of the delivery window and the Ready At will be ignored.
If an invalid or no Service Level is sent with or without a Ready At and with a delivery window, an invalid order will be created with 0 pricing, the pickup = Ready At if provided or the order creation date if not provided and a list of validation errors will be returned in the response body:
{
"orderId": "9999",
"validationErrors": [
"InvalidPrice",
"InvalidServiceLevel"
]
}
If an invalid or no Service Level is sent with or without a Ready At and no delivery window, an invalid order will be created with 0 pricing, the pickup will be set for January 1, 0000
There will be no service level in the order and the service level will need to be entered on the order in Dispatch Science to calculate the order price.
Calculate Pickup and Dropoff window
Remove DropoffWindow section and enter a ReadyAt date-time and a ServicelevelId. This will calculate the order drop-off window according to the service level hours of operations, pickup, order creation cut-off time and delivery time and set the pickup start time at the ReadyAt.
The time zone used for the ReadyAt will be converted to the time zone setup for the customer account when displayed in Dispatch Science.
If no ReadyAt is provided, the order creation date-time will be used at the pickup start date-time.
Specify the Dropoff window
Enter ReadyAt and DropoffWindow sections as well as the ServicelevelId. The ServicelevelId will be used calculate the price on the order and the pickup and dropoff windows will not be calculated according to the ServicelevelId entered. If you do not include a ReadyAt, the create order time will be used as the Ready At.