--- title: "Create or Update Route" method: POST path: "/v1/routes" tags: ["Route"] --- # Create or Update Route `POST /v1/routes` ## Request - Base URL: `https://api.sandbox.usenash.com` - URL: `https://api.sandbox.usenash.com/v1/routes` - Auth: none declared 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` integer, nullable: Estimated service time spent at the stop (in seconds). - `distanceFromPrevious` integer, nullable: Distance traveled from the previous stop (in meters). - `durationFromPrevious` integer, 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 - `occurredAt` string, nullable: Time the action happened on the driver's device, when known - `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.dev/nash/apis/nash-api.md) - [All operations](https://skmtc.dev/nash/apis/nash-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nash/apis/nash-api/revisions/e3713837c5c9?raw)