Document order operations: payments, edits, stock, booking slots and comment visibility

postman/collections/Fleetbase API/Entities/Create an Entity.request.yaml

@@ -1,6 +1,8 @@
 $kind: http-request
 description: |-
   Creates an entity such as a parcel, package, or item. Attach it to a payload and optionally set a destination or waypoint within that payload route.
+
+  When the entity belongs to an order's payload, the order's status decides whether its items can still change: once a driver has the order, or the order is finished, items are locked; once it is ready, items can only be removed. A locked change returns `422` `{ "error": "...", "locked": { "items": "<reason>" } }`, and an accepted change broadcasts `order.changed`. Requires Fleet-Ops with fleetbase/fleetops#394 (release v0.6.72).
 url: "{{base_url}}/{{namespace}}/entities"
 method: POST
 headers:

postman/collections/Fleetbase API/Entities/Delete a Entity.request.yaml

@@ -1,5 +1,8 @@
 $kind: http-request
-description: Delete an Entity.
+description: |-
+  Delete an Entity.
+
+  When the entity belongs to an order's payload, the order's status decides whether its items can still change: once a driver has the order, or the order is finished, items are locked; once it is ready, items can only be removed. A locked change returns `422` `{ "error": "...", "locked": { "items": "<reason>" } }`, and an accepted change broadcasts `order.changed`. Requires Fleet-Ops with fleetbase/fleetops#394 (release v0.6.72).
 url: "{{base_url}}/{{namespace}}/entities/:id"
 method: DELETE
 headers:

postman/collections/Fleetbase API/Entities/Update a Entity.request.yaml

@@ -1,6 +1,8 @@
 $kind: http-request
 description: |-
   Updates an entity's descriptive fields, payload assignment, destination, dimensions, weight, pricing, or metadata.
+
+  When the entity belongs to an order's payload, the order's status decides whether its items can still change: once a driver has the order, or the order is finished, items are locked; once it is ready, items can only be removed. A locked change returns `422` `{ "error": "...", "locked": { "items": "<reason>" } }`, and an accepted change broadcasts `order.changed`. Requires Fleet-Ops with fleetbase/fleetops#394 (release v0.6.72).
 url: "{{base_url}}/{{namespace}}/entities/:id"
 method: PUT
 headers:

postman/collections/Fleetbase API/Orders/.resources/Update an Order.resources/examples/Unprocessable Content.example.yaml

@@ -0,0 +1,37 @@
+$kind: http-example
+request:
+  url: "{{base_url}}/{{namespace}}/orders/:id"
+  method: PUT
+  headers:
+    Content-Type: application/json
+    Accept: application/json
+  pathVariables:
+    id: "order_7YqM3KpL2n"
+  body:
+    type: json
+    content: |-
+      {
+        "scheduled_at": "2026-10-13T15:00:00Z",
+        "payload": {
+          "entities_mode": "replace",
+          "entities": [
+            { "id": "entity_4Fr8Kq2Lp1", "name": "Cold Brew", "quantity": 3 }
+          ]
+        }
+      }
+response:
+  statusCode: 422
+  statusText: Unprocessable Content
+  headers:
+    Content-Type: application/json
+  body:
+    type: json
+    content: |-
+      {
+        "error": "Items cannot be changed once a driver has the order. The schedule cannot be changed once a driver has the order.",
+        "locked": {
+          "items": "Items cannot be changed once a driver has the order.",
+          "schedule": "The schedule cannot be changed once a driver has the order."
+        }
+      }
+order: 2000

postman/collections/Fleetbase API/Orders/.resources/definition.yaml

@@ -1,4 +1,15 @@
 $kind: collection
 description: |-
   Orders represent work to be planned, dispatched, tracked, and completed. Use order endpoints to create delivery or service jobs, assign resources, manage status, capture proof of delivery, and record activity.
