LateShipment.com API Documentation - Delivery Experience Management

Modified on: Fri, 18 Jul, 2025 at 3:50 AM

LateShipment.com API Documentation

Welcome to the LateShipment.com API! This documentation provides all the information you need to interact with our Delivery Experience Management (DEM) platform programmatically. You can track shipments, manage claims, and set up webhooks for real-time event notifications.

The base URL for all API endpoints is: https://api.lateshipment.com

Authentication

Authentication is handled via request headers. You must include your account's admin email and API key in every request.

Header	Description
`email`	The email address of your LateShipment.com account administrator.
`x-auth-key`	Your unique API key. You can find this in your LateShipment.com account under My Profile.

Example Authentication Header:

email: "admin@yourcompany.com"
x-auth-key: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

1. Order & Shipment Management

Endpoints for retrieving shipment details, tracking information, and history.

1.1 Get Shipment Details & Tracking Status

Retrieves comprehensive details and the latest tracking status for a single shipment using its tracking number.

Method: GET
Endpoint: /v1/shipments/{tracking_number}

Parameters:

Type	Name	Description
Path	`tracking_number`	The unique carrier tracking number for the shipment.

Example Request:

curl -X GET "https://api.lateshipment.com/v1/shipments/1Z999AA10123456784" \
     -H "email: admin@yourcompany.com" \
     -H "x-auth-key: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Success Response (200 OK):

{
  "status": "success",
  "data": {
    "tracking_number": "1Z999AA10123456784",
    "order_id": "ORD-2024-001",
    "carrier": "UPS",
    "service": "UPS Ground",
    "status_details": {
        "status": "In Transit",
        "status_description": "Your package is on its way.",
        "current_location": "Louisville, KY, United States",
        "estimated_delivery_date": "2024-07-22T18:00:00Z"
    },
    "customer_details": {
        "name": "Jane Doe",
        "email": "jane.doe@example.com",
        "phone": "555-123-4567",
        "shipping_address": {
            "street": "123 Main St",
            "city": "Anytown",
            "state": "CA",
            "zip_code": "12345",
            "country": "USA"
        }
    },
    "order_contents": [
        {
            "sku": "ITEM-VASE-01",
            "name": "Hand-painted Ceramic Vase",
            "quantity": 1,
            "price": 49.99
        },
        {
            "sku": "ITEM-MUG-04",
            "name": "Artisan Coffee Mug",
            "quantity": 2,
            "price": 15.00
        }
    ],
    "package_information": {
        "weight": "5.2 lbs",
        "dimensions": "12x10x8 in",
        "box_type": "Custom"
    },
    "events": [
      {
        "timestamp": "2024-07-18T10:30:00Z",
        "location": "Louisville, KY, United States",
        "description": "Departure Scan"
      },
      {
        "timestamp": "2024-07-17T22:15:00Z",
        "location": "Dallas, TX, United States",
        "description": "Origin Scan"
      }
    ]
  }
}

Error Response (404 Not Found):

{
  "status": "error",
  "message": "Shipment with tracking number 1Z999AA10123456784 not found."
}

1.2 Get Status by Order ID or Tracking Number

Retrieves the current status of a shipment using either your internal order ID or the carrier's tracking number.

Method: GET
Endpoint: /v1/shipments/status

Parameters:

Type	Name	Description
Query	`order_id`	(Optional) The order ID associated with the shipment.
Query	`tracking_number`	(Optional) The carrier tracking number.

Example Request:

curl -X GET "https://api.lateshipment.com/v1/shipments/status?tracking_number=1Z999AA10123456784" \
     -H "email: admin@yourcompany.com" \
     -H "x-auth-key: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Success Response (200 OK):

{
  "status": "success",
  "data": {
    "tracking_number": "1Z999AA10123456784",
    "status": "In Transit",
    "estimated_delivery_date": "2024-07-22T18:00:00Z"
  }
}

1.3 Bulk Shipment Status Lookup

Retrieves the status for multiple shipments in a single API call.

Method: POST
Endpoint: /v1/shipments/status/bulk

Payload Format:

{
  "tracking_numbers": [
    "1Z999AA10123456784",
    "9405511899561234567890",
    "781234567890"
  ]
}

Example Request:

curl -X POST "https://api.lateshipment.com/v1/shipments/status/bulk" \
     -H "Content-Type: application/json" \
     -H "email: admin@yourcompany.com" \
     -H "x-auth-key: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
     -d '{
       "tracking_numbers": [
         "1Z999AA10123456784",
         "9405511899561234567890"
       ]
     }'

