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 Shipment

GET

`/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

Example

GET

`/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. The total_count property in pagination returns the the total number of shipments in the database.

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 sender_address_id and statuses

sender_address_id - The PackageX address ID for the shipment. For example: sender_address_id=addr_001f0416a921fc9c22f3664f71f59031f998de7c7d30b74f6c02626fc01905c6
statuses - A comma separated list of shipment statuses. Keep in mind comma's in URLs are encoded as %2C, so we recommend using your platforms native URL encoding library. For example: statuses=delivered,picked_up
rate_types - There are different kinds of 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.

        const response = await fetch(
  "https://api.packagex.io/v1/shipments?statuses=delivered,picked_up&sender_address_id=addr_11fkZ8wQzscUj9SZaX1By1&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;
const pagination = response.pagination;

Sorting

Sorting describes in what order you want your responses to come in. You can select an available property by which to sort, as well as the direction.

order_by - The property by which to sort. Available properties are: created_at , updated_at
direction - The direction to sort. Available directions are: asc and desc

By default, shipments will be sorted by in descending order, meaning the most recently created will be first.

        const response = await fetch("https://api.packagex.io/v1/shipments?order_by=created_at&direction=desc", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const shipments = response.data;
const pagination = response.pagination;

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

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.

Ordering Search Results

By default, search results are ordered by relevance. However, if you include an order_by parameter along with your search query, the results will be ordered by the specified property instead of by relevance.

Relevance Score

Relevance scores are included in the search results by default. Note that this could add up to 10ms of extra time to the request.

        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

Retrieve Shipments