Shipment Tracking

Manage shipment tracking visualization data including map markers and detailed tracking checkpoints. These endpoints support map rendering and checkpoint ingestion for tracking timelines.

Get Map Data

GET/api/v1/shipment-tracking/map

Get shipments with coordinates for map markers.

Requiredshipments:read

Returns shipments that have geo-coordinates, with minimal fields needed for rendering map markers. Results are ordered by creation date (newest first).

Query Parameters

Parameter	Type	Description
`limit`	number	Maximum results to return (default: 100)
`status`	string	Filter by shipment status
`bridgeId`	string	Filter by bridge ID


curl -X GET "https://api.orderly-hub.com/api/v1/shipment-tracking/map?status=in_transit&limit=50" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "status": "in_transit",
      "tracking_number": "794644790132",
      "carrier": "fedex",
      "service": "FedEx Ground Home Delivery",
      "ship_to_lat": 34.0522,
      "ship_to_lng": -118.2437,
      "ship_from_lat": 40.7357,
      "ship_from_lng": -74.1724,
      "ship_to": { "city": "Los Angeles", "state": "CA" },
      "ship_from": { "city": "Newark", "state": "NJ" },
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-01-16T14:30:00Z"
    }
  ]
}

List Checkpoints

GET/api/v1/shipment-tracking/checkpoints

List tracking checkpoints for a shipment.

Requiredshipments:read

Returns a paginated list of tracking checkpoints for a given shipment, ordered by sequence number (ascending).

Query Parameters

Parameter	Type	Description
`shipmentId`	string	Required. The shipment UUID
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 50)


curl -X GET "https://api.orderly-hub.com/api/v1/shipment-tracking/checkpoints?shipmentId=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "organizationId": "uuid",
      "shipmentId": "550e8400-e29b-41d4-a716-446655440000",
      "sequence": 1,
      "status": "label_created",
      "statusDetail": "Shipment information sent to carrier",
      "description": "Shipping label created",
      "city": "Newark",
      "state": "NJ",
      "country": "US",
      "countryCode": "US",
      "zip": "07102",
      "latitude": 40.7357,
      "longitude": -74.1724,
      "checkpointTime": "2026-01-15T10:30:00Z",
      "source": "carrier_webhook",
      "sourceEventId": "evt_abc123",
      "isException": false,
      "exceptionType": null,
      "createdAt": "2026-01-15T10:31:00Z",
      "updatedAt": "2026-01-15T10:31:00Z"
    }
  ]
}

Add Checkpoint

POST/api/v1/shipment-tracking/checkpoints

Add a single tracking checkpoint to a shipment.

Requiredshipments:write

Creates a new tracking checkpoint for a shipment. Duplicate checkpoints (same source + event ID) are rejected with a 409 status.

Request Body

Field	Type	Required	Description
`shipmentId`	string	Yes	Shipment UUID
`sequence`	number	Yes	Checkpoint sequence number
`status`	string	Yes	Status code (e.g., `in_transit`, `delivered`)
`statusDetail`	string	No	Detailed status description
`description`	string	No	Human-readable description
`city`	string	No	City name
`state`	string	No	State or province
`country`	string	No	Country name
`countryCode`	string	No	Two-letter country code
`zip`	string	No	Postal code
`latitude`	number	No	Latitude coordinate
`longitude`	number	No	Longitude coordinate
`checkpointTime`	string	Yes	When the event occurred (ISO 8601)
`source`	string	Yes	Source of the checkpoint (e.g., `carrier_webhook`, `manual`)
`sourceEventId`	string	No	Unique event ID from source (used for deduplication)
`rawData`	object	No	Raw event data from carrier
`isException`	boolean	No	Whether this is an exception event (default: `false`)
`exceptionType`	string	No	Exception type (e.g., `delay`, `damage`)


curl -X POST "https://api.orderly-hub.com/api/v1/shipment-tracking/checkpoints" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "shipmentId": "550e8400-e29b-41d4-a716-446655440000",
    "sequence": 3,
    "status": "in_transit",
    "description": "Arrived at FedEx facility",
    "city": "Indianapolis",
    "state": "IN",
    "country": "US",
    "countryCode": "US",
    "checkpointTime": "2026-01-16T14:30:00Z",
    "source": "carrier_webhook",
    "sourceEventId": "evt_xyz789"
  }'

Response (201)


{
  "data": {
    "id": "uuid",
    "organizationId": "uuid",
    "shipmentId": "550e8400-e29b-41d4-a716-446655440000",
    "sequence": 3,
    "status": "in_transit",
    "description": "Arrived at FedEx facility",
    "city": "Indianapolis",
    "state": "IN",
    "checkpointTime": "2026-01-16T14:30:00Z",
    "source": "carrier_webhook",
    "sourceEventId": "evt_xyz789",
    "isException": false,
    "createdAt": "2026-01-16T14:31:00Z",
    "updatedAt": "2026-01-16T14:31:00Z"
  }
}

Batch Add Checkpoints

POST/api/v1/shipment-tracking/checkpoints/batch

Add multiple tracking checkpoints in a single request (upsert).

Requiredshipments:write

Creates or updates multiple checkpoints across one or more shipments. Uses upsert behavior on the deduplication key (shipment_id + source + source_event_id), so existing checkpoints with the same key are updated rather than duplicated.

Request Body

Field	Type	Required	Description
`checkpoints`	object[]	Yes	Array of checkpoint objects (same fields as single checkpoint)

All shipments referenced in the batch must belong to the authenticated organization. If any shipment ID is invalid, the entire batch is rejected.


curl -X POST "https://api.orderly-hub.com/api/v1/shipment-tracking/checkpoints/batch" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "checkpoints": [
      {
        "shipmentId": "550e8400-e29b-41d4-a716-446655440000",
        "sequence": 4,
        "status": "out_for_delivery",
        "description": "On FedEx vehicle for delivery",
        "city": "Los Angeles",
        "state": "CA",
        "checkpointTime": "2026-01-17T08:00:00Z",
        "source": "carrier_webhook",
        "sourceEventId": "evt_del001"
      },
      {
        "shipmentId": "550e8400-e29b-41d4-a716-446655440000",
        "sequence": 5,
        "status": "delivered",
        "description": "Delivered - Signed for by J. SMITH",
        "city": "Los Angeles",
        "state": "CA",
        "checkpointTime": "2026-01-17T14:22:00Z",
        "source": "carrier_webhook",
        "sourceEventId": "evt_del002"
      }
    ]
  }'

Response (201)


{
  "data": [
    {
      "id": "uuid",
      "shipmentId": "550e8400-e29b-41d4-a716-446655440000",
      "sequence": 4,
      "status": "out_for_delivery",
      "checkpointTime": "2026-01-17T08:00:00Z"
    },
    {
      "id": "uuid",
      "shipmentId": "550e8400-e29b-41d4-a716-446655440000",
      "sequence": 5,
      "status": "delivered",
      "checkpointTime": "2026-01-17T14:22:00Z"
    }
  ],
  "count": 2
}

Error Responses

Status	Description
`400`	One or more shipment IDs not found in the organization
`409`	Duplicate checkpoint (same source + event ID) — single checkpoint endpoint only