--- title: "Create or Update Route" method: POST path: "/v1/routes" tags: ["Route"] --- # Create or Update Route `POST /v1/routes` Create a new route or update an existing one. A route defines an optimized sequence of stops with orders assigned to each stop. ## Request body - UpsertRouteInputSerializer — Input for creating or updating a route. - `externalId` string, nullable — Route ID. If provided, the route will be updated. If not provided, a new route will be created. - `name` string, nullable — Name of the route. - `stops` RouteStopInputSerializer[], nullable — Complete route stops structure with timing, location, and stop types. Supports all stop types including PICKUP, DROPOFF, ROUTE_START, ROUTE_END, and DRIVER_BREAK. - `id` string, nullable — Stable id for this stop. If provided, it is preserved across upserts; if omitted, it is carried forward by matching stop_type + object_ids against the route's current stops, or a new one is minted. - `stopType` string, required — Type of the stop. - `objectIds` string[], required — List of object IDs (e.g., order IDs, store location IDs, break IDs) associated with this stop. - `serviceTime` integer, nullable — Service time at the stop in seconds. - `distanceFromPrevious` integer, nullable — Distance from the previous stop in meters. - `durationFromPrevious` integer, nullable — Travel duration from the previous stop in seconds. - `arrivalTime` string, nullable — Planned arrival time at the stop (UTC). - `departTime` string, nullable — Planned departure time from the stop (UTC). - `location` LatLngSerializer — Latitude/longitude coordinates. - `lat` number, required — Latitude coordinate. - `lng` number, required — Longitude coordinate. - `metadata` object, nullable — Additional metadata for this stop. - `routeMetadata` object, nullable — Additional metadata for the route. - `vehicleId` string, nullable — Vehicle ID (or external ID) to assign to this route. - `courierId` string, nullable — Courier/Driver ID (or external ID) to assign to this route. - `driverGroupId` string, nullable — Driver group/Contract ID (or external ID) to assign to this route. Required when assigning a courier or vehicle. - `autoDispatch` boolean — If true, dispatch the route to providers in the same request after upsert. Default: false. ## Response `200` OK - UpsertRouteResponseSerializer — Response for route upsert operation. - `route` RouteSerializer, required — Represents a planned sequence of stops for a delivery or batch. - `id` string, required — Unique identifier for the route. - `externalId` string, nullable — External Route ID. - `portalUrl` string, required — Portal URL of the route. - `name` string, nullable — Name of the route. - `type` string, required — Type of the route, indicating the pickup/dropoff structure. - `courierId` string, nullable — Courier ID of the driver assigned to the route. - `vehicleId` string, nullable — Vehicle ID of the vehicle assigned to the route. - `courier` CourierSerializer — Courier details for a route. - `id` string, nullable - `firstName` string, nullable - `lastName` string, nullable - `phoneNumber` string, nullable - `driverGroup` DriverGroupSerializer — Driver group details for a route. - `id` string, nullable - `externalId` string, nullable - `courierPosition` CourierPositionSerializer — Current GPS position of a courier. - `lat` number, required — Latitude coordinate. - `lng` number, required — Longitude coordinate. - `updatedAt` string, nullable — Timestamp when the position was last updated on the server. - `capturedAt` string, nullable — Timestamp when the GPS position was captured on driver's device. - `accuracy` number, nullable — Estimated horizontal accuracy radius in meters. - `heading` number, nullable — Heading in degrees relative to true north. - `speed` number, nullable — Speed in meters per second. - `altitude` number, nullable — Altitude in meters above sea level. - `altitudeAccuracy` number, nullable — Estimated altitude accuracy in meters. - `batteryLevel` number, nullable — Battery level from 0.0 to 1.0, if provided by device. - `batteryIsCharging` boolean, nullable — Whether the device is currently charging. - `isMoving` boolean, nullable — Whether the device is currently detected as moving. - `vehicle` VehicleSerializer — Vehicle details for a route. - `licensePlate` string, nullable - `make` string, nullable - `model` string, nullable - `color` string, nullable - `year` integer, nullable - `type` string, nullable - `providerName` string, nullable — Name of the delivery provider assigned to this route. - `shiftId` string, nullable — Shift ID of the shift assigned to the route. - `stops` RouteStopSerializer[], required — Ordered list of stops included in the route. - `stopType` string, required — Type of the stop. - `objectIds` string[], required — List of object IDs (e.g., order IDs, store location IDs) associated with this stop. - `arrivalTime` string, nullable — Estimated arrival time at the stop (UTC). - `departTime` string, nullable — Estimated departure time from the stop (UTC). - `plannedArrivalTime` string, nullable — Snapshot of arrival_time captured pre-dispatch (UTC). Mirrors arrival_time while the route is undispatched, then freezes at dispatch — gives consumers the planned ETA at dispatch even after real-time tracking updates arrival_time. - `serviceTime` number, nullable — Estimated service time spent at the stop (in seconds). - `distanceFromPrevious` number, nullable — Distance traveled from the previous stop (in meters). - `durationFromPrevious` number, nullable — Travel duration from the previous stop (in seconds). - `location` LatLngSerializer, required — Latitude/longitude coordinates. - `lat` number, required — Latitude coordinate. - `lng` number, required — Longitude coordinate. - `status` string, nullable — Current status of the stop. - `statusDescription` string, nullable — Detailed description of the current status of the stop. - `statusHistory` object[], nullable — History of status changes for the stop. - `metadata` object, nullable — Additional metadata for this stop. - `startedAt` string, nullable — Timestamp when the stop entered IN_PROGRESS status (UTC). - `breakDuration` integer, nullable — Duration in seconds of the break at this stop (for DRIVER_BREAK stops). - `orders` StopOrderSerializer[], nullable — Orders associated with this stop, including tracking URLs and delivery details. - `id` string, required — Order ID. - `externalId` string, nullable — External identifier for the order. - `publicTrackingUrl` string, nullable — Public tracking URL for the order. - `pod` ProofOfDeliverySerializer[], nullable — Proof of delivery data (photos, signature, etc.) if captured. - `type` string, required — Type of proof of delivery, e.g., 'photo', 'signature', etc. - `url` string, nullable — URL of the proof of delivery document. - `uploadedAt` string, nullable — Timestamp when the proof of delivery was uploaded. - `orderItems` OrderItemSerializer[], nullable — Items with lifecycle status tracking (picked, delivered, failed, etc.). - `id` string, nullable — The merchant ID of the item - `description` string, nullable — The description of the item - `count` integer, nullable — The quantity of the item - `valueCents` integer, nullable — The value of the item in cents - `barcode` string, nullable — Barcode associated with the item - `sku` string, nullable — SKU of the item - `category` string, nullable — The category of the item - `status` string, nullable — Current lifecycle status of the item. - `availableQuantity` integer, nullable — Quantity available after pickup (may differ from count) - `statusMetadata` ItemStatusMetadataSerializer — Operational metadata tracked during item lifecycle in route delivery. - `pickedAt` string, nullable — Timestamp when the item was picked up - `deliveredAt` string, nullable — Timestamp when the item was delivered - `failedAt` string, nullable — Timestamp when the item delivery failed - `returnedAt` string, nullable — Timestamp when the item was returned - `failureReason` string, nullable — Reason for delivery failure - `failureLocation` string, nullable — Where the failure occurred: 'pickup' or 'dropoff' - `statusHistory` ItemStatusHistoryEntrySerializer[], nullable — History of status changes for this item. - `status` string, required — Item status at this point in time - `createdAt` string, required — Timestamp of the status change - `subItems` OrderItemSerializer[], nullable — Nested sub-items with their own status tracking. - `isDispatched` boolean — Whether the route is dispatched. - `jobId` string, nullable — Dispatched Job ID of this route - `routeMetadata` object, nullable — Additional metadata for the route. - `validationErrors` object, nullable — Validation errors for the route. - `encodedPolyline` string, nullable — Encoded polyline representing the route geometry. - `status` string, nullable — Current status of the route. - `statusHistory` object[], nullable — History of status changes for the route. ## Other responses - `422` — Unprocessable Content --- [API](https://skmtc.net/usenash/apis/nash-api.md) · [All operations](https://skmtc.net/usenash/apis/nash-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/usenash/nash-api/revisions/09a23a95889b/schema)