1. Containers
  2. Retrieve Container

Containers

Retrieve Container

Retrieve detailed information about a specific container, including its current status, tracking history, and related data using the id of the container.

GET
`/v1/containers/:container`
js 
        fetch(`https://api.packagex.io/v1/containers/${container_id}`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
});

Error Handling

If the container doesn't exist or belongs to a different organization:

js 
        {
  "error": {
    "message": "Container not found",
    "status": 404
  }
}

List containers

Retrieve a paginated list of containers with comprehensive filtering, sorting, and search capabilities. The endpoint returns containers along with their associated data.

Basic Usage

GET
`/v1/containers`

Fetch a list of containers with default pagination and sorting:

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

const containers = res.data;

Pagination

The API uses page-based pagination to manage large sets of results. Each response includes a pagination object with the following information:

        {
  "pagination": {
    "page": number,         // Current page number
    "limit": number,        // Items per page
    "has_more": boolean,    // Whether more items exist
    "total_count": number   // Total number of items
  }
}

Default pagination settings:

  • Page: 1
  • Limit: 25 items per page

Example request for the second page:

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

const containers = response.data;
const pagination = response.pagination;

Filtering Options

The API supports multiple filtering parameters to help narrow down results:

  1. Location Filtering

Filter containers by their physical location:

  • location_id or location: Location identifier
  • layout_id or layout: Specific layout within a location
  • layout_path: Filter by layout hierarchy path
js 
        const response = await fetch(`https://api.packagex.io/v1/containers?location_id=loc_warehouse1&layout_id=lay_zone_a`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json"
  }
}).then((res) => res.json());

const containers = response.data;
const pagination = response.pagination;
  1. Status Filtering

Filter containers by their current status:

  • status: Single status filter
  • statuses: Comma-separated list of statuses
  • filter: Predefined status group filter
js 
        const response = await fetch(`https://api.packagex.io/v1/containers?statuses=delivered,picked_up,in_transit&filter=outstanding`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json"
  }
}).then((res) => res.json());

const containers = response.data;
const pagination = response.pagination;
  1. Metadata Filtering

Filter containers based on metadata fields using the metadata query parameter:

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

const containers = response.data;
const pagination = response.pagination;

Sorting

Control the order of returned results using sort parameters:

Parameter Type Default Description
order_by string created_at Field to sort by, supported values: created_at, updated_at, estimated_delivery_at
direction string desc Sort direction, supported values: asc, desc
js 
        const response = await fetch(`https://api.packagex.io/v1/containers?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 containers = response.data;
const pagination = response.pagination;

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

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

const containers = response.data;
const pagination = response.pagination;

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

js 
        "_search": {
  "tracking_number": "<mark>CTNR-N3J70JS-G07WFSJ</mark>",
  "relevance_score": 1,
  "query": "CTNR-N3J70JS-G07WFSJ"
}

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, estimated_delivery_at. The search functionality can be combined with other filter parameters to refine your results further.

Previous <- Update Containers
Next Delete Container ->