API Documentation

TIP API reference for integrating shipment tracking into your logistics workflow. Request and response values are illustrative; consult the pricing page and checkout for current prices.

Base URL
https://tip.live
Authentication
Most endpoints require authentication via Clerk session cookies.

Authenticated requests must include a valid session cookie from Clerk. For server-to-server communication, use the Clerk Backend API to verify sessions.

Device endpoints use API key authentication via the X-API-Key header.

Shipment API requests use a TIP API key via Authorization: Bearer <TIP_API_KEY>.

Rate Limiting

API requests are rate-limited to protect service stability. Limits are applied per IP address for public endpoints and per authenticated user for private endpoints.

  • Authenticated endpoints — 100 requests per minute
  • Public tracking endpoints — 30 requests per minute per IP
  • Device report endpoint — 10 requests per minute per device
  • Checkout / payment — 5 requests per minute

When you exceed the limit, the API returns 429 Too Many Requests. Wait for the window to reset before retrying.

Authentication
All authenticated endpoints require a valid session from Clerk.
GET/api/v1/user
Get current authenticated userAuth

Response

{
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "role": "user",
    "createdAt": "2025-01-15T10:00:00.000Z"
  }
}
GET/api/v1/user/preferences
Get notification preferencesAuth

Response

{
  "preferences": {
    "emailNotifications": true,
    "deliveryAlerts": true,
    "lowBatteryAlerts": true
  }
}
PATCH/api/v1/user/preferences
Update notification preferencesAuth

Request Body

{
  "emailNotifications": false,
  "deliveryAlerts": true
}

Response

{
  "preferences": {
    "emailNotifications": false,
    "deliveryAlerts": true,
    "lowBatteryAlerts": true
  }
}
Shipments
Manage shipments and tracking.
GET/api/v1/shipments
List user shipments (supports ?status filter)Auth

Response

