Skip to main content
The Prealert API lets you submit advance shipment notifications to Shiipp as soon as you have tracking information — even before a package leaves the origin warehouse. When a package is physically scanned at the Shiipp facility, the system checks for a matching prealert and automatically fills in the customer name, shipper, and description, reducing manual entry errors and speeding up receiving.

​
Endpoint

POST /api/Prealert.php
Authenticate every request using your API key in the X-API-KEY header. See API Keys for instructions on finding and securing your key.

​
Request Body

Send a JSON object in the request body. UserCode and TrackingNumber are required; all other fields are optional but recommended to give the warehouse team the most complete picture of an incoming package.
​
UserCode
string
required
The customer identifier from your customer list. Maximum 100 characters. Must match the normalised (uppercased, trimmed) UserCode value on the customer record — see Customer List Format for details.
​
TrackingNumber
string
required
The carrier tracking number for the package. Maximum 255 characters. Duplicate tracking numbers for the same courier are rejected with a 409 response.
​
Vendor
string
The name of the shipper or online store (e.g. "Amazon", "Best Buy"). Displayed on the package record in the warehouse dashboard.
​
Description
string
A brief description of the package contents (e.g. "Electronics - Laptop"). Helps warehouse staff handle packages appropriately.
​
Reference
string
Your internal reference number or order ID (e.g. "ORD-2024-001"). Stored against the prealert for your own reconciliation purposes.

​
Example Request

POST /api/Prealert.php HTTP/1.1
Host: your-shiipp-domain.com
X-API-KEY: your_api_key_here
Content-Type: application/json

{
  "UserCode": "CUST001",
  "TrackingNumber": "1Z9999999999999999",
  "Vendor": "Amazon",
  "Description": "Electronics - Laptop",
  "Reference": "ORD-2024-001"
}

​
Success Response

A successful submission returns HTTP 201 Created with a JSON body containing the new prealert’s internal UUID. 
{
  "status": "success",
  "message": "Pre-alert logged successfully",
  "data": {
    "prealert_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
Store the prealert_id in your own system if you want to reference or reconcile the prealert later.

​
Error Responses

HTTP CodestatusCause
400errorMissing required field (UserCode or TrackingNumber) or malformed JSON body
401errorNo API key was provided in the request
403errorThe API key is invalid, deactivated, or does not match any courier account
405errorRequest used a method other than POST
409errorA prealert for this tracking number already exists for your courier
500errorAn unexpected server error occurred — retry after a short delay
Duplicate tracking numbers for the same courier are rejected with a 409. Check whether a prealert already exists before submitting, or implement idempotent retry logic that treats 409 as a non-fatal condition.

​
Code Examples

curl -X POST https://your-shiipp-domain.com/api/Prealert.php \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "UserCode": "CUST001",
    "TrackingNumber": "1Z9999999999999999",
    "Vendor": "Amazon",
    "Description": "Electronics - Laptop",
    "Reference": "ORD-2024-001"
  }'
Submit prealerts as soon as you have the tracking number — even before the package ships. The warehouse sees prealerts immediately, so earlier submissions give staff more preparation time and reduce processing delays on arrival.