Parcels

Retrieve Parcel

GET

`/v1/parcels/:parcel`

Get a single parcel using its id.

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

const parcel = response.data;

List Parcels

Example

GET

`/v1/parcels`

When you want to retrieve multiple parcels, your data property on the result will always be an array even if you don't have any parcels.

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

const parcels = response.data; //the array of parcels
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 parcels 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 parcels in the database.

By default the page is set to 1 and the limit is 25.

If we want to query for parcels 26 - 50, we would request page 2 with a query parameter.

        const response = await fetch("https://api.packagex.io/v1/parcels?page=2&limit=25", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const items = response.data; //the array of items 25 - 50
const pagination = response.pagination; //the pagination object

Filter

You can filter parcels by unpacked, type, item_id, location_id, layout_id, statuses, special_handling_tags and updated_by. You can also filter parcels in date ranges. Supported date range filters are created_at and updated_at.

location_id - Add the ID of one of your locations to get all of the parcels currently mapped to that location. For example: location_id=loc_czhgjrk5JaVvyATPDbyURp

        const response = await fetch("https://api.packagex.io/v1/parcels?location_id=loc_hj7gjrk5JaVvyATPDbyURp&page=3", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const parcels = response.data;
const pagination = response.pagination;

item_id - Add the id of the item included in one or more of the parcel contents. For example: item_id=item_czhgjrk5JaVvyATPDbyURp

        const response = await fetch("https://api.packagex.io/v1/parcels?item_id=item_czhgjrk5JaVvyATPDbyURp&page=3", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const parcels = response.data;
const pagination = response.pagination;

layout_id - Add the id of the layout to get all parcels currently mapped to that layout. For example: layout_id=layout_czhgjrk5JaVvyATPDbyURp

        const response = await fetch("https://api.packagex.io/v1/parcels?layout_id=item_czhgjrk5JaVvyATPDbyURp&page=3", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const parcels = response.data;
const pagination = response.pagination;

unpacked - List all the parcels that have or have not been unapcked

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

const parcels = response.data;
const pagination = response.pagination;

statuses - Allows you to filter parcels that have a given status. You can pass comma separated list of statuses to filter with

        const response = await fetch("https://api.packagex.io/v1/parcels?statuses=in_use,in_storage", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const parcels = response.data;
const pagination = response.pagination;

type - Allows you to filter parcels based on type

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

const parcels = response.data;
const pagination = response.pagination;

updated_by - Allows you to filter parcels last updated by the given user or key

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

const parcels = response.data;
const pagination = response.pagination;

date filters - Allows you to filter parcels based on date ranges. Supported date filters are greater than (gt), less than (lt), greater than or equal (gte), less than or equal (lte), between inclusive (bwi), and between exclusive (bwe). Comma separated date range can be passed to bwi and bwe, other filters require a single date

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

const parcels = 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, serial_number
direction - The direction to sort. Available directions are: asc and desc

By default, parcels will be sorted by in ascending order by name, meaning they are returned alphabetically.

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

const parcels = response.data;
const pagination = response.pagination;

Search

There are times when filtering is not enough and you want to find a specific parcel by some other attribute, for example by tracking number or order number. In this case, you can do a fuzzy, typo-tolerant search of every parcel in the database.

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/parcels?search=coffee", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const parcel = response.data[0];

Retrieve Parcel

# List Parcels

# Example

# Pagination

# Filter

# Sorting