Success Response (200 OK):

{
  "status": "success",
  "data": [
    {
      "tracking_number": "1Z999AA10123456784",
      "status": "In Transit"
    },
    {
      "tracking_number": "9405511899561234567890",
      "status": "Delivered"
    }
  ]
}

1.4 Search/Filter Shipments

Search for shipments based on various criteria.

Method: POST
Endpoint: /v1/shipments/search

Payload Format:

{
  "filters": {
    "status": ["Delivered"],
    "carrier": ["FedEx", "UPS"],
    "delivery_from": "2024-07-01T00:00:00Z",
    "delivery_to": "2024-07-15T23:59:59Z"
  },
  "page": 1,
  "limit": 25
}

Example Request:

curl -X POST "https://api.lateshipment.com/v1/shipments/search" \
     -H "Content-Type: application/json" \
     -H "email: admin@yourcompany.com" \
     -H "x-auth-key: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
     -d '{
       "filters": { "status": ["Delivered"] }
     }'

Success Response (200 OK):

{
  "status": "success",
  "pagination": {
    "total_results": 150,
    "page": 1,
    "limit": 25,
    "total_pages": 6
  },
  "data": [
    {
      "tracking_number": "781234567890",
      "status": "Delivered",
      "delivery_date": "2024-07-14T11:00:00Z"
    }
  ]
}

1.5 Get Full Delivery History/Timeline

Retrieves the complete, ordered event timeline for a specific shipment.

Method: GET
Endpoint: /v1/shipments/{tracking_number}/history

Parameters:

Type	Name	Description
Path	`tracking_number`	The unique carrier tracking number for the shipment.

Example Request:

curl -X GET "https://api.lateshipment.com/v1/shipments/1Z999AA10123456784/history" \
     -H "email: admin@yourcompany.com" \
     -H "x-auth-key: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Success Response (200 OK):

{
  "status": "success",
  "data": {
    "tracking_number": "1Z999AA10123456784",
    "history": [
      {
        "timestamp": "2024-07-18T10:30:00Z",
        "location": "Louisville, KY, United States",
        "description": "Departure Scan"
      },
      {
        "timestamp": "2024-07-18T04:12:00Z",
        "location": "Louisville, KY, United States",
        "description": "Arrival Scan"
      },
      {
        "timestamp": "2024-07-17T22:15:00Z",
        "location": "Dallas, TX, United States",
        "description": "Origin Scan"
      },
      {
        "timestamp": "2024-07-17T20:05:00Z",
        "location": "Dallas, TX, United States",
        "description": "Shipment information sent to carrier"
      }
    ]
  }
}

2. Exceptions

2.1 Get Delivery Exceptions for Shipment

Retrieves any delivery exceptions (e.g., delay, damaged in transit) recorded for a shipment.

Method: GET
Endpoint: /v1/shipments/{tracking_number}/exceptions

Parameters:

Type	Name	Description
Path	`tracking_number`	The unique carrier tracking number for the shipment.

Example Request:

curl -X GET "https://api.lateshipment.com/v1/shipments/1Z999AA10198765432/exceptions" \
     -H "email: admin@yourcompany.com" \
     -H "x-auth-key: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Success Response (200 OK):

{
  "status": "success",
  "data": {
    "tracking_number": "1Z999AA10198765432",
    "exceptions": [
      {
        "code": "D1",
        "description": "Weather Delay",
        "timestamp": "2024-07-19T08:00:00Z",
        "details": "Severe thunderstorms in the area have disrupted sorting operations."
      }
    ]
  }
}

Success Response (No Exceptions):

{
  "status": "success",
  "data": {
    "tracking_number": "1Z999AA10198765432",
    "exceptions": []
  }
}

3. Claims (Lost/Damaged Shipments)

Endpoints for managing claims for lost or damaged shipments.

3.1 Report Shipment as Lost/Damaged (Initiate Claim)

Initiates a new claim for a lost or damaged shipment.

Method: POST
Endpoint: /v1/claims

Payload Format:

{
  "tracking_number": "1Z999AA10123456784",
  "claim_type": "damaged",
  "description": "The outer box was crushed and the item inside, a ceramic vase, is shattered.",
  "attachments": [
    "https://your-cdn.com/images/photo1.jpg",
    "https://your-cdn.com/docs/invoice.pdf"
  ]
}

