Retrieve and Filter Warehouse Packages

The RetrievePackages endpoint lets you query, filter, and paginate packages stored in your Shiipp warehouse. You can narrow results by tracking number, customer details, courier, carrier, and entry date range — or export the full result set to a CSV or XLSX file for offline reporting.

Endpoint

POST /api/RetrievePackages.php

Authentication: JWT Bearer token required. Include the token in the Authorization header.

Authorization: Bearer <your_token>

Request Body

All filters are passed as JSON in the request body.

integer

default:"1"

Page number for paginated results. Starts at 1.

integer

default:"25"

Number of records to return per page. Maximum value is 10000. When export is true, this limit applies to the exported file as well.

string

Filter by tracking number using a partial match. For example, "1Z9999" matches any tracking number containing that string.

string

Filter by house number using an exact match.

string

Filter by customer user code using an exact match.

string

Filter by shipper name using a partial match (e.g., "Amazon" matches "Amazon Fulfillment").

string

Filter by customer first name using a partial match.

string

Filter by customer last name using a partial match.

string

Filter results to packages belonging to a specific courier, identified by their courier ID.

string

Filter results to packages shipped via a specific carrier, identified by their carrier ID.

string

Return only packages with an entry date on or after this date. Format: YYYY-MM-DD.

string

Return only packages with an entry date on or before this date. Format: YYYY-MM-DD.

boolean

Set to true to receive a file download instead of a JSON response. When enabled, the response will be a binary file attachment.

string

The format of the exported file. Accepted values: csv (default) or xlsx. Only relevant when export is true.

Example Request

{
  "page": 1,
  "limit": 25,
  "trackingNumber": "1Z9999",
  "entryDateFloor": "2024-01-01",
  "entryDateCeiling": "2024-01-31"
}

curl -X POST https://app.shiipp.com/api/RetrievePackages.php \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "limit": 25,
    "trackingNumber": "1Z9999",
    "entryDateFloor": "2024-01-01",
    "entryDateCeiling": "2024-01-31"
  }'

Response

Success Response

{
  "status": "success",
  "message": "Found 47 records.",
  "data": [
    {
      "package_id": "pkg-uuid",
      "tracking_number": "1Z9999999999999999",
      "house_number": "HN-00142",
      "user_code": "CUST001",
      "first_name": "Jane",
      "last_name": "Smith",
      "weight": 3.5,
      "shipper": "Amazon",
      "description": "Electronics",
      "entry_date_time": "2024-01-15 09:22:11",
      "courier_name": "Express Couriers",
      "carrier_name": "UPS",
      "manifest_number": "MAN-20240115-A3B2",
      "status": "shipped"
    }
  ],
  "meta": {
    "total_count": 47,
    "total_weight": 142.5,
    "page": 1,
    "limit": 25,
    "total_pages": 2
  }
}

Response Fields

string

Indicates the outcome of the request. Will be "success" on a valid response.

string

A human-readable summary, including the total number of records matched.

array

Array of package objects matching the supplied filters.

Show Package object fields

string

Unique UUID identifying the package.

string

The carrier tracking number. May be partially masked for courier role users when the package owner is unknown.

string

Internal house reference number assigned at intake.

string

The customer’s unique user code.

string

Customer’s first name.

string

Customer’s last name.

number

Package weight in pounds (LBS).

string

The name of the shipper or sender.

string

A brief description of the package contents.

string

Timestamp when the package was entered into the system. Format: YYYY-MM-DD HH:MM:SS.

string

Name of the courier responsible for last-mile delivery.

string

Name of the inbound carrier (e.g., UPS, FedEx).

string

The manifest number this package was grouped under.

string

Current package status (e.g., received, in_transit, shipped, delivered).

object

Pagination and aggregate metadata.

Show Meta object fields

integer

Total number of packages matching the filters across all pages.

number

Sum of weights (in LBS) for all matched packages.

integer

The current page number returned.

integer

The page size used for this response.

integer

Total number of pages available given the current limit.

File Export

Set export: true in the request body to download the filtered results as a file instead of receiving JSON. The response will include the appropriate Content-Disposition header and a binary file payload.

CSV Export
XLSX Export

{
  "export": true,
  "export_format": "csv",
  "entryDateFloor": "2024-01-01",
  "entryDateCeiling": "2024-01-31"
}

{
  "export": true,
  "export_format": "xlsx",
  "entryDateFloor": "2024-01-01",
  "entryDateCeiling": "2024-01-31"
}

The exported file includes the following columns:

Column	Description
User Code	Customer user code
Package ID	Unique package UUID
Tracking Number	Carrier tracking number
House Number	Internal house reference
First Name	Customer first name
Last Name	Customer last name
Courier	Assigned courier name
Courier Code	Short courier identifier
Carrier	Inbound carrier name
Shipper	Shipper / sender name
Weight	Package weight (LBS)
Status	Current package status
Manifest Number	Associated manifest number
Entry Date Time	Date and time of intake

Use export_format: "xlsx" when sharing reports with non-technical stakeholders — Excel files preserve column types and are easier to filter in spreadsheet applications.

Dispatch Queue Action

Sending "action": "queue_dispatch" in the request body queues the matched packages for synchronisation with your external system. You may specify packages explicitly via a package_ids array, or let the endpoint derive the set from your active filters.

{
  "action": "queue_dispatch",
  "package_ids": ["pkg-uuid-1", "pkg-uuid-2"]
}

{
  "status": "success",
  "message": "Successfully queued packages. Live sync triggered for 2 items.",
  "data": {
    "total_selected": 2
  }
}

Once queued, packages are picked up and synced automatically. No further action is required on your part after a successful queue_dispatch response.

Role-Based Access

Courier role users can only retrieve packages that belong to their own courier account. Attempts to filter by a courierID outside their account are ignored and scoped back automatically.

Tracking numbers for packages with unknown or unassigned customers are partially masked when returned to courier role users. Full tracking numbers are always visible to admin and manager roles.

Overview

Prealerts

Packages

Customers

Manifests

Billing

Courier Settings

Retrieve and Filter Warehouse Packages — Shiipp API

Endpoint

Request Body

Example Request

Response

Success Response

Response Fields

File Export

Dispatch Queue Action

Role-Based Access

​Endpoint

​Request Body

​Example Request

​Response

​Success Response

​Response Fields

​File Export

​Dispatch Queue Action

​Role-Based Access

Endpoint

Request Body

Example Request

Response

Success Response

Response Fields

File Export

Dispatch Queue Action

Role-Based Access