--- title: "tracking shipments" method: POST path: "/freights/tracking" tags: ["Freight"] --- # tracking shipments `POST /freights/tracking` ## Request - Base URL: `https://stg.wearewarp.com/api/v1` - URL: `https://stg.wearewarp.com/api/v1/freights/tracking` - Auth: API key in header `apikey` Returns the latest status and the last known driver location of one or more shipments. **Request parameters** | Name | Type | Required/Optional | Description | |-----------------|---------------|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------| | trackingNumbers | Array | Required | The identifiers to look up. Each value can be a shipment tracking number, a shipment number (code, e.g. `S-00524-2635`) or an order number (code, e.g. `P-01723-2449`). Unknown values are simply omitted from the response. At most 50 values per request. |
**Response parameters** (one element per matched shipment) | Name | Type | Description | |-----------------------|--------|---------------------------------------------------------------------------------------------------| | trackingNumber | String | The value from the request that matched this shipment. | | orderId | String | The ID of the order. | | orderNumber | String | The display number (code) of the order. | | shipmentId | String | The ID of the shipment. | | shipmentNumber | String | The display number (code) of the shipment. | | statusInfo.status | String | Current shipment status (see the table below). | | statusInfo.lastUpdated| String | ISO 8601 timestamp of the last status change (`null` when unknown). | | location | Object | Last known driver location - `null` when the shipment is not on a route yet or no GPS ping exists. | | location.latitude | Number | | | location.longitude | Number | | | location.lastUpdated | String | ISO 8601 timestamp of the GPS ping (`null` when unknown). |
**Shipment status** | Value | Description | |-----------------------|------------------------------------------------------------------------------------| | needCarrier | First status when creating a shipment - Need to assign carrier. | | booked | When the carrier is assigned to the shipment. | | dispatched | When the driver/vehicle has started for pickup location. | | arrivedAtPickup | When the driver/vehicle has arrived at pickup location. | | pickupSuccessful | When the order is loaded in vehicle. | | pickupFailed | When Pickup task is Failed. | | inRouteToDropoff | When the driver/vehicle has started for dropoff location. | | arrivedAtDropoff | When the driver/vehicle has arrived at dropoff location. | | dropoffSuccessful | When the driver/vehicle has delivered the order successfully. | | dropoffFailed | When Dropoff task is “Failed”. | | complete | When the order is completed. | | returnInitiated | when return task is created. | | inRouteToReturn | When the driver/vehicle has started for return location. | | arrivedAtReturn | When the driver/vehicle has arrived at return location. | | returned | When the driver/vehicle has returned the order successfully. | | canceled | When the order is canceled. | | inRouteToWareHouse | When order is in route to the warehouse (In the case of using crossdock warehouse) | | arrivedAtWareHouse | When order is arrived at the warehouse (In the case of using crossdock warehouse) | | departedFromWarehouse | When order has left the warehouse (In the case of using crossdock warehouse) | | lost | When the shipment was reported lost. | | issue | When an issue was raised on the shipment and it is under review. | | removed | When the shipment was removed from its order. | | disposed | When the shipment was disposed of. | ## Request body - TrackingShipmentQuery - `trackingNumbers` string[], required: Shipment tracking numbers, shipment numbers (codes) or order numbers (codes). Unknown values are omitted from the response. ## Response `200` successful operation - TrackInfo[] - `trackingNumber` string: The value from the request that matched this shipment. - `orderId` string - `orderNumber` string: The display number (code) of the order. - `shipmentId` string - `shipmentNumber` string: The display number (code) of the shipment. - `statusInfo` object - `status` 'needCarrier' | 'booked' | 'dispatched' | 'arrivedAtPickup' | 'pickupSuccessful' | 'pickupFailed' | 'inRouteToDropoff' | 'arrivedAtDropoff' | 'dropoffSuccessful' | 'dropoffFailed' | 'complete' | 'returnInitiated' | 'inRouteToReturn' | 'arrivedAtReturn' | 'returned' | 'canceled' | 'inRouteToWareHouse' | 'arrivedAtWareHouse' | 'departedFromWarehouse' | 'lost' | 'issue' | 'removed' | 'disposed': Current shipment status - see the Shipment status table above. - `lastUpdated` string, date-time, nullable: Time of the last status change. `null` when unknown. - `location` object, nullable: Last known driver location. `null` when the shipment is not on a route yet or no GPS ping exists. - `latitude` number - `longitude` number - `lastUpdated` string, date-time, nullable: Time of the GPS ping. `null` when unknown. ## Other responses - `400`: Bad Request - the request payload is missing fields or contains invalid data. - `401`: Unauthorized - the apikey header is missing or does not match any active API key. - `403`: Forbidden - the customer account is suspended. The body carries `message` only, without `code`. - `429`: Too Many Requests - the quoting rate limit of the API key was exceeded (only POST /freights/quote, /freights/freight-quote and /freights/quote/multi-stops are rate limited; limits apply per UTC hour and per UTC day). The `Retry-After` header holds the number of seconds until the window resets. - `500`: Internal Server Error - an unknown error has occurred. --- [API](https://skmtc.dev/wearewarp/apis/warp-api-documentation.md) · [All operations](https://skmtc.dev/wearewarp/apis/warp-api-documentation/llms.txt) · [OpenAPI document](https://skmtc.dev/wearewarp/apis/warp-api-documentation/revisions/01526741bb48?raw)