1. Deliveries
  2. Retrieve Deliveries

Deliveries

Retrieve Deliveries

Retrieving a single delivery is pretty straightforward. You'll just use the id of delivery to get it. When you are retrieving multiple deliveries, there are additional search and filter options available.

Retrieve Single Delivery

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

GET
`/v1/deliveries/:delivery`

Request Example

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

const delivery = response.data;

List Deliveries

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

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

GET
`/v1/deliveries`

Basic Usage

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

const deliveries = response.data;

Filtering

The API supports comprehensive filtering of deliveries through query parameters.

Parameter Type Description
status string Filter by single status or comma-separated statuses.
type string Filter by delivery 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 delivery 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:
js 
        const response = await fetch(`https://api.packagex.io/v1/deliveries?status=delivered,in_transit`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

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

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

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

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

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

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

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

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

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

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

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

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

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

const deliveries = response.data;

Pagination

The system uses page-based pagination with these properties:

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

To retrieve the next page of results:

Example with pagination:

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

const deliveries = 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, deliveries will be sorted by in ascending order.

js 
        const response = await fetch("https://api.packagex.io/v1/deliveries?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 deliveries = response.data;
const pagination = response.pagination;

The API provides advanced full-text search capabilities through the search parameter, allowing you to filter specific deliveries 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 delivery
js 
        const response = await fetch("https://api.packagex.io/v1/deliveries?search=ups", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const deliveries = response.data;
const pagination = response.pagination;

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

js 
        "_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 delivery 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 delivery 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.

Previous <- Create and Update Deliveries
Next Groups Overview ->