--- title: "Update an existing stop" method: PATCH path: "/plans/{planId}/stops/{stopId}" tags: ["Stops"] --- # Update an existing stop `PATCH /plans/{planId}/stops/{stopId}` ## Request - Base URL: `https://api.spoke.com/public/v1` - URL: `https://api.spoke.com/public/v1/plans/{planId}/stops/{stopId}` - Auth: HTTP basic - TypeScript: (a function with typed inputs; its response is checked against the schema) Does not support updating a stop's location, nor the `clientId`. To do so, delete the stop and create a new one. If the plan is not writable, the request will fail, prefer using the [Update Live Stops API](#tag/Live-Stops/operation/updateLiveStop) instead. ## Path parameters - `planId` string, required - `stopId` string, required ## Request body - object: The request body for updating a stop. All the values present in the request will update the stop value, if you wish to update only certain fields, only set them and do not set the others. Any fields not set will not be updated. - `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. - `serviceInfo` object, nullable: Service offering data for this stop. Combines the service identifier and SLA start time. On update, set the whole object to `null` to clear all service info. - `identifier` string, nullable: The identifier of a service offering to assign to this stop. Must match the identifier of a current, non-deleted service offering defined on your team. On update, set it to `null` to remove an assigned service; on create, omit it to leave the stop without a service. - `slaStartsAt` integer, nullable: The SLA start time for this stop, in seconds since Unix epoch. Allows backdating when the actual order time is known. Can be provided with or without a service identifier. - `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` The updated stop - StopSchema: 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. - `day` integer, required: The day of the date. - `month` integer, required: The month of the date. - `year` integer, required: The year of the date. - `slaDueTime` 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 - `deliveryHorizon` object, required: The delivery horizon for this service. - `unit` union, required: The time unit of the delivery horizon. Known: `days`, `hours`. - … - `value` number, required: The number of time units in the delivery horizon. - `price` object, required: Price for this service at assignment time. - `value` number, required: Price in minor currency units (e.g. cents). - `currency` union, required: 3-letter ISO 4217 currency code. - … - `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 (syntactic or semantic), or the service is not eligible for the stop (activity, operating area, or depot availability). - `401`: Unauthorized - `403`: The plan is no longer accessible or the stop contains fields that require upgrading your team subscription. - `404`: The plan, stop, or referenced service offering could not be found. - `409`: The plan is not writable. - `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)