Skip to main content
A prealert is an advance shipment notification that tells the Shiipp warehouse a package is on its way before it physically arrives. Submitting prealerts enables the receiving team to pre-match incoming packages to customers automatically, reducing processing time and manual lookups. This endpoint is the public courier-facing entry point — it authenticates with an API key rather than a JWT token, making it suitable for automated shipping pipelines and third-party courier software.

​
Endpoint

POST /api/Prealert.php
Authentication: X-API-KEY header (your courier API key). See Authentication for how to obtain your key.
This endpoint does not accept JWT Bearer tokens. Use your courier API key exclusively. For warehouse-internal prealert creation by authenticated staff, see Manage Prealerts — POST.

​
Request Headers

​
X-API-KEY
string
required
Your courier API key, available from Courier Settings in the Shiipp dashboard.
​
Content-Type
string
required
Must be application/json.

​
Request Body

​
UserCode
string
required
The customer identifier in your Shiipp account. Maximum 100 characters. Must exactly match a user_code value in your active customer list — an unrecognised code will return a 400 error.
​
TrackingNumber
string
required
The carrier-assigned tracking number for the inbound shipment. Maximum 255 characters. A 409 conflict is returned if a prealert with this tracking number already exists under your courier account.
​
Vendor
string
The name of the shipper, retailer, or origin store (e.g. "Amazon", "Nike"). Used for display and filtering in the warehouse dashboard.
​
Description
string
A brief description of the package contents (e.g. "Electronics - Laptop"). This helps warehouse staff handle packages appropriately on arrival.
​
Reference
string
Your internal order or reference number. Stored alongside the prealert record and returned in list responses for cross-referencing with your own systems.

​
Example Request

curl -X POST https://your-domain.com/api/Prealert.php \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "UserCode": "CUST001",
    "TrackingNumber": "1Z9999999999999999",
    "Vendor": "Amazon",
    "Description": "Electronics - Laptop",
    "Reference": "ORD-2024-001"
  }'

​
Success Response

A successful submission returns HTTP 201 Created. 
{
  "status": "success",
  "message": "Pre-alert logged successfully",
  "data": {
    "prealert_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
​
status
string
Always "success" for a 201 response.
​
message
string
Human-readable confirmation message.
​
data
object
Container object for the created resource.

​
Error Reference

HTTP CodeCause
400A required field (UserCode or TrackingNumber) is missing, the request body is not valid JSON, or UserCode does not match any customer in your account
401The X-API-KEY header was not provided
403The API key is invalid, has been deactivated, or belongs to a different courier
405The request used an HTTP method other than POST
409A prealert for this TrackingNumber already exists under your courier account
500An unexpected server error occurred — log the response body and contact your Shiipp administrator
On a 409 conflict, do not re-submit the same tracking number. Retrieve the existing prealert using the GET /api/ManagePrealerts.php endpoint if you need to inspect or update it.