Shipments
Retrieve Shipments
Retrieving a single shipment is pretty straightforward. You'll just use the id
of shipment to get it. When you are retrieving multiple shipments, there are additional search and filter options available.
Retrieve ShipmentGET `/v1/shipments/:shipment`
Get a single shipment using its id
.
fetch("https://api.packagex.io/v1/shipments/ship_czhgjrk5JaVvyATPDbyURp", {
method: "GET",
headers: {
"PX-API-KEY": process.env.PX_API_KEY,
"Content-Type": "application/json",
},
});
List Shipments
ExampleGET `/v1/shipments`
When you want to retrieve multiple shipments, your data
property on the result will always be an array
even if you don't have any shipments. The shipments are returned in descending order, meaning the latest shipment that you just created will be first.
const response = await fetch("https://api.packagex.io/v1/shipments", {
method: "GET",
headers: {
"PX-API-KEY": process.env.PX_API_KEY,
"Content-Type": "application/json",
},
}).then((res) => res.json());
const shipments = response.data; //the array of shipments
const pagination = response.pagination; //the pagination object
Pagination
If the has_more
property on the pagination object is set to true, you know there are more shipments 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 shipments 26 - 50, we would request page 2 with a query parameter.
const response = await fetch("https://api.packagex.io/v1/shipments?page=2&limit=25", {
method: "GET",
headers: {
"PX-API-KEY": process.env.PX_API_KEY,
"Content-Type": "application/json",
},
}).then((res) => res.json());
const shipments = response.data; //the array of shipments 25 - 50
const pagination = response.pagination; //the pagination object
Filter
You can filter shipments by their sudo-statuses. There are three options to select from: completed
, outstanding
, and exception
.
You can use filters along with pagination to get more specific views of shipments, like checking every shipment that is still in transit.
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 shipments = response.data; //the array of shipments 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 shipment by some other attribute. In this case, you can do a fuzzy, typo-tolerant search of every shipment in the database. Below are the shipments 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
provider.id
provider.name
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/shipments?search=fedex", {
method: "GET",
headers: {
"PX-API-KEY": process.env.PX_API_KEY,
"Content-Type": "application/json",
},
}).then((res) => res.json());
const shipment = response.data[0];
console.log(shipment._search); //Special _search property