Submitting Advance Shipment Prealerts to Shiipp API

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.

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.

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.

string

The name of the shipper or online store (e.g. "Amazon", "Best Buy"). Displayed on the package record in the warehouse dashboard.

string

A brief description of the package contents (e.g. "Electronics - Laptop"). Helps warehouse staff handle packages appropriately.

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 Code	`status`	Cause
`400`	`error`	Missing required field (`UserCode` or `TrackingNumber`) or malformed JSON body
`401`	`error`	No API key was provided in the request
`403`	`error`	The API key is invalid, deactivated, or does not match any courier account
`405`	`error`	Request used a method other than POST
`409`	`error`	A prealert for this tracking number already exists for your courier
`500`	`error`	An 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"
  }'

const submitPrealert = async (prealert) => {
  const response = await fetch('https://your-shiipp-domain.com/api/Prealert.php', {
    method: 'POST',
    headers: {
      'X-API-KEY': process.env.SHIIPP_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(prealert),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Shiipp error ${response.status}: ${error.message}`);
  }

  return response.json();
};

// Usage
const result = await submitPrealert({
  UserCode: 'CUST001',
  TrackingNumber: '1Z9999999999999999',
  Vendor: 'Amazon',
  Description: 'Electronics - Laptop',
  Reference: 'ORD-2024-001',
});

console.log('Prealert ID:', result.data.prealert_id);

<?php
function submitPrealert(array $data): array {
    $client = new \GuzzleHttp\Client();

    $response = $client->post('https://your-shiipp-domain.com/api/Prealert.php', [
        'headers' => [
            'X-API-KEY'    => getenv('SHIIPP_API_KEY'),
            'Content-Type' => 'application/json',
        ],
        'json' => $data,
    ]);

    return json_decode($response->getBody(), true);
}

// Usage
$result = submitPrealert([
    'UserCode'       => 'CUST001',
    'TrackingNumber' => '1Z9999999999999999',
    'Vendor'         => 'Amazon',
    'Description'    => 'Electronics - Laptop',
    'Reference'      => 'ORD-2024-001',
]);

echo 'Prealert ID: ' . $result['data']['prealert_id'];

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.

Get Started

Core Concepts

Courier Integration

Guides

FAQ & Troubleshooting

Submitting Advance Shipment Prealerts to Shiipp API

Endpoint

Request Body

Example Request

Success Response

Error Responses

Code Examples

​Endpoint

​Request Body

​Example Request

​Success Response

​Error Responses

​Code Examples

Endpoint

Request Body

Example Request

Success Response

Error Responses

Code Examples