Skip to main content
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.
​
page
integer
default:"1"
Page number for paginated results. Starts at 1.
​
limit
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.
​
trackingNumber
string
Filter by tracking number using a partial match. For example, "1Z9999" matches any tracking number containing that string.
​
houseNumber
string
Filter by house number using an exact match.
​
userCode
string
Filter by customer user code using an exact match.
​
shipper
string
Filter by shipper name using a partial match (e.g., "Amazon" matches "Amazon Fulfillment").
​
firstName
string
Filter by customer first name using a partial match.
​
lastName
string
Filter by customer last name using a partial match.
​
courierID
string
Filter results to packages belonging to a specific courier, identified by their courier ID.
​
carrierID
string
Filter results to packages shipped via a specific carrier, identified by their carrier ID.
​
entryDateFloor
string
Return only packages with an entry date on or after this date. Format: YYYY-MM-DD.
​
entryDateCeiling
string
Return only packages with an entry date on or before this date. Format: YYYY-MM-DD.
​
export
boolean
Set to true to receive a file download instead of a JSON response. When enabled, the response will be a binary file attachment.
​
export_format
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"
}

​
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

​
status
string
Indicates the outcome of the request. Will be "success" on a valid response.
​
message
string
A human-readable summary, including the total number of records matched.
​
data
array
Array of package objects matching the supplied filters.
​
meta
object
Pagination and aggregate metadata.

​
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. 
{
  "export": true,
  "export_format": "csv",
  "entryDateFloor": "2024-01-01",
  "entryDateCeiling": "2024-01-31"
}
The exported file includes the following columns:
ColumnDescription
User CodeCustomer user code
Package IDUnique package UUID
Tracking NumberCarrier tracking number
House NumberInternal house reference
First NameCustomer first name
Last NameCustomer last name
CourierAssigned courier name
Courier CodeShort courier identifier
CarrierInbound carrier name
ShipperShipper / sender name
WeightPackage weight (LBS)
StatusCurrent package status
Manifest NumberAssociated manifest number
Entry Date TimeDate 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.