---
title: "Report a shipment milestone"
method: POST
path: "/v1/carrier/shipments/{identifier}/milestones"
tags: ["Carrier API"]
---

# Report a shipment milestone

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

## Request

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

Records a physical shipment observation without changing the shipment's commercial order state.

## Path parameters

- `identifier` string, required

## Request body

- MilestoneReportRequest: A carrier-observed physical shipment milestone
  - `type` 'ARRIVED_AT_PICKUP' | 'LOADED' | 'DEPARTED_PICKUP' | 'ARRIVED_AT_DELIVERY' | 'UNLOADED', required
  - `occurred_at` string, date-time, required: Time the physical event occurred
  - `coordinates` EventCoordinates: GPS coordinates for a shipment event
    - `latitude` number, double: Latitude in decimal degrees
    - `longitude` number, double: Longitude in decimal degrees
  - `notes` string: Additional notes about the milestone

## Response `200`

Milestone recorded

- ShipmentMilestoneDTO
  - `type` 'ARRIVED_AT_PICKUP' | 'LOADED' | 'DEPARTED_PICKUP' | 'ARRIVED_AT_DELIVERY' | 'UNLOADED'
  - `source` 'DRIVER_APP' | 'ADMIN_APP' | 'CARRIER_API' | 'ELD_AUTO' | 'INFERRED'
  - `occurredAt` string, date-time
  - `lat` number, double
  - `lng` number, double
  - `notes` string

## Other responses

- `400`: Invalid milestone request
- `401`: Authentication required
- `403`: Carrier is not authorized for this shipment
- `404`: Shipment not found for this carrier
- `409`: Shipment is not in a reportable state
- `500`: Milestone could not be recorded

## Changes

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

[Operation history](https://skmtc.dev/shipoway/apis/oway-carrier-api/changes/v1/carrier/shipments/:identifier/milestones/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)