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.
`provider_service_level_id`	string	Filter by single service level from provider or comma-separated service levels from provider.
`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}

provider_service_level_id only support following service levels

FedEx

fedex_ground
fedex_home_delivery
ground_home_delivery
fedex_2_day
standard_overnight
priority_overnight
first_overnight
fedex_2_day_am
fedex_express_saver
express
express_international_economy
international_economy
international_priority
international_first
international_connect_plus
smart_post
same_day

UPS

ground
2nd_day_air_am
2nd_day_air
3_day_select
mail_innovations
next_day_air_saver
next_day_air_early_am
next_day_air
standard
saver
sure_post
sure_post_over_1_lb
sure_post_under_1_lb
expedited
day_definite_by_end_of_day
express
express_plus
express_saver
international_economy
international_priority
international_first
world_wide_express
world_wide_express_plus
world_wide_express_freight_midday
world_wide_express_freight
world_wide_saver
world_wide_express_expedited
world_wide_express_economy

USPS

first_class_package
first_class_mail
first_class_package_return_service
first_class_package_international
priority_mail
priority
media_mail
ground_advantage
ground_return_service
priority_mail_n_day
priority_mail_international
express
library_mail
parcel_select
parcel_select_lightweight

DHL

worldwide_express
express_envelope
express_easy
domestic_express
economy_select
break_bulk_express
break_bulk_economy
same_day

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

        const response = await fetch(`https://api.packagex.io/v1/shipments?provider_service_level_id=fedex_ground,first_overnight`, {
  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