Example Request:

curl -X POST "https://api.lateshipment.com/v1/claims" \
     -H "Content-Type: application/json" \
     -H "email: admin@yourcompany.com" \
     -H "x-auth-key: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
     -d '{
       "tracking_number": "1Z999AA10123456784",
       "claim_type": "damaged",
       "description": "The outer box was crushed.",
       "attachments": ["https://your-cdn.com/images/photo1.jpg"]
     }'

Success Response (201 Created):

{
  "status": "success",
  "message": "Claim initiated successfully.",
  "data": {
    "claim_id": "CLM-XYZ789",
    "tracking_number": "1Z999AA10123456784",
    "status": "Submitted"
  }
}

Failure Response (422 Unprocessable Entity):

{
  "status": "error",
  "message": "Validation failed.",
  "errors": {
    "claim_type": "Claim type must be either 'lost' or 'damaged'."
  }
}

3.2 Update Claim Info

Updates an existing claim with a new description or additional attachments.

Method: PATCH
Endpoint: /v1/claims/{claim_id}

Payload Format:

{
  "description": "Adding more details about the damage.",
  "attachments_to_add": [
    "https://your-cdn.com/images/photo2_close_up.jpg"
  ]
}

Example Request:

curl -X PATCH "https://api.lateshipment.com/v1/claims/CLM-XYZ789" \
     -H "Content-Type: application/json" \
     -H "email: admin@yourcompany.com" \
     -H "x-auth-key: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
     -d '{
       "attachments_to_add": ["https://your-cdn.com/images/photo2.jpg"]
     }'

Success Response (200 OK):

{
  "status": "success",
  "message": "Claim updated successfully.",
  "data": {
    "claim_id": "CLM-XYZ789",
    "status": "Under Review"
  }
}

3.3 Get List of All Claims

Retrieves a paginated list of all claims associated with your account.

Method: GET
Endpoint: /v1/claims

Example Request:

curl -X GET "https://api.lateshipment.com/v1/claims?status=Submitted" \
     -H "email: admin@yourcompany.com" \
     -H "x-auth-key: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Success Response (200 OK):

{
  "status": "success",
  "data": [
    {
      "claim_id": "CLM-XYZ789",
      "tracking_number": "1Z999AA10123456784",
      "status": "Submitted",
      "created_at": "2024-07-20T14:00:00Z"
    }
  ]
}

3.4 Get Details/Status of a Specific Claim

Retrieves the full details and status for a single claim.

Method: GET
Endpoint: /v1/claims/{claim_id}

Example Request:

curl -X GET "https://api.lateshipment.com/v1/claims/CLM-XYZ789" \
     -H "email: admin@yourcompany.com" \
     -H "x-auth-key: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Success Response (200 OK):

{
  "status": "success",
  "data": {
    "claim_id": "CLM-XYZ789",
    "tracking_number": "1Z999AA10123456784",
    "claim_type": "damaged",
    "status": "Submitted",
    "description": "The outer box was crushed.",
    "attachments": [
      "https://your-cdn.com/images/photo1.jpg"
    ],
    "created_at": "2024-07-20T14:00:00Z"
  }
}

4. Webhooks (Event Push to External Systems)

Register a webhook to receive real-time notifications for critical Delivery Experience Management (DEM) events. When an event occurs, we will send an HTTP POST request to the URL you provide.

Webhook Event Payloads

When a subscribed event is triggered, your target_url will receive a POST request with a payload similar to the examples below. Your endpoint should respond with a 200 OK status code to acknowledge receipt.

Example: shipment.delayed event

{
  "event_id": "evt_12345",
  "event_type": "shipment.delayed",
  "created_at": "2024-07-21T09:00:00Z",
  "data": {
    "tracking_number": "1Z999AA10198765432",
    "reason": "Operational Delay",
    "new_estimated_delivery": "2024-07-23T18:00:00Z"
  }
}

Example: claim.status.changed event

{
  "event_id": "evt_67890",
  "event_type": "claim.status.changed",
  "created_at": "2024-07-22T11:30:00Z",
  "data": {
    "claim_id": "CLM-XYZ789",
    "tracking_number": "1Z999AA10123456784",
    "previous_status": "Submitted",
    "new_status": "Approved",
    "resolution_details": "Claim approved for full value. Payout will be processed within 3-5 business days."
  }
}