--- title: "Update an existing stop" method: POST path: "/plans/{planId}/stops/{stopId}:liveUpdate" tags: ["Live Stops"] --- # Update an existing stop `POST /plans/{planId}/stops/{stopId}:liveUpdate` ## Request - Base URL: `https://api.spoke.com/public/v1` - URL: `https://api.spoke.com/public/v1/plans/{planId}/stops/{stopId}:liveUpdate` - Auth: HTTP basic - TypeScript: (a function with typed inputs; its response is checked against the schema) Update a stop on live plans. When the plan is not writable, this endpoint starts an editing session and the action can be applied through a new optimization, or be discarded. It does not support updating a stop's location, the `clientId`, nor service fields. To do so, delete the stop and create a new one. ## Path parameters - `planId` string, required - `stopId` string, required ## Request body - object: The request body for updating a live stop. Service fields are not supported on live stops. - `recipient` object, nullable: Recipient information for this stop - `externalId` string, nullable: External ID of the recipient, as defined by the API user - `email` string, email, nullable: The email address of the recipient. Multiple emails are not supported. - `phone` string, nullable: Phone number of the recipient - `name` string, nullable: Name of the recipient - `orderInfo` object, nullable: Order information for this stop - `products` string[]: Products in this stop - `invoiceNumber` string, nullable: Invoice number - `sellerOrderId` string, nullable: Seller order ID - `sellerName` string, nullable: Seller name - `sellerWebsite` string, nullable: Seller website - `paymentOnDelivery` object, nullable: Payment on delivery (also known as "Cash on Delivery") data for this stop - `amount` integer, nullable: Amount *in minor units* (e.g. cents) to be collected upon delivery - `currency` 'AED' | 'ARS' | 'AUD' | 'BRL' | 'CAD' | 'CHF' | 'CLP' | 'CNY' | 'COP' | 'DKK' | 'EGP' | 'EUR' | 'GBP' | 'HKD' | 'HUF' | 'ILS' | 'INR' | 'JPY' | 'KRW' | 'MYR' | 'MXN' | 'NOK' | 'NZD' | 'PEN' | 'RON' | 'RUB' | 'SAR' | 'SEK' | 'SGD' | 'TRY' | 'USD' | 'UYU' | 'ZAR', nullable: Currency of the payment. Defaults to the team's currency. - `proofOfAttemptRequirements` object, nullable: Proof of attempt requirement settings for this stop - `enabled` boolean, nullable: Whether proof of attempt is required for this stop - `allowedDrivers` string[], nullable: Driver IDs that are allowed to be assigned to this stop. These drivers must be configured as part of the plan to be valid. - `activity` 'delivery' | 'pickup', nullable: Activity type - `optimizationOrder` 'first' | 'last' | 'default', nullable: The preferred order of this stop in the optimized route. If not provided or `"default"`, the stop will be placed in the optimal order, decided by the optimization algorithm. Otherwise it will be placed either `"first"` or `"last"`. - `packageCount` number, nullable: Number of packages in the stop - `weight` object, nullable: Weight information for this stop. - `amount` number, required: The weight amount for this stop. - `unit` 'kilogram' | 'pound' | 'metric-ton', required: The weight unit in which the amount is specified. - `notes` string, nullable: Notes for the stop - `barcodes` string[]: List of barcode IDs associated with this stop - `customProperties` object, nullable: Key-value pairs of custom stop properties for this stop. The keys must be unique and match a custom stop property defined in your team. - `timing` object, nullable - `timeWindows` object[]: Up to two ordered arrival windows for this stop. An empty array clears the windows. A single window may have one null bound; two windows must have both bounds set. Windows must not overlap or touch, and their total span must not exceed 24 hours. - `earliestAttemptTime` object, nullable, required: Time of day in hours and minutes. Use a 24 hour clock. - `hour` integer, required: Hour of the day - `minute` integer, required: Minute of the hour - `latestAttemptTime` object, nullable, required: Time of day in hours and minutes. Use a 24 hour clock. - `hour` integer, required: Hour of the day - `minute` integer, required: Minute of the hour - `earliestAttemptTime` object, nullable: Time of day in hours and minutes. Use a 24 hour clock. - `hour` integer, required: Hour of the day - `minute` integer, required: Minute of the hour - `latestAttemptTime` object, nullable: Time of day in hours and minutes. Use a 24 hour clock. - `hour` integer, required: Hour of the day - `minute` integer, required: Minute of the hour - `estimatedAttemptDuration` integer, nullable: Duration in seconds of the activity in this stop, only set if you want to override the default. This can be set up to 8 hours. ## Response `200` Success - object: Success - `pending` boolean, required - `stop` StopSchema, required: A stop of a plan, can be related to a route. - `id` string, required - `address` object, required: The address of the stop. - `address` string, required: The address of the stop. - `addressLineOne` string, required: The first line of the address. - `addressLineTwo` string, required: The second line of the address. - `latitude` number, nullable, required: The latitude of the address in decimal degrees. - `longitude` number, nullable, required: The longitude of the address in decimal degrees. - `placeId` string, nullable, required: The identifier of the place corresponding to this stop on Google Places - `placeTypes` string[], required: Array of strings that is provided by the Google AutoCompleteAPI - `barcodes` string[], required: List of Barcode IDs associated with the stop. - `allowedDrivers` string[], required: The driver IDs that can be assigned to this stop - `estimatedTravelDuration` number, nullable, required: Estimated time that the driver will take to arrive at this stop from the previous stop in seconds. - `estimatedTravelDistance` number, nullable, required: The distance in meters between the previous stop and this stop. - `notes` string, nullable, required: Notes for the stop. - `packageCount` number, nullable, required: The number of packages. - `weight` object, nullable, required: Weight information for the stop. - `amount` number, required: The weight amount for this stop. - `unit` 'kilogram' | 'pound' | 'metric-ton', required: The weight unit in which the amount is specified (defined at team's capacity unit). - `type` 'start' | 'stop' | 'end', required: The type of the stop. `start` is the first stop of the route, `stop` is a stop in the middle of the route, and `end` is the last stop of the route. - `packageLabel` string, nullable, required: The label of the package. - `stopPosition` number, nullable, required: The position of the stop in the route. - `trackingLink` string, nullable, required: The recipient tracking link. - `webAppLink` string, required: The web app link. - `orderInfo` object, required: The order information of the stop. - `products` string[], required: The products of the stop. - `invoiceNumber` string, nullable, required: Invoice number associated with the order. - `sellerName` string, nullable, required: Name of the seller where the order is from. - `sellerOrderId` string, nullable, required: Id of the seller where the order is from. - `sellerWebsite` string, nullable, required: Website of the seller where the order is from. - `placeInVehicle` object, nullable, required: The position of the package in the vehicle. - `x` 'left' | 'right', nullable, required: The x position of the package. - `y` 'front' | 'back' | 'middle', nullable, required: The y position of the package. - `z` 'floor' | 'shelf', nullable, required: The z position of the package. - `recipient` object, required: The recipient of the stop. - `name` string, nullable, required: The name of the recipient. - `email` string, nullable, required: The email of the recipient. - `phone` string, nullable, required: The phone of the recipient. - `externalId` string, nullable, required: The external id of the recipient. - `activity` 'delivery' | 'pickup' - `deliveryInfo` object, nullable, required: The delivery information of the stop. - `attempted` boolean, required: Whether the stop was attempted. - `attemptedAt` number, nullable, required: When the stop was attempted in seconds since epoch. - `timeAtStopInfo` union, required - object - `status` 'available', required - `value` object, required: Grouped time-at-stop data. - `arrivedAt` number, nullable, required: When the driver arrived at the stop in seconds since epoch. - `departedAt` number, nullable, required: When the driver departed from the stop in seconds since epoch. - `isEstimated` boolean, nullable, required: Whether the time at stop was estimated rather than directly measured. - object - `status` 'restricted', required - `requiredFeature` string - `upgradeUrl` string - `restrictionCode` 'subscription_not_supported' - object - `status` 'pending', required - `pendingReason` 'not_yet_arrived' - `attemptedLocation` object, nullable, required: A location. - `latitude` number, required: The latitude of the location. - `longitude` number, required: The longitude of the location. - `driverProvidedInternalNotes` string, nullable, required: Internal notes provided by the driver. - `driverProvidedRecipientNotes` string, nullable, required: Recipient notes provided by the driver. - `photoUrls` string[], required: URLs of proof of delivery photos. - `recipientProvidedNotes` string, nullable, required: Notes from recipient - `signatureUrl` string, nullable, required: URL of the signature. - `signeeName` string, nullable, required: Name of the signee. - `succeeded` boolean, required: Whether the stop was succeeded. - `state` 'delivered_to_recipient' | 'delivered_to_third_party' | 'delivered_to_mailbox' | 'delivered_to_safe_place' | 'delivered_to_pickup_point' | 'delivered_other' | 'picked_up_from_customer' | 'picked_up_unmanned' | 'picked_up_from_locker' | 'picked_up_other' | 'failed_not_home' | 'failed_cant_find_address' | 'failed_no_parking' | 'failed_no_time' | 'failed_package_not_available' | 'failed_other' | 'failed_missing_required_proof' | 'failed_payment_not_received' | 'unattempted', required: The state of the delivery. - `paymentOnDelivery` object, nullable, required: The payment due upon delivery also known as "Cash on Delivery". - `amount` integer, nullable, required: The amount *in minor units* (e.g. cents) to be collected upon delivery. - `currency` string, required: The payment's currency in ISO 4217 standard. - `proofOfAttemptRequirements` object, required: The proof of attempt requirements of the stop. - `enabled` boolean, nullable, required: Whether the proof of attempt is enabled.This only works if the team subscription has access to proof of delivery - `plan` string, required - `route` RouteSchema, required: A route. - `id` string, required - `title` string, required: The title of the route. - `stopCount` number, required: The number of stops in the route. - `driver` string, required - `state` object, nullable, required: The state of a route. - `completed` boolean, required: Whether the route is completed. - `completedAt` number, nullable, required: The timestamp the route was completed at. - `distributed` boolean, required: Whether the route is distributed. - `distributedAt` number, nullable, required: The timestamp the route was distributed at. - `notifiedRecipients` boolean, required: Whether the recipients were notified. - `notifiedRecipientsAt` number, nullable, required: The timestamp the recipients were notified at. - `started` boolean, required: Whether the route is started. - `startedAt` number, nullable, required: The timestamp the route was started at. - `plan` string, required - `eta` union, required - object - `status` 'available', required - `value` object, required: The estimated time of arrival data of the stop. - `estimatedArrivalAt` number, required: The estimated time in seconds since epoch. - `estimatedLatestArrivalAt` number, required: The latest estimated time in seconds since epoch. - `estimatedEarliestArrivalAt` number, required: The earliest estimated time in seconds since epoch. - object - `status` 'restricted', required - `requiredFeature` string - `upgradeUrl` string - `restrictionCode` 'subscription_not_supported' - object - `status` 'pending', required - `pendingReason` 'not_optimized' - `timing` object, required: The timing data of the stop. - `timeWindows` object[], required: Ordered arrival windows for this stop. - `earliestAttemptTime` TimeOfDaySchema, required: Time of day in hours and minutes. Uses a 24 hour clock. - `hour` integer, required: Hour of the day - `minute` integer, required: Minute of the hour - `latestAttemptTime` TimeOfDaySchema, required: Time of day in hours and minutes. Uses a 24 hour clock. - `hour` integer, required: Hour of the day - `minute` integer, required: Minute of the hour - `estimatedAttemptDuration` number, nullable, required: Time that the driver estimates to spend on the stop to do his job (deliver a parcel, visit a client, etc) in seconds. - `earliestAttemptTime` TimeOfDaySchema, required: Time of day in hours and minutes. Uses a 24 hour clock. - `hour` integer, required: Hour of the day - `minute` integer, required: Minute of the hour - `latestAttemptTime` TimeOfDaySchema, required: Time of day in hours and minutes. Uses a 24 hour clock. - `hour` integer, required: Hour of the day - `minute` integer, required: Minute of the hour - `optimizationOrder` 'first' | 'last' | 'default' - `customProperties` object, nullable, required: Custom properties of the stop, can be used to store additional information. - `clientId` string, nullable, required: The associated Client ID of the Spoke Connect - `serviceInfo` union, required: Service offering data for this stop. - object - `status` 'available', required - `value` union, required: Service offering data for this stop. - object: Service offering data when a service is assigned to the stop. - `identifier` string, required: The service offering identifier, as configured in Spoke Dispatch, captured at assignment time. Not currently discoverable through the public API. - `name` string, required: The human-readable service name. - `slaStartsAt` number, required: The SLA start time in seconds since epoch. - `slaDueDate` object, required: The computed SLA due date in the team's timezone. - … - `slaDueTime` TimeOfDaySchema, required: Time of day in hours and minutes. Uses a 24 hour clock. - … - `deliveryHorizon` object, required: The delivery horizon for this service. - … - `price` object, required: Price for this service at assignment time. - … - `hasPaymentOnDelivery` boolean, required: Whether cash on delivery is enabled via the service. - `definedAt` number, required: When the service was assigned in seconds since epoch. - object: Service data when only an SLA start time is set. - `identifier` unknown, required - `slaStartsAt` number, required: The SLA start time in seconds since epoch. - object - `status` 'empty', required - object - `status` 'restricted', required - `requiredFeature` string - `upgradeUrl` string - `restrictionCode` 'subscription_not_supported' ## Other responses - `400`: The request has errors. Either syntactic or semantic - `401`: Unauthorized - `403`: The plan is no longer accessible or the stop contains fields that require upgrading your team subscription. - `404`: Not Found - `409`: The plan's optimization is in progress. - `412`: Drivers must be part of the plan to be referenced by stops - `422`: The stop is unprocessable. - `500`: An internal server error occurred - `default`: The default error model --- [API](https://skmtc.dev/spoke/apis/spoke-api.md) - [All operations](https://skmtc.dev/spoke/apis/spoke-api/llms.txt) - [OpenAPI document](https://skmtc.dev/spoke/apis/spoke-api/revisions/a09d9194ae1c?raw)