> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer-stage.shipbob.dev/2026-07/api/orders/bulk-place-shipments-on-hold/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer-stage.shipbob.dev/_mcp/server.

# Bulk Place Shipments On Hold


POST https://sandbox-api.shipbob.com/2026-07/shipment:bulkPlaceOnHold
Content-Type: application/json

Places a Manual hold on multiple shipments in a single request. By default the committed inventory stays reserved and an allocation hold is placed; set `reserve_inventory` to `false` to deallocate the committed inventory instead (mirrors the dashboard's "Unreserve" option).

**Per-shipment results:** every shipment is evaluated independently and returns its own success/failure in `results`; one shipment failing never fails the whole request. A shipment already on a Manual hold is an idempotent success. Shipments that are picked, being fulfilled, cancelled, shipped, or otherwise ineligible fail individually. HTTP 400 is only returned when the request itself is malformed (empty `shipment_ids` or over the batch cap).


Reference: https://developer-stage.shipbob.dev/api/orders/bulk-place-shipments-on-hold

## Authentication

- `Authorization` header (bearer token, required) — Authentication using Personal Access Token (PAT) token
- `Authorization` header (bearer token, required) — OAuth2 authentication using JWT tokens

## Request

### Body (application/json)

This endpoint expects an Orders.BulkPlaceOnHoldRequest.

- `shipment_ids` (list of long, required) — Shipments to place on hold. Must contain at least one id.
- `reserve_inventory` (boolean, optional, default: true) — When true (default), inventory stays committed and an allocation hold is placed. When false, the committed inventory is deallocated (the dashboard's 'Unreserve' option).

## Response

### 200

OK

- `summary` (Orders.SummaryResponse, required) — Summary of the bulk operation results
- `results` (list of Orders.IApiDetailResponse, optional, nullable) — Per-shipment results of the bulk operation

## Errors

### 400 Bad Request Error

Bad Request

- `code` (enum, optional) — Error code identifying the type of error
  - Allowed values: `INVALID_PARAMETER`, `VALIDATION_ERROR`, `DATABASE_UPDATE_ERROR`, `REPROCESSING_ERROR`, `DEALLOCATE_ERROR`, `NOT_FOUND`, `CONFLICT`
- `message` (string, optional, nullable) — Human-readable description of the error

## Types

### Orders.SummaryResponse

- `failed` (integer, optional) — Number of shipments that failed to update
- `successful` (integer, optional) — Number of shipments that were updated successfully
- `total` (integer, optional) — Total number of shipments included in the bulk operation

### Orders.IApiDetailResponse

- `error` (Orders.ErrorResponse, optional, nullable) — Error details if the operation was not successful
- `id` (long, optional) — Unique identifier of the shipment
- `is_success` (boolean, optional) — Indicates whether the operation was successful for this shipment

### Orders.ErrorResponse

- `code` (enum, optional) — Error code identifying the type of error
  - Allowed values: `INVALID_PARAMETER`, `VALIDATION_ERROR`, `DATABASE_UPDATE_ERROR`, `REPROCESSING_ERROR`, `DEALLOCATE_ERROR`, `NOT_FOUND`, `CONFLICT`
- `message` (string, optional, nullable) — Human-readable description of the error

## Examples

**Request**

```json
{
  "shipment_ids": [
    123456,
    789012
  ],
  "reserve_inventory": true
}
```

**Response**

```json
{
  "summary": {
    "failed": 0,
    "successful": 2,
    "total": 2
  },
  "results": [
    {
      "error": {},
      "id": 123456,
      "is_success": true
    },
    {
      "error": {},
      "id": 789012,
      "is_success": true
    }
  ]
}
```

**SDK Code**

```python default
import requests

url = "https://sandbox-api.shipbob.com/2026-07/shipment:bulkPlaceOnHold"

payload = {
    "shipment_ids": [123456, 789012],
    "reserve_inventory": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript default
const url = 'https://sandbox-api.shipbob.com/2026-07/shipment:bulkPlaceOnHold';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"shipment_ids":[123456,789012],"reserve_inventory":true}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go default
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox-api.shipbob.com/2026-07/shipment:bulkPlaceOnHold"

	payload := strings.NewReader("{\n  \"shipment_ids\": [\n    123456,\n    789012\n  ],\n  \"reserve_inventory\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby default
require 'uri'
require 'net/http'

url = URI("https://sandbox-api.shipbob.com/2026-07/shipment:bulkPlaceOnHold")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"shipment_ids\": [\n    123456,\n    789012\n  ],\n  \"reserve_inventory\": true\n}"

response = http.request(request)
puts response.read_body
```

```java default
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://sandbox-api.shipbob.com/2026-07/shipment:bulkPlaceOnHold")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"shipment_ids\": [\n    123456,\n    789012\n  ],\n  \"reserve_inventory\": true\n}")
  .asString();
```

```php default
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://sandbox-api.shipbob.com/2026-07/shipment:bulkPlaceOnHold', [
  'body' => '{
  "shipment_ids": [
    123456,
    789012
  ],
  "reserve_inventory": true
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp default
using RestSharp;

var client = new RestClient("https://sandbox-api.shipbob.com/2026-07/shipment:bulkPlaceOnHold");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"shipment_ids\": [\n    123456,\n    789012\n  ],\n  \"reserve_inventory\": true\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift default
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "shipment_ids": [123456, 789012],
  "reserve_inventory": true
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://sandbox-api.shipbob.com/2026-07/shipment:bulkPlaceOnHold")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```