---
title: "Submit GPS location for a shipment"
method: POST
path: "/v1/carrier/shipments/{identifier}/location"
tags: ["Carrier API"]
---

# Submit GPS location for a shipment

`POST /v1/carrier/shipments/{identifier}/location`

## Request

- Base URL: `https://api.oway.io`
- URL: `https://api.oway.io/v1/carrier/shipments/{identifier}/location`
- Auth: HTTP bearer and API key in header `x-oway-api-key`

Submit a GPS location update tied to a specific shipment.

**State requirement:** The shipment must be in ACCEPTED or PICKED_UP status.

## Path parameters

- `identifier` string, required

## Request body

- OfferLocationUpdate: Real-time location update for a shipment in transit
  - `latitude` number, double, required: Latitude in decimal degrees
  - `longitude` number, double, required: Longitude in decimal degrees
  - `heading` integer: Heading in degrees (0-359, where 0 is north; -1 for unknown)
  - `speed_mph` integer: Speed in miles per hour
  - `timestamp` string, date-time, required: Timestamp of this location reading
  - `vehicle_id` string: Identifier of the vehicle reporting this position. Optional. Supply it here if the vehicle was not known at offer acceptance, or when the truck changes mid-shipment; the latest value is recorded as the shipment's assigned vehicle. The position trail itself is keyed internally per shipment, so changing or omitting this never affects tracking history.

## Response `200`

Location update acknowledged

- LocationAcknowledgment: Acknowledgment of a location update
  - `recorded` boolean: Whether the location update was recorded
  - `order_number` string: Human-readable order number

## Other responses

- `400`: Invalid request: latitude, longitude, and timestamp are required
- `401`: Unauthorized: missing or invalid bearer token
- `403`: Forbidden: missing/invalid API key or API access not enabled
- `404`: Shipment not found
- `409`: Shipment not in valid state for location updates
- `500`: Internal server error

## Changes

- **2026-11-03** `8d96932e1dc6`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/shipoway/apis/oway-carrier-api/changes/v1/carrier/shipments/:identifier/location/post.md)

---

[API](https://skmtc.dev/shipoway/apis/oway-carrier-api.md) - [All operations](https://skmtc.dev/shipoway/apis/oway-carrier-api/llms.txt) - [OpenAPI document](https://skmtc.dev/shipoway/apis/oway-carrier-api/revisions/8d96932e1dc6?raw)