Skip to main content
Shiipp gives you two authentication paths depending on your role: courier partners authenticate using a dedicated API key scoped to the public Prealert endpoint, while all other API calls use a short-lived JWT Bearer token obtained from the login endpoint. Follow the steps below to go from zero to your first successful API call.
Your Shiipp base URL (for example, https://acme.shiipp.com) is provisioned by your Shiipp administrator. Replace https://your-domain in every example below with the URL they provide.
1

Log in and obtain your Bearer token

Send a POST request to /api/login.php with your Shiipp credentials. Include "action": "login" along with your username and password. On success, the response contains an access_token you will use for all subsequent requests.Request
POST https://your-domain/api/login.php
Content-Type: application/json

{
  "action": "login",
  "username": "youruser",
  "password": "yourpassword"
}
Response
{
  "status": "success",
  "message": "Login successful",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "user": {
      "id": "42",
      "full_name": "Jane Smith",
      "username": "youruser",
      "role": "admin",
      "courier_id": null,
      "courier_code": null,
      "two_factor_enabled": false
    }
  },
  "timestamp": 1700000000
}
Copy the value of data.access_token — you will need it in the next step.
2

Attach the token to every API request

Pass the token in the Authorization header on all subsequent calls to the Shiipp API.
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Tokens are valid for 8 hours. After expiry, repeat Step 1 to obtain a fresh token. Your application should handle 401 Unauthorized responses by re-authenticating automatically.
3

Courier partners: locate your API key

If you are a courier partner, you have a separate API key that grants access to the public Prealert endpoint. You do not need a JWT token for this endpoint.
  1. Log in to the Shiipp dashboard.
  2. Navigate to Settings → Courier Settings.
  3. Copy the value shown under API Key.
Pass this key in every Prealert request using the X-API-KEY header:
X-API-KEY: your_api_key_here
4

Submit your first prealert

With your API key in hand, submit a prealert by posting shipment details to /api/Prealert.php. UserCode and TrackingNumber are required; Vendor, Description, and Reference are optional.Request
POST https://your-domain/api/Prealert.php
X-API-KEY: your_api_key_here
Content-Type: application/json

{
  "UserCode": "CUST001",
  "TrackingNumber": "1Z9999999999999999",
  "Vendor": "Amazon",
  "Description": "Electronics",
  "Reference": "ORD-2024-001"
}
Success response (HTTP 201)
{
  "status": "success",
  "message": "Pre-alert logged successfully",
  "data": {
    "prealert_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
Store the returned prealert_id to track and reference this shipment in future API calls.
Ready to go deeper with courier integrations? See the Courier Overview for the full list of endpoints, field definitions, and webhook configuration.