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

# Example

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 by location_id, statuses, rate_types and recipient_contact_id.

• location_id - Add the ID of one of your locations to get all of the deliveries currently mapped to that location. For example: location_id=loc_czhgjrk5JaVvyATPDbyURp
• 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.
• recipient_contact_id - This will let you filter all deliveries where the recipient matches the selected contact ID. For example: recipient_contact_id=ctct_rEMzyCyxJzuBzN4LyurAJV

        const response = await fetch(
  "https://api.packagex.io/v1/deliveries?location_id=loc_czhgjrk5JaVvyATPDbyURp&statuses=delivered,picked_up&rate_types=in_person_pickup,curbside_pickup&recipient_contact_id=ctct_rEMzyCyxJzuBzN4LyurAJV&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

      

# 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
• direction - The direction to sort. Available directions are: asc and desc

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

        const response = await fetch("https://api.packagex.io/v1/deliveries?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 deliveries = response.data;
const pagination = response.pagination;

      

# 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