Shipments

Retrieve Shipments

To access shipment information, you may retrieve either individual or multiple shipment records:

Accessing a single shipment record requires only the shipment's unique identifier (id).
When accessing multiple shipments simultaneously, the system provides enhanced functionality through additional search parameters and filtering options.

Retrieve Shipment

This endpoint allows you to retrieve detailed information about a specific shipment using its unique identifier. The response includes comprehensive shipment details along with related information such as tracking updates, addresses, etc.

GET

`/v1/shipments/:shipment`

Request Example

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

const shipment = response.data;

List Shipments

This endpoint enables you to retrieve multiple shipments with comprehensive filtering, sorting, and search capabilities. The system provides flexible query options to help you find exactly the shipments you need.

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.

Basic Usage

        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;

Filtering

The API supports comprehensive filtering of shipments through query parameters.

Parameter	Type	Description
`status`	string	Filter by single status or comma-separated statuses.
`type`	string	Filter by shipment type.
`filter`	string	Filter by predefined groups. Can either be `completed`, `outstanding`, `exception`
`tags`	string	Filter by tags.
`layout_id` OR `layout`	string	Filter by layout identifier.
`location_id` OR `location`	string	Filter by location identifier.
`layout_path`	string	Filter by layout path.
`sender_contact_id` OR `sender_contact`	string	Filter by sender contact id.
`recipient_contact_id` OR `recipient_contact`	string	Filter by recipient contact id.
`container_id` OR `container`	string	Filter by container id.
`provider_id` OR `provider`	string	Filter by single provider or comma-separated providers.
`service_level` OR `service_levels`	string	Filter by single service level or comma-separated service levels.
`rate_type` OR `rate_types`	string	Filter by single rate type or comma-separated rate types.
`sender_address_id`	string	Filter by sender address id.
`recipient_address_id`	string	Filter by recipient address id.
`user_id` OR `user`	string	Filter by user id.
`created_at`	epoch timestamp OR Date	Filter by creation timestamp.
`pickup_at`	epoch timestamp OR Date	Filter by pickup_at timestamp.
`estimated_delivery_at`	epoch timestamp OR Date	Filter by estimated_delivery_at timestamp.
`rates_generated_at`	epoch timestamp OR Date	Filter by rates_generated_at timestamp.
`start_at`	epoch timestamp OR Date	When the `created_at` parameter is not specified, you may utilize the `start_at` parameter as an alternative filtering mechanism. This parameter automatically retrieves all shipment records with a creation timestamp greater than or equal to the specified date value.

created_at, pickup_at, estimated_delivery_at, rates_generated_at and start_at support the following operators:

eq: Equals
!eq: Not equals
gt: Greater than
gte: Greater than or equal
lt: Less than
lte: Less than or equal
bwe: Between exclusive (requires comma-separated dates)
bwi: Between inclusive (requires comma-separated dates)
in: In list of dates (requires comma-separated dates)
!in: Not in list of dates (requires comma-separated dates)

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

Filtering Examples

Filtering by status:

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

const shipments = response.data;

Filtering by type:

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

const shipments = response.data;

Filtering by filter:

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

const shipments = response.data;

Filtering by tags:

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

const shipments = response.data;

Filtering by layout_id:

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

const shipments = response.data;

Filtering by location_id:

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

const shipments = response.data;

Filtering by layout_path:

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

const shipments = response.data;

Filtering by sender_contact_id:

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

const shipments = response.data;

Filtering by recipient_contact_id:

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

const shipments = response.data;

Filtering by container_id:

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

const shipments = response.data;

Filtering by provider_id:

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

const shipments = response.data;

Filtering by service_level:

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

const shipments = response.data;

Filtering by rate_type:

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

const shipments = response.data;

Filtering by sender_address_id:

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

const shipments = response.data;

Filtering by recipient_address_id:

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

const shipments = response.data;

Filtering by user_id:

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

const shipments = response.data;

Filtering by created_at:

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

const shipments = response.data;

Filtering by pickup_at:

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

const shipments = response.data;

Filtering by estimated_delivery_at:

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

const shipments = response.data;

Filtering by rates_generated_at:

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

const shipments = response.data;

Filtering by start_at:

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

const shipments = response.data;

Pagination

The system uses page-based pagination with these properties:

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

To retrieve the next page of results:

Example with pagination:

        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;
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`, `estimated_delivery_at`, `pickup_at`, `_relevance`, `_similarity`
`direction`	string	`asc`	Sort direction, supported values: `asc`, `desc`

By default, shipments will be sorted by in ascending order.

        const response = await fetch("https://api.packagex.io/v1/shipments?order_by=estimated_delivery_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

The API provides advanced full-text search capabilities through the search parameter, allowing you to filter specific shipments using fuzzy, typo-tolerant matching across multiple fields.

Below are the properties that are supported by our full text search.

Searchable Properties

search.provider: the provider name
search.barcode_values
search.order_number
search.recipient: the recipient name, nickname and email
search.sender: the sender name, nickname and email
search.tracking_number
search.metadata: the custom metadata of the shipment

        const response = await fetch("https://api.packagex.io/v1/shipments?search=ups", {
  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;

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

        "_search": {
  "order_number": null,
  "barcode_values": [],
  "tracking_number": "1ZXXXXXXXXXXXXXXXX",
  "sender_name": "john",
  "sender_email": "john@packagex.xyz",
  "recipient_name": "johnny",
  "recipient_email": "johnny@packagex.xyz",
  "provider_name": "<mark>UPS</mark>",
  "relevance_score": 0.8,
  "query": "ups"
}

To perform a general search, simply provide a string to search by using the search query param. The results will be order by the most relevant first. To perform a targeted search, or a mixture of targeted search and general search, or to use various modifiers to boost a particular field, refer to the general section on search, while using the searchable properties provided above

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.

We also provide a _searchV2 object that has a searchV2.scores property for scores and searchV2.shipment property with all matches highlighted with <mark> handles; this object has the same structure as the shipment object, except only those properties are present where there are highlights.

Ordering Search Results

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 and pickup_at or the search score like _similarity and _relevance. The search functionality can be combined with other filter parameters to refine your results further.

Retrieve Shipments