1. Parcels
  2. Retrieve Parcel

Parcels

Retrieve Parcel

GET
`/v1/parcels/:parcel`

Retrieves detailed information about a specific parcel using its id.

Path Parameters

parcel_id (string, required): The unique identifier of the parcel to retrieve.

js 
        const response = await fetch(`https://api.packagex.io/v1/parcels/${parcel_id}`, {
  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

GET
`/v1/parcels`

Retrieves a paginated list of parcels with comprehensive filtering, sorting, and search capabilities. This endpoint provides flexible querying options to find parcels based on various criteria.

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

Filtering

The API supports comprehensive filtering of parcels through query parameters. Multiple filters can be combined to refine your results.

Parameter Type Description
location_id string Filter by location identifier
layout_id string Filter by layout identifier
item_id string Filter by item contained in parcels
unpacked boolean Filter by unpacking status
type string Filter by parcel type
statuses string[] Comma-separated list of parcel statuses
special_handling_tags string[] Comma-separated list of special handling tags
created_by string Filter by creator identifier
updated_by string Filter by last modifier identifier
created_at string Filter by creation timestamp
updated_at string Filter by last modification timestamp

Both created_at and updated_at support the following operators:

  • gt: Greater than
  • lt: Less than
  • gte: Greater than or equal to
  • lte: Less than or equal to
  • bwi: Between inclusive (requires comma-separated dates)
  • bwe: Between exclusive (requires comma-separated dates)

Format: {field}={operator}:{date} or {field}={operator}:{date1},{date2}

Filtering Examples

  • Filtering by location_id and statuses:
js 
        const response = await fetch(
  `https://api.packagex.io/v1/parcels?location_id=loc_abc123&statuses=inbound_transit,delivered`,
  {
    method: "GET",
    headers: {
      "PX-API-KEY": process.env.PX_API_KEY,
      "Content-Type": "application/json",
    }
  }
).then((res) => res.json());

const parcels = response.data;
  • Filtering by created_at:
js 
        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;
  • Filtering by item_id:
js 
        const response = await fetch("https://api.packagex.io/v1/parcels?item_id=item_czhgjrk5JaVvyATPDbyURp", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

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

const parcels = response.data;
  • Filtering by unpacked:
js 
        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;

Pagination

The response includes a pagination object with the following properties:

  • has_more - Indicates if there are more parcels available
  • page - Current page number (default: 1)
  • limit - Number of results per page (default: 25)
  • total_count - Total number of parcels in the database.

To retrieve the next page of results:

js 
        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 parcels = response.data;
const pagination = response.pagination;

Sorting

Control the order of results using:

Parameter Type Default Description
order_by string created_at Field to sort by, supported values: created_at, updated_at
direction string asc Sort direction, supported values: asc, desc

If no sorting parameter is specified, the system defaults to sorting by created_at in ascending order asc

Example with sorting:

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

const parcels = response.data;

The API provides advanced full-text search capabilities through the search parameter, allowing you to search parcels using fuzzy, typo-tolerant matching across multiple fields. The search functionality examines key parcel properties including:

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

const parcels = response.data;

Each parcel in the search results includes a special _search object that provides detailed information about the match:

js 
        "_search": {
  "tracking_number": "<mark>PKGX</mark>-123456",
  "container_number": "12313123",
  "relevance_score": 0.8,
  "query": "PKGX"
}

The _search object includes highlighted matches using <mark> tags, making it easy to emphasize matching text in user interfaces. It also provides a relevance score between 0 and 1, where higher values indicate better matches.

By default, search results are ordered by relevance score to show the best matches first. However, you can override this by specifying an order_by parameter to sort by other fields like created_at, updated_at. The search functionality can be combined with other filter parameters to refine your results further.

Previous <- Create & Update Parcel
Next Imports Overview ->