API Reference
Shipments

Shipments API

The shipments API lets you create, retrieve, update, and delete shipments in your TrackLogy workspace.

GET /v1/shipments

List all shipments in your workspace, with optional filtering and pagination.

Query Parameters

ParameterTypeDescription
pageintegerPage number (default: 1)
per_pageintegerResults per page (default: 25, max: 100)
statusstringFilter by shipment status
store_idintegerFilter by store ID
tracking_providerstringFilter by carrier slug
searchstringSearch by tracking number, order ID, or customer name
date_fromstringFilter by created date (ISO 8601)
date_tostringFilter by created date (ISO 8601)

Request

curl "https://api.tracklogy.com/v1/shipments?page=1&per_page=10&status=in_transit" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 42,
        "tracking_number": "1Z999AA10123456784",
        "tracking_provider": "ups",
        "status": "in_transit",
        "customer_name": "Jane Smith",
        "customer_email": "[email protected]",
        "order_id": "ORD-1001",
        "created_at": "2025-05-07T10:00:00Z",
        "updated_at": "2025-05-07T14:30:00Z"
      }
    ],
    "total": 142,
    "page": 1,
    "per_page": 10,
    "total_pages": 15
  }
}

POST /v1/shipments

Create a new shipment. Consumes one tracker from your balance.

Request Body

FieldTypeRequiredDescription
tracking_numberstringYesCarrier tracking number
tracking_providerstringNoCarrier slug (auto-detected if omitted)
store_idintegerNoAssociate with a specific store
customer_namestringNoCustomer full name
customer_emailstringNoCustomer email (for email notifications)
customer_phonestringNoCustomer phone in E.164 format (for SMS)
customer_addressstringNoShipping address
order_idstringNoYour internal order ID
order_numberstringNoHuman-readable order number
destination_countrystringNoISO country code (e.g. US)
postal_codestringNoDestination postal code
est_delivery_datestringNoEstimated delivery (ISO 8601)
notesstringNoInternal notes

Request

curl -X POST https://api.tracklogy.com/v1/shipments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_number": "9400111899223456789012",
    "tracking_provider": "usps",
    "customer_name": "John Doe",
    "customer_email": "[email protected]",
    "customer_phone": "+12125550100",
    "order_id": "ORD-5001",
    "order_number": "#5001",
    "destination_country": "US",
    "postal_code": "10001"
  }'

Response (201 Created)

{
  "success": true,
  "message": "Shipment created",
  "data": {
    "shipment": {
      "id": 42,
      "tracking_number": "9400111899223456789012",
      "tracking_provider": "usps",
      "status": "pending",
      "customer_name": "John Doe",
      "customer_email": "[email protected]",
      "order_id": "ORD-5001",
      "order_number": "#5001",
      "destination_country": "US",
      "created_at": "2025-05-07T10:00:00Z"
    },
    "detected_tracking_provider": "usps"
  }
}

Error Responses

CodeMessageReason
409Shipment with this tracking number already existsDuplicate
402Tracker balance is not availableBalance exhausted
422Tracking number is requiredMissing field

GET /v1/shipments/show

Retrieve a single shipment by its ID.

Query Parameters

ParameterTypeRequiredDescription
idintegerYesShipment ID

Request

curl "https://api.tracklogy.com/v1/shipments/show?id=42" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "shipment": {
      "id": 42,
      "tracking_number": "9400111899223456789012",
      "tracking_provider": "usps",
      "status": "delivered",
      "customer_name": "John Doe",
      "customer_email": "[email protected]",
      "order_id": "ORD-5001",
      "est_delivery_date": "2025-05-09",
      "delivered_at": "2025-05-09T14:22:00Z",
      "created_at": "2025-05-07T10:00:00Z",
      "updated_at": "2025-05-09T14:22:00Z"
    }
  }
}

DELETE /v1/shipments/delete

Delete a shipment. This also removes all associated tracking events.

⚠️

Deleting a shipment is permanent and does not refund the tracker credit.

Request Body

FieldTypeRequiredDescription
idintegerYesShipment ID to delete

Request

curl -X DELETE https://api.tracklogy.com/v1/shipments/delete \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": 42 }'

Response

{
  "success": true,
  "message": "Shipment deleted",
  "data": {}
}

GET /v1/shipments/events

Get the tracking event history for a shipment.

Query Parameters

ParameterTypeRequiredDescription
shipment_idintegerYesShipment ID
pageintegerNoPage number (default: 1)
per_pageintegerNoResults per page (default: 50, max: 100)

Request

curl "https://api.tracklogy.com/v1/shipments/events?shipment_id=42" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 101,
        "shipment_id": 42,
        "status": "delivered",
        "description": "Delivered to front door",
        "location": "New York, NY",
        "event_at": "2025-05-09T14:22:00Z",
        "source": "carrier"
      },
      {
        "id": 100,
        "shipment_id": 42,
        "status": "out_for_delivery",
        "description": "Out for delivery",
        "location": "New York, NY",
        "event_at": "2025-05-09T08:15:00Z",
        "source": "carrier"
      }
    ],
    "total": 5,
    "page": 1,
    "per_page": 50
  }
}
Overview & AuthCarriers