+
+  ## Ad hoc orders
+
+  A driver assigned to an order, by dispatch or auto-assign, has the order; there is nothing for the driver to accept. Only ad hoc orders (`adhoc: true`) are offered to drivers: dispatching one notifies the drivers within `adhoc_distance`, and Fleet-Ops notifies them again every minute until a driver takes it. The first driver to take it does so with `Start an Order`, sending their driver id as `assign`.
+
+  ## Realtime events
+
+  Order changes are broadcast on the socket channels below. Every event has the envelope `{ id, api_version, event, created_at, data }`. These events require Fleet-Ops with fleetbase/fleetops#394 (release v0.6.72).
+
+  - `order.changed`: the order's route, items, contact, schedule, notes or amounts were edited after it was placed (through `Update an Order`, `Update a Payload`, the entity endpoints, the console or Storefront). Channels: `order.{public_id}` and `order.{uuid}`, `driver.{public_id}` and `driver.{uuid}` of the assigned driver, `customer.{public_id}` and `company.{uuid}`. Data: `{ id, changes, summary, dropoff: { id, address, location }, cod_amount, total, currency, changed_by, changed_at }`; `changes` lists the parts that changed (`pickup`, `dropoff`, `return`, `waypoints`, `items`, `schedule`, `contact`, `notes`, `cod_amount`, ...) and `summary` is one readable line. When the change concerns the driver, the assigned driver also gets an `order_changed` push.
+  - `order.driver_unassigned`: a driver was taken off the order (unassigned or replaced). Channels: `driver.{public_id}` and `driver.{uuid}` of the previous driver, and `company.{uuid}`. Data: `{ id, driver }`. The previous driver also gets an `order_unassigned` push.
 order: 8000

postman/collections/Fleetbase API/Orders/Cancel an Order.params.yaml

@@ -0,0 +1,5 @@
+$kind: params
+fields:
+  - name: reason
+    type: string
+    description: "Why the order is canceled. Recorded as the canceled status details and sent with the canceled notifications. Trimmed to 1000 characters."

postman/collections/Fleetbase API/Orders/Cancel an Order.request.yaml

@@ -1,10 +1,21 @@
 $kind: http-request
-description: Cancels an order without deleting the order resource.
+description: |-
+  Cancels an order without deleting the order resource.
+
+  An optional `reason` (body or query string) becomes the details of the canceled tracking status and is sent with the canceled notifications: the assigned driver's push carries it as `reason`, so the Navigator app can show why the order was canceled. A reason is trimmed to 1000 characters. The `reason` requires Fleet-Ops with fleetbase/fleetops#394 (release v0.6.72); earlier versions ignore it.
 url: "{{base_url}}/{{namespace}}/orders/:id/cancel"
 method: DELETE
+headers:
+  Content-Type: application/json
 pathVariables:
   - key: id
     value: "{{order_id}}"
     description: (Required) The id of the `Order`.
+body:
+  type: json
+  content: |-
+    {
+        "reason": "The customer asked to cancel."
+    }
 examples: .resources/Cancel an Order.resources/examples
 order: 13000

postman/collections/Fleetbase API/Orders/Update an Order.params.yaml

@@ -17,7 +17,15 @@ fields:
     description: Replacement waypoint list. When sent empty with route endpoint fields, existing waypoints are removed.
   - name: entities
     type: array of objects
-    description: Replacement entities for the order payload.
+    description: Entities for the order payload. Appended to the payload's entities, or with `entities_mode` `replace`, the payload's full list.
+  - name: entities_mode
+    type: enum
+    values: ["append", "replace"]
+    default: append
+    description: "`replace` (or `sync`) makes `entities` the payload's full list: entries with the `id` of one of the payload's entities update it, entries without one are created, and entities left out are deleted. Also read from `payload.entities_mode`."
+  - name: cod_amount
+    type: number
+    description: "Cash to collect on delivery, also accepted as `payload.cod_amount`. `0` clears it; a value that isn't numeric is ignored."
   - name: service_quote
     type: string
     description: Service quote ID to purchase and attach to the order.

postman/collections/Fleetbase API/Orders/Update an Order.request.yaml

@@ -1,6 +1,19 @@
 $kind: http-request
 description: |-
   Updates an order and returns the updated order resource. You can update order metadata, notes, status, assignment fields, scheduling fields, proof-of-delivery settings, and payload details.
