---
title: "[beta] List orders for a specific plan"
method: GET
path: "/hub/plan/orders"
tags: ["Beta APIs"]
---

# \[beta\] List orders for a specific plan

`GET /hub/plan/orders`

## Request

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

Retrieve all orders for a specific plan, including both assigned and unassigned orders.

**Beta:** This endpoint is in beta and is likely to change before being broadly available. Reach out to your Samsara Representative to have RoutePlanning APIs enabled for your organization.

 <b>Rate limit:</b> 10 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 **Read 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.

## Query parameters

- `planId` string, required
- `orderIds` string
- `after` string
- `limit` integer

## Response `200`

OK response.

- PlanOrdersListPlanOrdersResponseBody
  - `data` OrderObjectResponseBody[], required: 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
  - `pagination` ListPlanOrdersResponsePaginationResponseBody, required: Pagination information
    - `endCursor` string: Cursor for the last item in the page
    - `hasNextPage` boolean, required: Whether there are more pages available

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