---
title: "Create orders in bulk"
method: POST
path: "/hub/plan/orders"
tags: ["Plans"]
---

# Create orders in bulk

`POST /hub/plan/orders`

## Request

- Base URL: `https://api.samsara.com`
- URL: `https://api.samsara.com/hub/plan/orders`
- Auth: HTTP bearer

Create one or more orders (bulk upsert). Pass an array of order objects; any object whose customerOrderId already exists will be updated, otherwise a new order is created. Functions can return JSON arrays in this Order POST format. Orders are initially created at the plan level but will migrate to hub-level entities, with planId becoming optional in future versions.

 <b>Rate limit:</b> 5 requests/sec (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>
 

 **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

- PlanOrdersCreatePlanOrdersRequestBody: Request body for creating plan orders
  - `data` OrderInputObjectRequestBody[], required: An array of order objects to be created or updated
    - `customProperties` OrderCustomPropertyInputRequestBody[]: An array of custom property values for the order
      - `customPropertyId` string, required: The ID of the custom property definition
      - `value` string, required: The value for this custom property
    - `customerOrderId` string, required: The customer-provided identifier for the order
    - `delivery` OrderTaskRequestBody: Order task. One of `customerLocationId`, `address`, or both `latitude` and `longitude` is required.
      - `address` string: The full address string for the order. One of `customerLocationId`, `address`, or both `latitude` and `longitude` is required.
      - `appointmentWindow` AppointmentWindowRequestBody: Appointment window
        - `endTime` string, date-time, required: End time of the appointment window, in RFC 3339 format
        - `startTime` string, date-time, required: Start time of the appointment window, in RFC 3339 format
      - `customerLocationId` string: The customer-provided identifier of the location associated with the order. One of `customerLocationId`, `address`, or both `latitude` and `longitude` is required.
      - `latitude` number, double: Latitude of the order. Optional if address is provided; the address will be geocoded to obtain coordinates. One of `customerLocationId`, `address`, or both `latitude` and `longitude` is required.
      - `longitude` number, double: Longitude of the order. Optional if address is provided; the address will be geocoded to obtain coordinates. One of `customerLocationId`, `address`, or both `latitude` and `longitude` is required.
      - `notes` string: Any additional notes for the order
      - `position` 'first' | 'last' | 'any': Position constraint for the order task Valid values: `first`, `last`, `any`
      - `serviceTimeSeconds` integer: Estimated service time for the order in seconds
    - `hubId` string, required: The ID of the hub the order belongs to
    - `pickup` OrderTaskRequestBody: Order task. One of `customerLocationId`, `address`, or both `latitude` and `longitude` is required.
      - `address` string: The full address string for the order. One of `customerLocationId`, `address`, or both `latitude` and `longitude` is required.
      - `appointmentWindow` AppointmentWindowRequestBody: Appointment window
        - `endTime` string, date-time, required: End time of the appointment window, in RFC 3339 format
        - `startTime` string, date-time, required: Start time of the appointment window, in RFC 3339 format
      - `customerLocationId` string: The customer-provided identifier of the location associated with the order. One of `customerLocationId`, `address`, or both `latitude` and `longitude` is required.
      - `latitude` number, double: Latitude of the order. Optional if address is provided; the address will be geocoded to obtain coordinates. One of `customerLocationId`, `address`, or both `latitude` and `longitude` is required.
      - `longitude` number, double: Longitude of the order. Optional if address is provided; the address will be geocoded to obtain coordinates. One of `customerLocationId`, `address`, or both `latitude` and `longitude` is required.
      - `notes` string: Any additional notes for the order
      - `position` 'first' | 'last' | 'any': Position constraint for the order task Valid values: `first`, `last`, `any`
      - `serviceTimeSeconds` integer: Estimated service time for the order in seconds
    - `planId` string, required: The ID of the plan the order belongs to
    - `priority` integer: Priority of the order (e.g., 1 for high, 5 for low)
    - `quantities` OrderQuantityInputRequestBody[]: An array of quantities for the order
      - `capacityId` string, required: The ID of the required capacity type
      - `quantity` number, double, required: The quantity of the required capacity
    - `skillsRequired` string[]: An array of skill IDs required to fulfill the order
  - `enableUpdateExistingOrders` boolean: Enable update of existing orders if an order with the same customerOrderId exists. The input must match the same quantity dimensions as the existing order. If not provided, requests will fail if an order's customerOrderId already exists.

## Response `200`

OK response.

- PlanOrdersCreatePlanOrdersResponseBody
  - `data` OrderObjectResponseBody[], required: Created order objects
    - `createdAtTime` string, date-time, required: The timestamp (in UTC) when the order was created
    - `customProperties` OrderCustomPropertyResponseBody[], required: An array of custom property values for the order
      - `customPropertyId` string, required: The ID of the custom property definition
      - `name` string, required: The name of the custom property
      - `value` string, required: The value for this custom property
    - `customerOrderId` string, required: The customer-provided identifier for the order
    - `delivery` OrderTaskResponseBody: Order task. One of `customerLocationId`, `address`, or both `latitude` and `longitude` is required.
      - `address` string: The full address string for the order. One of `customerLocationId`, `address`, or both `latitude` and `longitude` is required.
      - `appointmentWindow` AppointmentWindowResponseBody: Appointment window
        - `endTime` string, date-time, required: End time of the appointment window, in RFC 3339 format
        - `startTime` string, date-time, required: Start time of the appointment window, in RFC 3339 format
      - `customerLocationId` string: The customer-provided identifier of the location associated with the order. One of `customerLocationId`, `address`, or both `latitude` and `longitude` is required.
      - `latitude` number, double: Latitude of the order. Optional if address is provided; the address will be geocoded to obtain coordinates. One of `customerLocationId`, `address`, or both `latitude` and `longitude` is required.
      - `longitude` number, double: Longitude of the order. Optional if address is provided; the address will be geocoded to obtain coordinates. One of `customerLocationId`, `address`, or both `latitude` and `longitude` is required.
      - `notes` string: Any additional notes for the order
      - `position` 'first' | 'last' | 'any': Position constraint for the order task Valid values: `first`, `last`, `any`
      - `serviceTimeSeconds` integer: Estimated service time for the order in seconds
    - `hubId` string, required: The ID of the hub the order belongs to
    - `id` string, required: The Samsara-generated unique identifier (UUID) for the order
    - `pickup` OrderTaskResponseBody: Order task. One of `customerLocationId`, `address`, or both `latitude` and `longitude` is required.
      - `address` string: The full address string for the order. One of `customerLocationId`, `address`, or both `latitude` and `longitude` is required.
      - `appointmentWindow` AppointmentWindowResponseBody: Appointment window
        - `endTime` string, date-time, required: End time of the appointment window, in RFC 3339 format
        - `startTime` string, date-time, required: Start time of the appointment window, in RFC 3339 format
      - `customerLocationId` string: The customer-provided identifier of the location associated with the order. One of `customerLocationId`, `address`, or both `latitude` and `longitude` is required.
      - `latitude` number, double: Latitude of the order. Optional if address is provided; the address will be geocoded to obtain coordinates. One of `customerLocationId`, `address`, or both `latitude` and `longitude` is required.
      - `longitude` number, double: Longitude of the order. Optional if address is provided; the address will be geocoded to obtain coordinates. One of `customerLocationId`, `address`, or both `latitude` and `longitude` is required.
      - `notes` string: Any additional notes for the order
      - `position` 'first' | 'last' | 'any': Position constraint for the order task Valid values: `first`, `last`, `any`
      - `serviceTimeSeconds` integer: Estimated service time for the order in seconds
    - `planId` string, required: The ID of the plan the order belongs to
    - `priority` integer, required: Priority of the order (e.g., 1 for high, 5 for low)
    - `quantities` OrderQuantityResponseBody[], required: An array of quantities for the order
      - `capacityId` string, required: The ID of the required capacity type
      - `quantity` number, double, required: The quantity of the required capacity
    - `routeId` string: The ID of the route this order is assigned to. Null if the order is unassigned. Only populated on list responses.
    - `skillsRequired` string[], required: An array of skill IDs required to fulfill the order
    - `updatedAtTime` string, date-time, required: The timestamp (in UTC) when the order was last updated

## 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)