> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.shipbob.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.shipbob.com/_mcp/server.

# Bulk Place Shipments On Hold


POST https://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.shipbob.com/api/orders/bulk-place-shipments-on-hold

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: api-2026-07
  version: 1.0.0
paths:
  /2026-07/shipment:bulkPlaceOnHold:
    post:
      operationId: bulk-place-shipments-on-hold
      summary: |
        Bulk Place Shipments On Hold
      description: >
        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).
      tags:
        - orders
      parameters:
        - name: Authorization
          in: header
          description: Authentication using Personal Access Token (PAT) token
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.BulkActionApiResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders.ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Orders.BulkPlaceOnHoldRequest'
servers:
  - url: https://api.shipbob.com
    description: https://api.shipbob.com
  - url: https://sandbox-api.shipbob.com
    description: https://sandbox-api.shipbob.com
components:
  schemas:
    Orders.BulkPlaceOnHoldRequest:
      type: object
      properties:
        reserve_inventory:
          type: boolean
          default: true
          description: >-
            When true (default), inventory stays committed and an allocation
            hold is placed. When false, the committed inventory is deallocated
            (the dashboard's 'Unreserve' option).
        shipment_ids:
          type: array
          items:
            type: integer
            format: int64
          description: Shipments to place on hold. Must contain at least one id.
      required:
        - shipment_ids
      title: Orders.BulkPlaceOnHoldRequest
    Orders.ErrorCode:
      type: string
      enum:
        - INVALID_PARAMETER
        - VALIDATION_ERROR
        - DATABASE_UPDATE_ERROR
        - REPROCESSING_ERROR
        - DEALLOCATE_ERROR
        - NOT_FOUND
        - CONFLICT
      title: Orders.ErrorCode
    Orders.ErrorResponse:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/Orders.ErrorCode'
          description: Error code identifying the type of error
        message:
          type:
            - string
            - 'null'
          description: Human-readable description of the error
      title: Orders.ErrorResponse
    Orders.IApiDetailResponse:
      type: object
      properties:
        error:
          oneOf:
            - $ref: '#/components/schemas/Orders.ErrorResponse'
            - type: 'null'
          description: Error details if the operation was not successful
        id:
          type: integer
          format: int64
          description: Unique identifier of the shipment
        is_success:
          type: boolean
          description: Indicates whether the operation was successful for this shipment
      title: Orders.IApiDetailResponse
    Orders.SummaryResponse:
      type: object
      properties:
        failed:
          type: integer
          description: Number of shipments that failed to update
        successful:
          type: integer
          description: Number of shipments that were updated successfully
        total:
          type: integer
          description: Total number of shipments included in the bulk operation
      title: Orders.SummaryResponse
    Orders.BulkActionApiResponse:
      type: object
      properties:
        results:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/Orders.IApiDetailResponse'
          description: Per-shipment results of the bulk operation
        summary:
          $ref: '#/components/schemas/Orders.SummaryResponse'
          description: Summary of the bulk operation results
      required:
        - summary
      title: Orders.BulkActionApiResponse
  securitySchemes:
    PAT:
      type: http
      scheme: bearer
      description: Authentication using Personal Access Token (PAT) token
    OAuth2:
      type: http
      scheme: bearer
      description: OAuth2 authentication using JWT tokens

```

## Examples



**Request**

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

**Response**

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

**SDK Code**

```python default
import requests

url = "https://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://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://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://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://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://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://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://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()
```