Deliveries
Retrieve Deliveries
Retrieving a single delivery is pretty straightforward. You'll just use the id
of the delivery to get it. When you are retrieving multiple deliveries, there are additional search and filter options available.
Retrieve DeliveryGET `/v1/deliveries/:delivery`
Get a single delivery using its id
.
fetch("https://api.packagex.io/v1/deliveries/del_czhgjrk5JaVvyATPDbyURp", {
method: "GET",
headers: {
"PX-API-KEY": process.env.PX_API_KEY,
"Content-Type": "application/json",
},
});
List Deliveries
ExampleGET `/v1/deliveries`
When you want to retrieve multiple deliveries, your data
property on the result will always be an array
even if you don't have any deliveries. The deliveries are returned in descending order, meaning the latest delivery that was created will be first.
const response = await fetch("https://api.packagex.io/v1/deliveries", {
method: "GET",
headers: {
"PX-API-KEY": process.env.PX_API_KEY,
"Content-Type": "application/json",
},
}).then((res) => res.json());
const deliveries = response.data;
const pagination = response.pagination;
Pagination
If the has_more
property on the pagination object is set to true, you know there are more deliveries in the database that have not been returned to you. The pagination object also has a page
property indicating your current offset and a limit property.
By default the page
is set to 1
and the limit
is 25
.
If we want to query for deliveries 26 - 50, we would request page 2 with a query parameter.
const response = await fetch("https://api.packagex.io/v1/deliveries?page=2&limit=25", {
method: "GET",
headers: {
"PX-API-KEY": process.env.PX_API_KEY,
"Content-Type": "application/json",
},
}).then((res) => res.json());
const deliveries = response.data; //the array of deliveries 25 - 50
const pagination = response.pagination; //the pagination object
Filter
You can filter deliveries in a number of different ways.
- filter - There are three sudo-statuses used to filter from which to select:
completed
,outstanding
, andexception
. For example, there are many statuses that indicate that something is not going to plan, including delays, package damage, etc. Filtering by exceptions will give you all of the issues without having to specify all of the statuses. - status - If you're looking for a specific status, you can use that instead. For example, if you want to view all of the deliveries that were canceled, you query ?status=canceled.
- rate_types - There are different kinds of deliveries rate types you can have on your hands. If you want to query for all customer pickups, you can query something like
?rate_types=in_person_pickup,curbside_pickup
. - location - If you work with multiple locations, you may want to filter deliveries by a specific location, which you can do by passing the location ID into the query like
?location=loc_czhgjrk5JaVvyATPDbyURp
The deliveries will automatically be sorted by the created_at
time in descending order, meaning the most recently created deliveries will be returned first.
const response = await fetch("https://api.packagex.io/v1/shipments?filter=outstanding&page=3", {
method: "GET",
headers: {
"PX-API-KEY": process.env.PX_API_KEY,
"Content-Type": "application/json",
},
}).then((res) => res.json());
const deliveries = response.data; //the array of deliveries 50 - 75 that are still in transit
const pagination = response.pagination; //the pagination object
Search
There are times when filtering is not enough and you want to find a specific delivery by some other attribute. In this case, you can do a fuzzy, typo-tolerant search of every delivery in the database. Below are the delivery properties that are supported by our full text search.
id
tracking_number
sender.name
sender.phone
sender.email
sender.address.formatted_address
recipient.name
recipient.phone
recipient.email
recipient.address.formatted_address
metadata
To search, simply provide a string to search by using the search
query param.
If you want to highlight matching search results for a frontend, we provide a special property for search-returned shipment objects called _search
which will have the matched text surrounded with <mark>
handles.
const response = await fetch("https://api.packagex.io/v1/deliveries?search=jamie%jones", {
method: "GET",
headers: {
"PX-API-KEY": process.env.PX_API_KEY,
"Content-Type": "application/json",
},
}).then((res) => res.json());
const delivery = response.data[0];
console.log(delivery._search); //Special _search property