+
+  What can still change depends on the order's status. A change the status locks is refused with `422` and nothing is written: `{ "error": "...", "locked": { "<field>": "<reason>" } }`. The fields are `pickup`, `dropoff`, `return`, `waypoints`, `items` (the payload's entities), `schedule` (`scheduled_at`), `contact` (`customer`), `notes` and `cod_amount`:
+
+  - Open (`created`, `pending`, `accepted`, `confirmed`, `preparing`, or a custom status before dispatch): everything can change.
+  - Ready (`ready`, `pickup_ready`, `ready_for_pickup`): items can only be removed and the schedule can only move earlier; everything else can change.
+  - With a driver (dispatched, started, `enroute`, `driver_*` and similar, or a custom status after dispatch): the route (the driver is rerouted), contact, notes and `cod_amount` can change; items and schedule are locked.
+  - Finished (`completed`, `canceled`, `expired`, or the order config's complete or terminal activity): nothing can change.
+
+  Entities sent with the payload are appended by default. With `entities_mode` `replace` (at the top level or in `payload`), the list sent becomes the payload's full list: entries with an `id` of one of the payload's entities update it, entries without one are created, and entities left out are deleted. `cod_amount` is accepted at the top level or in `payload`, and `0` is kept (it clears the cash to collect). The order's current waypoint only moves when the route changed, so an order under way keeps its stop.
+
+  An edit that changes anything broadcasts the realtime event `order.changed` (see the Orders folder) and, when the change concerns the driver, sends the assigned driver an `order_changed` push.
+
+  The status guard, `entities_mode` and top-level `cod_amount` require Fleet-Ops with fleetbase/fleetops#394 (release v0.6.72).
 url: "{{base_url}}/{{namespace}}/orders/:id"
 method: PUT
 pathVariables:

postman/collections/Fleetbase API/Payloads/Update a Payload.params.yaml

@@ -14,7 +14,12 @@ fields:
     description: Replacement waypoint list. Sending route endpoint fields without waypoints removes existing waypoints.
   - name: entities
     type: array of objects
-    description: Replacement entities, packages, or items attached to the payload.
+    description: Entities, packages, or items for the payload. Appended to its entities, or with `entities_mode` `replace`, the payload's full list.
+  - name: entities_mode
+    type: enum
+    values: ["append", "replace"]
+    default: append
+    description: "`replace` (or `sync`) makes `entities` the payload's full list: entries with the `id` of one of the payload's entities update it, entries without one are created, and entities left out are deleted."
   - name: type
     type: string
     description: Payload type.
@@ -23,7 +28,7 @@ fields:
     description: Provider identifier associated with the payload.
   - name: cod_amount
     type: currency
-    description: Cash-on-delivery amount.
+    description: Cash-on-delivery amount. `0` is kept and clears the cash to collect.
   - name: cod_currency
     type: currency
     description: Three-letter currency code for `cod_amount`.

postman/collections/Fleetbase API/Payloads/Update a Payload.request.yaml

@@ -1,6 +1,10 @@
 $kind: http-request
 description: |-
   Updates a payload's route endpoints, waypoints, entities, cash-on-delivery settings, or metadata. The response returns the updated payload with route and entity data.
+
+  Entities are appended by default; with `entities_mode` `replace` the list sent becomes the payload's full list (entries with the `id` of one of its entities update it, entries without one are created, and entities left out are deleted). A `cod_amount` of `0` is kept, clearing the cash to collect; other empty values are ignored as before.
+
+  When the payload belongs to an order, the order's status decides what can still change, as for `Update an Order`: a locked change returns `422` `{ "error": "...", "locked": { "<field>": "<reason>" } }` and nothing is written, and an accepted change broadcasts `order.changed`. Requires Fleet-Ops with fleetbase/fleetops#394 (release v0.6.72).
 url: "{{base_url}}/{{namespace}}/payloads/:id"
 method: PUT
 pathVariables:

postman/collections/Fleetbase Core API/Chat Channels/.resources/object.yaml

@@ -8,10 +8,30 @@ example: |
     "created_by": "user_8xP2L1d",
     "name": "Dispatch updates",
     "title": "Dispatch updates",
-    "last_message": null,
+    "last_message": {
+      "id": "chat_message_3Hk9mL2",
+      "chat_channel": "chat_channel_5VUl2v4",
+      "content": "Order updated: Drop-off changed to 8 Marina View",
+      "sender": null,
+      "system": true,
+      "meta": { "system": true, "kind": "order_updated" },
+      "attachments": [],
+      "receipts": [],
+      "updated_at": "2026-10-13T09:30:00Z",
+      "created_at": "2026-10-13T09:30:00Z"
+    },
     "slug": "dispatch-updates",
     "feed": [],
-    "participants": [],
+    "participants": [
+      {
+        "id": "chat_participant_2Lm4kQ7",
+        "name": "Ada Buyer",
+        "role": "customer",
+        "meta": { "role": "customer" },
+        "is_online": true,
+        "last_seen_at": "2026-10-13T09:29:00Z"
+      }
+    ],
     "meta": {},
     "updated_at": "2026-05-07T09:30:00Z",
     "created_at": "2026-05-07T09:30:00Z",
@@ -32,7 +52,7 @@ fields:
     description: "Display title for the channel."
   - name: last_message
     type: object
-    description: "Most recent chat message for the channel, when available."
+    description: "Most recent chat message for the channel, when available. Messages carry `system` (true for messages the system posts, such as `order_updated` or `address_change_requested`, read from `meta.system`) and `meta` (with `kind` for system messages). `sender` is the sending participant, or null for a message without one. Requires Core API with fleetbase/core-api#306 (release v1.6.69)."
   - name: unread_count
     type: integer
     description: "Unread message count for the current session user when session context is available."
@@ -44,10 +64,10 @@ fields:
     description: "Messages and feed entries returned for the channel."
   - name: participants
     type: array of objects
-    description: "Chat participants in the channel."
+    description: "Chat participants in the channel. Each participant has `role` and `meta`: `role` is read from `meta.role` and is `customer`, `driver`, `store` or `system` when one of those was recorded (order chats record it), else null; `meta` is the participant's metadata (an empty object when unset). Requires Core API with fleetbase/core-api#306 (release v1.6.69)."
   - name: meta
     type: object
-    description: "Arbitrary metadata stored with the channel."
+    description: "Arbitrary metadata stored with the channel. Storefront order chats carry `storefront_order_uuid`, `storefront_order_id`, `order_public_id` and `kind` (`group` for the customer and driver thread, `customer` for the customer and store thread)."
   - name: updated_at
     type: timestamp
     description: "Time the channel was last updated."

postman/collections/Fleetbase Core API/Chat Channels/Send Message.request.yaml

@@ -1,6 +1,8 @@
 $kind: http-request
 description: |-
   Sends a message to a chat channel as an existing chat participant. File IDs can be included to attach previously uploaded files to the message.
+
+  The response is the chat message, with `sender` (the participant, including its `role`), `system` and `meta` (see the Chat Channel object).
 url: "{{base_url}}/{{namespace}}/chat-channels/:id/send-message"
 method: POST
 pathVariables:

postman/collections/Fleetbase Core API/Comments/.resources/definition.yaml

@@ -1,4 +1,8 @@
 $kind: collection
 description: |-
   Comments attach discussion to Fleetbase resources or reply to existing comments. Use comment endpoints to create threaded context around orders, files, operational records, and other subject models.
+
+  Comments are `internal` (notes for the organization's own users) or `customer` (may be shown to customers and drivers). The public API only returns customer-visible comments.
+
+  New comments are broadcast as the realtime event `comment.created` on `company.{uuid}` and, for customer-visible comments, on the subject's channels (`{subject type}.{public_id}` and `{subject type}.{uuid}`, e.g. `order.order_7YqM3KpL2n`). Payload: `{ id, event, created_at, subject_id, data }`, where `data` is the comment and `subject_id` the subject's public ID. Requires Core API with fleetbase/core-api#306 (release v1.6.69).
 order: 4000

postman/collections/Fleetbase Core API/Comments/.resources/object.yaml

@@ -7,7 +7,8 @@ example: |
     "id": "comment_8JVZr4q",
     "content": "Please confirm the delivery window.",
     "tags": [],
-    "meta": {},
+    "meta": { "visibility": "customer" },
+    "visibility": "customer",
     "author": {
       "id": "user_8xP2L1d",
       "name": "Alex Rivera"
@@ -31,12 +32,16 @@ fields:
   - name: meta
     type: object
     description: "Arbitrary metadata stored with the comment."
+  - name: visibility
+    type: enum
+    values: ["internal", "customer"]
+    description: "Who may see the comment, from `meta.visibility`: `internal` comments are notes for the organization's own users and never appear on the public API, `customer` comments may be shown to customers and drivers. A comment without a visibility is `customer`. Requires Core API with fleetbase/core-api#306 (release v1.6.69)."
   - name: author
     type: object
     description: "User that authored the comment."
   - name: replies
     type: array of objects
-    description: "Nested replies to the comment."
+    description: "Nested replies to the comment. On the public API, internal replies are left out."
   - name: editable
     type: boolean
     description: "Whether the current session user can edit the comment."

postman/collections/Fleetbase Core API/Comments/Create Comment.params.yaml

@@ -25,3 +25,7 @@ fields:
   - name: parent
     type: string
     description: "Public ID of the parent comment when creating a reply."
+  - name: visibility
+    type: enum
+    values: ["internal", "customer"]
+    description: "Who may see the comment; any other value returns `422`. Stored as `meta.visibility`. When omitted, a reply takes its parent's visibility, a comment on an order created through this API is `customer` (and `internal` when written from the console), and a comment on any other subject has none, which counts as `customer`. Requires Core API with fleetbase/core-api#306 (release v1.6.69)."

postman/collections/Fleetbase Core API/Comments/Create Comment.request.yaml

@@ -1,6 +1,8 @@
 $kind: http-request
 description: |-
   Creates a comment on a subject resource or as a reply to an existing comment. Provide either a subject reference or a parent comment ID with the comment content.
+
+  Set `visibility` to `internal` for a note only the organization's users should see, or `customer` for one customers and drivers may see (see the Comment object for the default). Internal comments are not returned by `Query Comments` or `Retrieve Comment`. Every new comment broadcasts the realtime event `comment.created` (see the Comments folder). Requires Core API with fleetbase/core-api#306 (release v1.6.69).
 url: "{{base_url}}/{{namespace}}/comments"
 method: POST
 body:

postman/collections/Fleetbase Core API/Comments/Query Comments.request.yaml

@@ -1,6 +1,6 @@
 $kind: http-request
 description: |-
-  Returns comments for the current organization. Use query parameters to filter, sort, and paginate the result set.
+  Returns comments for the current organization. Use query parameters to filter, sort, and paginate the result set. Internal comments (`visibility` `internal`) and internal replies are left out. Requires Core API with fleetbase/core-api#306 (release v1.6.69).
 url: "{{base_url}}/{{namespace}}/comments"
 method: GET
 queryParams:

postman/collections/Fleetbase Core API/Comments/Retrieve Comment.request.yaml

@@ -1,6 +1,6 @@
 $kind: http-request
 description: |-
-  Retrieves a comment by ID, including its author and any nested replies returned by the API resource.
+  Retrieves a comment by ID, including its author and any nested replies returned by the API resource. An internal comment returns `404` (`Comment resource not found.`), and internal replies are left out. Requires Core API with fleetbase/core-api#306 (release v1.6.69).
 url: "{{base_url}}/{{namespace}}/comments/:id"
 method: GET
 pathVariables:

postman/collections/Fleetbase Storefront API/Checkout/Before Cash Pickup Checkout.request.yaml

@@ -1,6 +1,8 @@
 $kind: http-request
 description: |-
   Initializes a cash (cash-on-delivery) pickup checkout. A pickup checkout with the cash gateway needs no delivery service quote, so the `service_quote` parameter is omitted. The response returns the checkout id and token; no gateway client data is prepared for cash.
+
+  Like every checkout, it holds stock for products that track inventory and can be refused with `422` `cart_items_unavailable` or `booking_slot_unavailable` (see `Before`).
 url: "{{base_url}}/{{api_prefix}}/{{namespace}}/checkouts/before"
 method: GET
 queryParams: