Skip to main content

​
Overview

The Order Stops API provides read-only access to the order_stops table, which contains stop-level data for customer orders with tracking status information. Database Table: order_stops Purpose:
  • Query stops associated with orders (pickups, deliveries)
  • Filter by tracking status (en_route, arrived, departed, etc.)
  • Get stops with Terminal tracking enabled
Difference from Movement Stops:
  • order_stops - Customer-facing order data
  • movement_stops - Internal shipment/movement data (used by operations)

​
Get Order Stops

​
GET /api/order_stops/

Retrieve order stop records with optional filtering.
​
company_id
string
default:"None"
Filter by company ID
​
order_id
string
default:"None"
Filter by order ID
​
terminal_vehicle_id
string
default:"None"
Filter by Terminal vehicle ID
​
tracking_status
string
default:"None"
Filter by tracking status: not_tracked, en_route, arrived, departed, delayed, exception
Response: 
[
  {
    "order_id": "ORD-123456",
    "order_sequence": 1,
    "company_id": "TMS",
    "stop_type": "PU",
    "city_name": "Austin",
    "state": "TX",
    "zip_code": "78701",
    "address": "123 Main St",
    "location_name": "Warehouse A",
    "latitude": "30.2672",
    "longitude": "-97.7431",
    "scheduled_arrival_early": "2025-11-17T08:00:00.000Z",
    "scheduled_arrival_late": "2025-11-17T10:00:00.000Z",
    "actual_arrival": "2025-11-17T08:45:00.000Z",
    "actual_departure": "2025-11-17T09:30:00.000Z",
    "tracking_status": "departed",
    "terminal_tracking_enabled": true,
    "terminal_vehicle_id": "vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC"
  }
]
How it works:
  1. Query Database: Calls get_order_stops() which queries the order_stops table
  2. Filter Application: Applies provided filters using SQL WHERE clauses with AND logic
  3. Ordering: Results are ordered by order_id, order_sequence for consistent ordering
  4. Response Conversion: Converts SQLAlchemy rows to Pydantic response models
Tracking Status Values:
StatusDescription
not_trackedStop is not being tracked via Terminal
en_routeVehicle is en route to this stop
arrivedVehicle has arrived at this stop
departedVehicle has departed from this stop
delayedVehicle is delayed (late ETA)
exceptionException occurred at this stop

​
Get Tracked Order Stops

​
GET /api/order_stops/tracked

Retrieve all order stops with Terminal tracking enabled. Response: 
[
  {
    "order_id": "ORD-123456",
    "order_sequence": 1,
    "company_id": "TMS",
    "tracking_status": "en_route",
    "terminal_tracking_enabled": true,
    "terminal_vehicle_id": "vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC"
  }
]
How it works:
  1. Calls get_tracked_order_stops() which queries with terminal_tracking_enabled = True
  2. Returns only stops that are actively being tracked via Terminal API

​
Get Order Stops by Company

​
GET /api/order_stops/company/

Retrieve all order stops for a specific company.
​
company_id
string
required
Company ID to filter by
Response: 
[
  {
    "order_id": "ORD-123456",
    "company_id": "TMS",
    "order_sequence": 1,
    "stop_type": "PU",
    "city_name": "Austin",
    "state": "TX"
  }
]
How it works:
  1. Calls get_order_stops_by_company() with the specified company ID
  2. Returns all stops for that company, ordered by order_id, order_sequence
  3. Returns empty array if company not found

​
Data Model

​
Order Stops Table Schema

ColumnTypeDescription
order_idVARCHAROrder ID (composite key part 1)
order_sequenceINTStop sequence within order (composite key part 2)
company_idVARCHARCompany ID
stop_typeVARCHARStop type (PU=Pickup, SO=Delivery)
city_nameVARCHARCity name
stateVARCHARState code
zip_codeVARCHARZIP code
addressVARCHARStreet address
location_nameVARCHARLocation/facility name
latitudeNUMERICGPS latitude
longitudeNUMERICGPS longitude
scheduled_arrival_earlyTIMESTAMPTZEarliest scheduled arrival
scheduled_arrival_lateTIMESTAMPTZLatest scheduled arrival
actual_arrivalTIMESTAMPTZActual arrival timestamp
actual_departureTIMESTAMPTZActual departure timestamp
tracking_statusVARCHARCurrent tracking status
terminal_tracking_enabledBOOLEANWhether Terminal tracking is active
terminal_vehicle_idVARCHARAssigned Terminal vehicle ID