{
  "shipments": [
    {
      "id": "clxyz123",
      "name": "Electronics to Berlin",
      "status": "IN_TRANSIT",
      "shareCode": "RYbEAxJF",
      "originAddress": "45 Warehouse Rd, London, UK",
      "destinationAddress": "123 Main St, Berlin, Germany",
      "createdAt": "2025-01-20T14:00:00.000Z",
      "label": {
        "id": "lbl_001",
        "deviceId": "HL-001001",
        "batteryPct": 85,
        "status": "ACTIVE"
      }
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}
POST/api/v1/shipments
Create a new shipmentAuth

Request Body

{
  "name": "Electronics to Berlin",
  "labelId": "clxyz_label_id",
  "originAddress": "45 Warehouse Rd, London, UK",
  "originLat": 51.5074,
  "originLng": -0.1278,
  "destinationAddress": "123 Main St, Berlin, Germany",
  "destinationLat": 52.5200,
  "destinationLng": 13.4050,
  "photoUrls": []
}

Response

{
  "shipment": {
    "id": "clxyz123",
    "name": "Electronics to Berlin",
    "status": "PENDING",
    "shareCode": "RYbEAxJF",
    "originAddress": "45 Warehouse Rd, London, UK",
    "destinationAddress": "123 Main St, Berlin, Germany",
    "createdAt": "2025-01-20T14:00:00.000Z"
  }
}
GET/api/v1/shipments/[id]
Get shipment details with locationsAuth

Response

{
  "shipment": {
    "id": "clxyz123",
    "name": "Electronics to Berlin",
    "status": "IN_TRANSIT",
    "shareCode": "RYbEAxJF",
    "locations": [
      {
        "id": "loc_001",
        "latitude": 51.5074,
        "longitude": -0.1278,
        "batteryPct": 92,
        "accuracyM": 15,
        "recordedAt": "2025-01-20T15:00:00.000Z"
      }
    ],
    "label": {
      "deviceId": "HL-001001",
      "batteryPct": 85
    }
  }
}
PATCH/api/v1/shipments/[id]
Update shipment detailsAuth

Request Body

{
  "name": "Updated name",
  "shareEnabled": false
}

Response

{
  "shipment": { ... }
}
DELETE/api/v1/shipments/[id]
Cancel shipment (soft delete)Auth

Response

{
  "success": true
}
Labels
Manage tracking labels.
GET/api/v1/labels
List available labels for shipment creationAuth

Response

{
  "labels": [
    {
      "id": "lbl_001",
      "deviceId": "HL-001001",
      "status": "SOLD",
      "batteryPct": 100,
      "activatedAt": null
    }
  ]
}
Orders
Label purchase and order management.
GET/api/v1/orders
List user ordersAuth

Response

{
  "orders": [
    {
      "id": "ord_abc123",
      "status": "PAID",
      "quantity": 5,
      "totalAmount": 12000,
      "currency": "USD",
      "trackingNumber": null,
      "createdAt": "2025-01-15T10:00:00.000Z"
    }
  ]
}
GET/api/v1/orders/[id]
Get order details with labelsAuth
POST/api/v1/checkout
Create Stripe checkout sessionAuth

Request Body

{
  "packType": "team",
  "shippingAddress": {
    "name": "Jane Doe",
    "line1": "123 Main St",
    "city": "London",
    "state": "",
    "postalCode": "SW1A 1AA",
    "country": "GB"
  }
}

Response

{
  "url": "https://checkout.stripe.com/c/pay/cs_...",
  "sessionId": "cs_live_..."
}
Shipment API (API keys)
Stable v1 server-to-server shipment endpoints. Authenticate with a TIP API key.
GET/api/public/v1/cargo?status=IN_TRANSIT&query=TIP-010&limit=20&offset=0
List or resolve shipments by ID, exact name, or label IDAuth

Use Authorization: Bearer <TIP_API_KEY>. Existing updatedSince behavior is unchanged; locationUpdatedSince filters by tracking-event time.

GET/api/public/v1/cargo/summary?scope=active&page=1&limit=5
Get deterministic fleet totals and a paginated listAuth

Response

{
  "totals": {
    "total": 14,
    "byStatus": {
      "PENDING": 1,
      "IN_TRANSIT": 12,
      "DELIVERED": 0,
      "CANCELLED": 1
    },
    "attention": 2
  },
  "staleAfterHours": 48,
  "data": [ ... ],
  "pagination": { "total": 12, "page": 1, "limit": 5, "hasMore": true }
}
GET/api/public/v1/cargo/[id]
Get shipment details and its latest valid locationAuth
GET/api/public/v1/cargo/[id]/route
Get a normalized route summary without repetitive tracking pingsAuth

Response

{
  "shipment": {
    "id": "shipment_id",
    "labelId": "002492622",
    "name": "Hk test",
    "status": "IN_TRANSIT"
  },
  "currentLocation": { "city": "Hong Kong", "countryCode": "HK", "lat": 22.31, "lng": 114.16 },
  "lastUpdate": "2026-08-06T00:27:00.000Z",
  "isStale": false,
  "routeSegments": [
    { "location": { "city": "Warsaw", "countryCode": "PL" }, "firstSeen": "...", "lastSeen": "...", "signalCount": 12 },
    { "location": { "city": "Beijing", "countryCode": "CN" }, "firstSeen": "...", "lastSeen": "...", "signalCount": 1 },
    { "location": { "city": "Hong Kong", "countryCode": "HK" }, "firstSeen": "...", "lastSeen": "...", "signalCount": 40 }
  ],
  "locationCount": 3,
  "countryCount": 3
}
GET/api/public/v1/cargo/[id]/locations?limit=50&offset=0
Get raw tracking events for technical diagnosticsAuth
Public Tracking
Public endpoints for shipment tracking. No authentication required.
GET/api/v1/track/[code]
Get public tracking data by share code

Response

{
  "shipment": {
    "name": "Electronics to Berlin",
    "status": "IN_TRANSIT",
    "destinationAddress": "Berlin, Germany",
    "locations": [
      {
        "latitude": 52.3676,
        "longitude": 9.7389,
        "batteryPct": 78,
        "recordedAt": "2025-01-21T08:30:00.000Z"
      }
    ],
    "label": {
      "deviceId": "HL-001001",
      "batteryPct": 78
    }
  }
}
Delivery Confirmation
Public endpoint for consignee delivery confirmation.
POST/api/v1/track/[code]/confirm
Confirm delivery (by recipient)

Request Body

{
  "receiverName": "John Smith",
  "notes": "Received in good condition"
}

Response

{
  "success": true,
  "message": "Delivery confirmed"
}
Device Integration
Endpoints for device communication.
POST/api/v1/device/report
Receive location reports from devices

Requires device API key in X-API-Key header

Request Body

{
  "deviceId": "HL-001001",
  "latitude": 51.5074,
  "longitude": -0.1278,
  "batteryPct": 85,
  "accuracyM": 10,
  "recordedAt": "2025-01-20T15:00:00.000Z"
}

Response

{
  "success": true,
  "eventId": "evt_abc123"
}
POST/api/v1/device/activate
Activate a label after QR scanAuth

Request Body

{
  "labelId": "lbl_001"
}

Response

{
  "label": {
    "id": "lbl_001",
    "status": "ACTIVE",
    "activatedAt": "2025-01-20T14:30:00.000Z"
  }
}
Statistics
Dashboard statistics.
GET/api/v1/stats
Get dashboard statisticsAuth

Response

{
  "activeShipments": 3,
  "totalLabels": 10,
  "deliveredThisMonth": 5,
  "lowBatteryLabels": 1
}
Account
Account management and GDPR compliance.
GET/api/v1/user/export
Export all user data (GDPR)Auth

Response

{
  "user": { ... },
  "orders": [ ... ],
  "shipments": [ ... ],
  "exportedAt": "2025-01-20T10:00:00.000Z"
}
DELETE/api/v1/user/delete
Delete account and all data (GDPR)Auth

Request Body

{
  "confirm": "DELETE"
}

Response

{
  "success": true,
  "message": "Account and all associated data have been permanently deleted."
}
Health
Service health and readiness checks.
GET/api/health
Health check with dependency status

Response

{
  "status": "healthy",
  "timestamp": "2025-01-20T10:00:00.000Z",
  "dependencies": {
    "database": "connected",
    "stripe": "configured",
    "clerk": "configured"
  }
}
GET/api/health/ready
Readiness check for deployments

Response

{
  "ready": true
}
Webhooks
Webhook endpoints for third-party services.
POST/api/webhooks/clerk
Clerk user sync webhook

Requires Clerk signature verification

POST/api/webhooks/stripe
Stripe payment webhook

Requires Stripe signature verification

Error Responses

All error responses follow a consistent JSON format:

{
  "error": "Error message describing what went wrong",
  "details": {           // Optional — present on validation errors
    "fieldErrors": {
      "name": ["Shipment name is required"]
    }
  }
}

Common HTTP Status Codes:

  • 200 — Success
  • 201 — Created (new resource)
  • 400 — Bad Request (validation error or missing confirmation)
  • 401 — Unauthorized (missing or invalid auth)
  • 403 — Forbidden (insufficient permissions)
  • 404 — Not Found
  • 429 — Too Many Requests (rate limited)
  • 500 — Internal Server Error