User
A User represents an individual Business or Organization.
Location
A Location represents a physical address.
Delivery
A Delivery represents all data related to a single point-to-point transport of a package or packages, where the the starting point is the Origin and the ending point is the Destination.
Data Parameters
These parameters are set or controlled by the API. Any values input for these parameters will be ignored.
|
Name |
Type |
Description |
|
id |
number |
The unique delivery identifier generated by the API when a delivery is created. |
|
status |
string |
The current status of the Delivery. Defaults to “received”. Delivery Status List. |
|
deliveryType |
string |
The type of Delivery. Delivery Type List. |
|
batchId |
string |
If the Delivery is part of a Batch, denotes the Batch’s id. Contains letters, numbers and dashes. |
|
routeOrder |
number |
If the Delivery is part of a Batch, denotes the sequential order related to that Batch in which this Delivery will be handled. |
|
distance |
number |
The determined distance for this Delivery in miles, precision of 0.1 miles. |
|
deliveryRate |
number |
The calculated rate based on distance. The formula for deliveryRate is 599 for any distance of five miles or less, with an additional 150 * (distance - 5) over five miles. Monetary Data Format |
|
deliveryFee |
number |
The calculated fee based on the number of packages and the User’s subscription tier. Monetary Data Format |
|
trackingNumber |
string |
A generated unique identifier for referencing this Delivery. Will appear on the Delivery label. |
|
createdAt |
number |
Timestamp of when this Delivery was created. |
|
minimumAge |
number |
Set by the API based on the User’s category. |
|
confirmationPhoto |
string |
The URL of the photo taken by the Driver upon completion of the Delivery. |
|
originTrackingURL |
string |
The tracking link for the portion of the Delivery from the Driver’s location to the origin, or in the case of a Batch Delivery, to the initial origin. |
|
destinationTrackingURL |
string |
The tracking link for the portion of the Delivery from the origin to the destination. |
Input Parameters
The parameters for validating or creating a Delivery.
|
orderNumber |
string |
API: Required A User defined free form string for use as identification for the User and their Delivery recipients. Will appear prominently on the Delivery label. |
|
numPackages |
number |
API: Required The number of individual items being delivered. Must be a positive whole number. |
|
totalWeight |
number |
API: Depreciated The total weight in pounds of all packages for this Delivery. Must be a positive whole number. Maximum weight of 50lbs per Delivery. |
|
scheduledDateTime |
number |
API: Optional A timestamp for when this Delivery will be sent into our dispatch system. For a Batch Delivery, input the scheduled date time at the request level rather than on each Delivery. Timestamp Data Format |
|
test |
boolean |
API: Optional, defaults to false Denotes the Delivery as a test, preventing any charges and the dispatching of a driver. |
|
destinationName |
string |
API: Required The name of the Delivery Recipient. |
|
destinationPhone |
number string |
API: Required The phone number of the Delivery Recipient. Phone Data Format |
|
destinationEmail |
string |
API: Optional The email of the Delivery Recipient. If set, the Recipient will receive an email notification when their Delivery is completed, which will include the confirmationPhoto, if applicable. |
|
destinationAddress1 |
string |
API: Required The street address of the Delivery destination. Street Address Format |
|
destinationAddress2 |
string |
API: Optional The apartment, suite number, etc. of the Delivery destination. |
|
destinationCity |
string |
API: Required The city of the Delivery destination. |
|
destinationState |
string |
API: Required The state of the Delivery destination. |
|
destinationZip |
string number |
API: Required The zip code of the Delivery destination. Zip Code Format |
|
destinationNote |
string |
API: Optional Free form notes related to the Delivery destination. Use this for things like the customer asked for the Driver to call upon arrival. |
|
originAddress1 |
string |
API: Optional The street address of the Delivery origin. If not provided, the User’s default Location will be used. For a Delivery Type of ‘batchdestination’, this value will be determined from the previous Delivery’s destination. Street Address Format |
|
originAddress2 |
string |
API: Optional The apartment, suite number, etc. of the Delivery origin. |
|
originCity |
string |
API: Optional The city of the Delivery origin. If not provided, the User’s default Location will be used. For a Delivery Type of ‘batchdestination’, this value will be determined from the previous Delivery’s destination. |
|
originState |
string |
API: Optional The state of the Delivery origin. |
|
originZip |
string number |
API: Optional The zip code of the Delivery origin. If not provided, the User’s default Location will be used. For a Delivery Type of ‘batchdestination’, this value will be determined from the previous Delivery’s destination. Zip Code Format |
|
originNote |
string |
API: Optional Free form notes related to the Delivery origin. Use this for things like telling the Driver to pick up Deliveries in the back of the store, or to call first before returning an attempted Delivery. |
|
gratuity |
number |
API: Optional Driver’s tip, 100% goes directly to the Driver. Monetary Data Format |
Delivery Type
|
Name |
Description |
|
standard |
A single point to point Delivery |
|
batchorigin |
The Delivery within a Batch Delivery where the initial Location is the origin |
|
batchdestination |
A Delivery within a Batch Delivery where the origin is the previous Delivery’s destination |
Delivery Status
|
Name |
Description |
|
received |
The default Delivery Status. The Delivery request has been received by the API. |
|
assigned |
The Delivery has been dispatched and a Driver has been assigned. |
|
started |
The Driver is en route to the Origin. |
|
pickedup |
All packages have been picked up by the Driver at the Origin. |
|
transit |
The Driver is en route to the Destination. |
|
completed |
All packages have been delivered by the Driver and any requirements such as taking a photo, capturing a signature, or verifying age have been completed successfully. |
|
failed |
A User related issue caused the Driver to be unable to pick up the packages at the Origin. |
|
undeliverable |
An issue caused the Driver to be unable to deliver the packages to the Destination. In this case the Driver will return the packages to the Origin or the Batch Delivery Origin and the User will incur an additional charge. |
|
cancelled |
A general issue occurred and the Delivery has been cancelled. |
Batch Delivery
A Batch Delivery comprises between 2 and 49 Deliveries whereby the Origins and Destinations are chained together in an optimized fashion to create a continuous route.
Batch
|
Name |
Type |
Description |
|
origin |
The initial origin for this Batch - where the Driver will pick up all of the packages. |
|
|
distance |
number |
The total determined distance for this Batch in miles, precision of 0.1 miles. |
|
deliveryRate |
number |
The total calculated rate based on distance for the Batch. The formula for deliveryRate is 599 for any distance of five miles or less, with an additional 150 * (distance - 5) over five miles. Monetary Data Format |
|
deliveryFee |
number |
The total calculated fee based on the number of packages for this Batch and the User’s subscription tier. Monetary Data Format |
|
numPackages |
number |
The total number of packages being Delivered in this Batch. |
|
deliveries |
Delivery[] |
The list of Delivery objects associated with this Batch. |
|
total |
number |
The total of the deliveryRate, deliveryFee and gratuity for this Batch. |
|
gratuity |
number |
Total Driver’s tip across all Deliveries in the Batch. Monetary Data Format |
Endpoints
The base URL for the Trellus API is https://api.bytrellus.com/v1
For the sandbox environment, the base URL is https://testapi.bytrellus.com/v1
Delivery
Delivery endpoints will return the Delivery object upon successful request.
Example Delivery Response:
{
"success": true,
"delivery": {
"id": 99999,
"status": "received",
"deliveryType": "standard",
...
}
}
Get
Retrieve a single Delivery by id
|
Method |
GET |
|
Endpoint |
{baseURL}/delivery/get/:id |
|
Response |
success: boolean delivery: Delivery deliveryErrors: Error[] |
Label
Download a single Delivery Label by Delivery Id
|
Method |
GET |
|
Endpoint |
{baseURL}/delivery/label/:id |
|
Response |
Streamed PDF file download |
Validate
Run Delivery Input through the process of validation without actually submitting the Delivery to be saved. Will not return an id, or dispatch-related parameters such as originTrackingURL.
|
Method |
POST |
|
Endpoint |
{baseURL}/delivery/validate |
|
Body |
|
|
Response |
success: boolean delivery: Delivery deliveryErrors: Error[] |
Create
Create a Delivery.
|
Method |
POST |
|
Endpoint |
{baseURL}/delivery/create |
|
Body |
|
|
Response |
success: boolean delivery: Delivery deliveryErrors: Error[] |
Batch
Since a Batch Delivery is just a set of Delivery objects, Batch related requests will require a list of Delivery Input objects.
Note: For (optionally) scheduling a Batch Delivery, the scheduledDateTime is set at the request level, rather than being repeated on each Delivery. It’s not currently possible to schedule individual Deliveries within a Batch for different dates or times.
Example Batch Delivery Request Body:
{
"scheduledDateTime": 1621990283129,
"deliveries": [
{
"orderNumber": 1234567,
"destinationName": "John Smith",
...
},
{
"orderNumber": 1234568,
"destinationName": "Jane Tailor",
...
},
...
}
}
Batch Delivery endpoints get and create will return the list of Deliveries within the Batch upon successful request. The validate endpoint includes a Delivery Route rather than just a Delivery list.
Example Batch Delivery Response:
{
"success": true,
"deliveries": [
{
"id": 9999998,
"status": "received",
...
},
{
"id": 9999999,
"status": "received",
...
},
...
}
}
Get
Retrieve a Batch Delivery by id
|
Method |
GET |
|
Endpoint |
{baseURL}/batch/get/:id |
|
Response |
success: boolean batch: Batch deliveries: Delivery[] Depreciated deliveryErrors: Error[] |
Label
Download all Delivery Labels within a Batch by Batch Id
|
Method |
GET |
|
Endpoint |
{baseURL}/batch/label/:id |
|
Response |
Streamed PDF file download, each page representing a single Delivery Label |
Validate
Run Batch Delivery Input through the process of validation without actually submitting the Batch Delivery to be saved. Will not return any id parameters, or dispatch related parameters such as originTrackingURL.
|
Method |
POST |
|
Endpoint |
{baseURL}/batch/validate |
|
Body |
scheduledDateTime: timestamp deliveries: DeliveryInput[] |
|
Response |
success: boolean batch: Batch route: DeliveryRoute Depreciated deliveryErrors: Error[] |
Create
Create a Batch Delivery.
|
Method |
POST |
|
Endpoint |
{baseURL}/batch/create |
|
Body |
scheduledDateTime: timestamp deliveries: DeliveryInput[] |
|
Body |
success: boolean batch: Batch deliveries: Delivery[] Depreciated deliveryErrors: Error[] |