PATCH /api/v1/businesses/{id}/plans/{plan}/stops/{order}

PATCH/api/v1/businesses/{id}/plans/{plan}/stops/{order}

Same manual adjustment/publication warning contract. Does not edit actual timestamps. Integration permission: planning.edit. Administrator membership grants management access only to this business.

Authentication

Authorized business administrator session, or a business API key with planning.edit.

Parameters

Parameter	In	Type	Description
`id`Required	path	`string`	Authorized business context. Never inferred from client record IDs.Format: uuid
`plan`Required	path	`string`
`order`Required	path	`string`

Request

Field	Type	Description & constraints
`order_id`	`string`	Resource-specific value; see the related workflow and schema.
`scheduled_at`	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`vehicle_id`	`string`	Assigned or selected vehicle ID in this business.
`driver_id`	`string \| null`	Assigned driver ID; stop-specific assignments can change after a handover.
`position`	`integer`	Resource-specific value; see the related workflow and schema.
`status`	`created \| on_road \| in_progress \| completed \| unable_to_complete \| cancelled`	Current execution or operation state. Planned/unplanned is separate from execution.

Example JSON body

{
  "order_id": "job-1001",
  "scheduled_at": "2026-11-02T09:30:00Z",
  "vehicle_id": "van-01",
  "driver_id": "driver-01",
  "position": 0,
  "status": "created"
}

Request schema

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string"
    },
    "scheduled_at": {
      "type": "string",
      "format": "date-time",
      "description": "RFC3339 UTC instant or explicit offset; business wall times are resolved separately."
    },
    "vehicle_id": {
      "type": "string"
    },
    "driver_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "position": {
      "type": "integer"
    },
    "status": {
      "enum": [
        "created",
        "on_road",
        "in_progress",
        "completed",
        "unable_to_complete",
        "cancelled"
      ]
    }
  }
}

Example request

Replace synthetic identifiers and credentials. Example dates, coordinates, revisions, and IDs are not production defaults. Read the workflow guide before making a write.

curl --request PATCH 'https://route-api.okok.space/api/v1/businesses/11111111-1111-4111-8111-111111111111/plans/plan-01/stops/job-1001' \
  --header 'Authorization: Bearer REPLACE_WITH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"order_id":"job-1001","scheduled_at":"2026-11-02T09:30:00Z","vehicle_id":"van-01","driver_id":"driver-01","position":0,"status":"created"}'

Responses

Examples illustrate the documented shape; optional fields and current state can differ. JSON extraction/body-limit errors may be plain text.

200 · Successful response

application/json

Field	Type	Description & constraints
`id`Required	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`vehicle_id`Required	`string`	Assigned or selected vehicle ID in this business.
`driver_id`	`string \| null`	Assigned driver ID; stop-specific assignments can change after a handover.
`revision`Required	`integer`	Current version used to detect stale edits or publication.
`state`Required	`planning \| published \| superseded`	Planning/published version state or event visibility state.
`start_at`	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`end_at`	`string`	RFC3339 UTC instant or explicit offset; business wall times are resolved separately.Format: date-time
`stops`Required	`array<object>`	Ordered planned route stops.
`return_leg`	`object`	Resource-specific value; see the related workflow and schema.
`warnings`	`array<string>`	Constraint warnings requiring review where applicable.
`unplanned_order_ids`	`array<string>`	Resource-specific value; see the related workflow and schema.
`published`	`object \| null`	Resource-specific value; see the related workflow and schema.
`received_at`	`string \| null`	Resource-specific value; see the related workflow and schema.

Illustrative response

{
  "id": "example-id",
  "vehicle_id": "van-01",
  "driver_id": "driver-01",
  "revision": 1,
  "state": "planning",
  "start_at": "2026-11-02T08:00:00Z",
  "end_at": "2026-11-02T16:00:00Z",
  "stops": [
    {}
  ],
  "return_leg": {},
  "warnings": [
    "example"
  ],
  "unplanned_order_ids": [
    "example"
  ],
  "published": {},
  "received_at": "2026-11-02T09:00:00Z"
}

Response schema

{
  "$ref": "#/components/schemas/Plan"
}

401 · Missing/invalid/revoked token

application/json

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-specific value; see the related workflow and schema.

Illustrative response

{
  "error": {
    "code": "unauthorized",
    "message": "Missing/invalid/revoked token"
  }
}

Response schema

{
  "$ref": "#/components/schemas/Error"
}

403 · Business membership or required API-key scope denied

application/json

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-specific value; see the related workflow and schema.

Illustrative response

{
  "error": {
    "code": "unauthorized",
    "message": "Business membership or required API-key scope denied"
  }
}

Response schema

{
  "$ref": "#/components/schemas/Error"
}

404 · Record not found in authorized business

application/json

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-specific value; see the related workflow and schema.

Illustrative response

{
  "error": {
    "code": "not_found",
    "message": "Record not found in authorized business"
  }
}

Response schema

{
  "$ref": "#/components/schemas/Error"
}

409 · Duplicate identifier, stale revision, expired reservation, protected publication or unavailable capacity

application/json

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-specific value; see the related workflow and schema.

Illustrative response

{
  "error": {
    "code": "conflict",
    "message": "Duplicate identifier, stale revision, expired reservation, protected publication or unavailable capacity"
  }
}

Response schema

{
  "$ref": "#/components/schemas/Error"
}

422 · Domain validation rejected the operation

application/json

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-specific value; see the related workflow and schema.

Illustrative response

{
  "error": {
    "code": "validation",
    "message": "Domain validation rejected the operation"
  }
}

Response schema

{
  "$ref": "#/components/schemas/Error"
}

503 · Required persistence, map/routing or other infrastructure unavailable

application/json

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-specific value; see the related workflow and schema.

Illustrative response

{
  "error": {
    "code": "unavailable",
    "message": "Required persistence, map/routing or other infrastructure unavailable"
  }
}

Response schema

{
  "$ref": "#/components/schemas/Error"
}

← All endpoints Integration workflows →

Move/reorder/change draft stop

Authentication

Parameters

Request

Example JSON body

Example request

Responses

200 · Successful response

401 · Missing/invalid/revoked token

403 · Business membership or required API-key scope denied

404 · Record not found in authorized business

409 · Duplicate identifier, stale revision, expired reservation, protected publication or unavailable capacity

422 · Domain validation rejected the operation

503 · Required persistence, map/routing or other infrastructure unavailable