Create orders in bulk

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.

Rate limit: 5 requests/sec (learn more about rate limits here).

To use this endpoint, select Write Routes under the Driver Workflow category when creating or editing an API token. Learn More.

Submit Feedback: Likes, dislikes, and API feature requests should be filed as feedback in our API feedback form. If you encountered an issue or noticed inaccuracies in the API documentation, please submit a case to our support team.

POST /hub/plan/orders

Create orders in bulk

cURL

curl --request POST \
  --url https://api.samsara.com/hub/plan/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "data": [
    {
      "customerOrderId": "ORDER-2024-001",
      "hubId": "550e8400-e29b-41d4-a716-446655440000",
      "planId": "650e8400-e29b-41d4-a716-446655440023",
      "customProperties": [
        {
          "customPropertyId": "750e8400-e29b-41d4-a716-446655440004",
          "value": "Premium"
        }
      ],
      "delivery": {
        "address": "123 Business Way, San Francisco",
        "customerLocationId": "LOC-123",
        "latitude": 37.7749,
        "longitude": -122.4194,
        "notes": "Use main entrance",
        "position": "first",
        "serviceTimeSeconds": 600
      },
      "pickup": {
        "address": "123 Business Way, San Francisco",
        "customerLocationId": "LOC-123",
        "latitude": 37.7749,
        "longitude": -122.4194,
        "notes": "Use main entrance",
        "position": "first",
        "serviceTimeSeconds": 600
      },
      "priority": 1,
      "quantities": [
        {
          "capacityId": "850e8400-e29b-41d4-a716-446655440003",
          "quantity": 25.5
        }
      ],
      "skillsRequired": [
        "650e8400-e29b-41d4-a716-446655440001",
        "650e8400-e29b-41d4-a716-446655440001"
      ]
    }
  ],
  "enableUpdateExistingOrders": false
}
'

200

{
  "data": [
    {
      "createdAtTime": "2024-04-10T11:30:00Z",
      "customProperties": [
        {
          "customPropertyId": "750e8400-e29b-41d4-a716-446655440004",
          "name": "CustomerType",
          "value": "Premium"
        }
      ],
      "customerOrderId": "ORDER-2024-001",
      "hubId": "550e8400-e29b-41d4-a716-446655440000",
      "id": "a50e8400-e29b-41d4-a716-446655440006",
      "planId": "650e8400-e29b-41d4-a716-446655440023",
      "priority": 1,
      "quantities": [
        {
          "capacityId": "850e8400-e29b-41d4-a716-446655440003",
          "quantity": 25.5
        }
      ],
      "skillsRequired": [
        "650e8400-e29b-41d4-a716-446655440001",
        "650e8400-e29b-41d4-a716-446655440001",
        "650e8400-e29b-41d4-a716-446655440001",
        "650e8400-e29b-41d4-a716-446655440001"
      ],
      "updatedAtTime": "2024-04-10T11:30:00Z",
      "delivery": {
        "address": "123 Business Way, San Francisco",
        "appointmentWindow": {
          "endTime": "2024-04-10T17:00:00Z",
          "startTime": "2024-04-10T09:00:00Z"
        },
        "customerLocationId": "LOC-123",
        "latitude": 37.7749,
        "longitude": -122.4194,
        "notes": "Use main entrance",
        "position": "first",
        "serviceTimeSeconds": 600
      },
      "pickup": {
        "address": "123 Business Way, San Francisco",
        "appointmentWindow": {
          "endTime": "2024-04-10T17:00:00Z",
          "startTime": "2024-04-10T09:00:00Z"
        },
        "customerLocationId": "LOC-123",
        "latitude": 37.7749,
        "longitude": -122.4194,
        "notes": "Use main entrance",
        "position": "first",
        "serviceTimeSeconds": 600
      },
      "routeId": "950e8400-e29b-41d4-a716-446655440005"
    }
  ]
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request body for creating plan orders

data · object[] · required

An array of order objects to be created or updated

Show child attributes

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.

Example:

false

Response

200

application/json

OK response.

data · object[] · required

Created order objects

Show child attributes