---
title: "[preview] Upsert orders"
method: POST
path: "/preview/fleet/orders/batch"
tags: ["Preview APIs"]
---

# \[preview\] Upsert orders

`POST /preview/fleet/orders/batch`

## Request

- Base URL: `https://api.samsara.com`
- URL: `https://api.samsara.com/preview/fleet/orders/batch`
- Auth: HTTP bearer

Atomically creates or updates up to 250 canonical orders.

 <b>Rate limit:</b> 100 requests/min (learn more about rate limits <a href="https://developers.samsara.com/docs/rate-limits" target="_blank">here</a>).

To use this endpoint, select **Write Routes** under the Driver Workflow category when creating or editing an API token. <a href="https://developers.samsara.com/docs/authentication#scopes-for-api-tokens" target="_blank">Learn More.</a>

Endpoints in this section are in Preview. These APIs are not functional and are instead for soliciting feedback from our API users on the intended design of this API. Additionally, it is not guaranteed that we will be releasing an endpoint included in this section to production. This means that developers should **NOT** rely on these APIs to build business critical applications

- Samsara may change the structure of a preview API's interface without versioning or any notice to API users.

- When an endpoint becomes generally available, it will be announced in the API [changelog](https://developers.samsara.com/changelog).
 

 **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href="https://forms.gle/zkD4NCH7HjKb7mm69" target="_blank">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href="https://www.samsara.com/help" target="_blank">submit a case</a> to our support team.

## Request body

- OrdersPostOrdersBatchRequestBody: Atomic canonical order upsert request.
  - `data` FleetOrderBatchUpsertInputRequestBody[], required: Orders to upsert atomically. Maximum 250.
    - `customerProperties` FleetOrderBatchCustomerPropertyInputRequestBody[]: Order-specific customer metadata.
      - `key` string: Customer-defined property key. Required.
      - `value` string: Customer-defined property value. Required.
    - `externalIds` object: Org-scoped external identifiers.
    - `id` string: Existing Samsara order UUID. Required unless externalIds is supplied.
    - `samsaraCustomerOrderName` string: Human-readable order label.
    - `taskIdsToRemove` string[]: Existing task IDs to retire.
    - `tasks` FleetOrderBatchTaskUpsertInputRequestBody[]: Tasks to create or update. Omitted existing tasks remain live.
      - `customerProperties` FleetOrderBatchCustomerPropertyInputRequestBody[]: Task-specific customer metadata.
        - `key` string: Customer-defined property key. Required.
        - `value` string: Customer-defined property value. Required.
      - `dispatcherNotes` string: Dispatcher-visible note.
      - `driverNotes` string: Driver-visible note.
      - `hubId` string, required: Hub UUID for this task.
      - `id` string: Existing task ID. Omit to create a task.
      - `positionConstraintType` string: Task position constraint. Must be none, first, or last.
      - `quantities` FleetOrderBatchQuantityInputRequestBody[]: Task quantities.
        - `capacityId` string: Optional capacity UUID for the task hub.
        - `label` string: Human-readable quantity label. Required.
        - `value` number, double: Finite, non-negative quantity value. Required.
      - `serviceDurationSeconds` integer: Expected non-negative service duration in seconds.
      - `serviceLocation` FleetOrderBatchServiceLocationInputRequestBody: Saved or one-time service location for an order task. The discriminator and matching branch are validated per batch item.
        - `addressId` string: Saved address ID. Required for savedAddress locations.
        - `customAddress` FleetOrderBatchCustomAddressInputRequestBody: A one-time structured service address. Coordinate ranges are validated per batch item.
          - `addressLine1` string: First address line.
          - `addressLine2` string: Second address line.
          - `city` string: City.
          - `country` string: Country.
          - `formattedAddress` string: Human-readable formatted address.
          - `latitude` number, double: Latitude in decimal degrees. Must be between -90 and 90.
          - `longitude` number, double: Longitude in decimal degrees. Must be between -180 and 180.
          - `postalCode` string: Postal code.
          - `state` string: State, province, or region.
        - `serviceLocationType` string: Location discriminator. Required; must be savedAddress or customAddress.
      - `serviceWindowIdsToRemove` string[]: Existing service window UUIDs to retire.
      - `serviceWindows` FleetOrderBatchServiceWindowUpsertInputRequestBody[]: Service windows to create or update.
        - `endTime` string: Service window end in RFC 3339 format.
        - `id` string: Existing service window UUID. Omit to create a window.
        - `startTime` string: Service window start in RFC 3339 format.
      - `taskType` string, required: Task type. Must be delivery, pickup, or pickupDelivery.

## Response `200`

OK response.

- OrdersPostOrdersBatchResponseBody
  - `requestId` string, uuid, required: UUID for this batch operation.
  - `responses` FleetOrderBatchResponseItemResponseBody[], required: One result per input order, in request order.
    - `data` FleetOrderObjectResponseBody: A canonical customer order.
      - `createdAtTime` string, date-time, required: Creation timestamp in RFC 3339 format.
      - `customerProperties` FleetOrderCustomerPropertyObjectResponseBody[], required: Order-specific customer metadata.
        - `key` string, required: Customer-defined property key.
        - `value` string, required: Customer-defined property value.
      - `externalIds` object: Org-scoped external identifiers.
      - `id` string, required: Samsara-generated canonical order UUID.
      - `samsaraCustomerOrderName` string: Human-readable order label.
      - `tasks` FleetOrderTaskObjectResponseBody[], required: Live order tasks.
        - `createdAtTime` string, date-time, required: Creation timestamp in RFC 3339 format.
        - `customerProperties` FleetOrderCustomerPropertyObjectResponseBody[], required: Task-specific customer metadata.
          - `key` string, required: Customer-defined property key.
          - `value` string, required: Customer-defined property value.
        - `dispatcherNotes` string: Dispatcher-visible note.
        - `driverNotes` string: Driver-visible note.
        - `hubId` string, required: Hub UUID for the task.
        - `id` string, required: Opaque task ID.
        - `positionConstraintType` 'unknown' | 'none' | 'first' | 'last', required: Task position constraint. Valid values: `unknown`, `none`, `first`, `last`
        - `quantities` FleetOrderQuantityObjectResponseBody[], required: Task quantities.
          - `capacityId` string: Capacity UUID when this quantity uses a configured capacity.
          - `id` string, required: Opaque quantity UUID.
          - `label` string, required: Human-readable quantity label.
          - `value` number, double, required: Quantity value.
        - `routeId` string: Route ID when this task is attached to a route.
        - `serviceDurationSeconds` integer: Expected service duration in seconds.
        - `serviceLocation` FleetOrderServiceLocationObjectResponseBody: A saved, one-time, or unknown task service location.
          - `addressId` string: Saved address ID.
          - `customAddress` FleetOrderCustomAddressObjectResponseBody: A one-time structured service address.
            - `addressLine1` string: First address line.
            - `addressLine2` string: Second address line.
            - `city` string: City.
            - `country` string: Country.
            - `formattedAddress` string: Human-readable formatted address.
            - `latitude` number, double: Latitude in decimal degrees.
            - `longitude` number, double: Longitude in decimal degrees.
            - `postalCode` string: Postal code.
            - `state` string: State, province, or region.
          - `serviceLocationType` 'unknown' | 'savedAddress' | 'customAddress', required: Location discriminator. Returns unknown when the backend location variant is not recognized. Valid values: `unknown`, `savedAddress`, `customAddress`
        - `serviceWindows` FleetOrderServiceWindowObjectResponseBody[], required: Task service windows.
          - `endTime` string, date-time: Service window end in RFC 3339 format.
          - `id` string, required: Opaque service window UUID.
          - `startTime` string, date-time: Service window start in RFC 3339 format.
        - `taskType` 'unknown' | 'delivery' | 'pickup' | 'pickupDelivery', required: Task type. Valid values: `unknown`, `delivery`, `pickup`, `pickupDelivery`
        - `updatedAtTime` string, date-time, required: Last update timestamp in RFC 3339 format.
      - `updatedAtTime` string, date-time, required: Last update timestamp in RFC 3339 format.
    - `message` string: Failure message.
    - `status` integer, required: HTTP-style status for this input.

## Other responses

- `401`: Unauthorized response.
- `404`: Not Found response.
- `405`: Method Not Allowed response.
- `413`: Content Too Large response.
- `429`: Too Many Requests response.
- `500`: Internal Server Error response.
- `501`: Not Implemented response.
- `502`: Bad Gateway response.
- `503`: Service Unavailable response.
- `504`: Gateway Timeout response.
- `default`: Bad Request response.

---

[API](https://skmtc.dev/samsara/apis/samsara-api.md) - [All operations](https://skmtc.dev/samsara/apis/samsara-api/llms.txt) - [OpenAPI document](https://skmtc.dev/samsara/apis/samsara-api/revisions/a9e35d4999be?raw)