Updates the onHold status for multiple sales orders in a single request. This endpoint allows you to:

• Put orders on hold: Provide the onHold object in the request body
• Set automatic release: Include a releaseDate in the onHold object to automatically release orders on a specific hour
• Remove hold status: Provide null as the onHold value in the request body

The response will indicate which orders were successfully updated and which failed with error details.

Bulk Operations for Sales Orders

Bulk operations allow you to efficiently update multiple sales orders in a single API request.

Bulk OnHold Operations

The Bulk OnHold endpoint (PUT /v1/merchants/{merchantId}/orders/bulk) manages the hold status of multiple orders.

Use Cases

Request Structure

The request body requires:

• referenceIds: Array of order reference IDs to update
• onHold (nullable): Object containing hold configuration: null value clears any existing hold
• onHold.releaseDate (optional): If present the hold is configured to end on the given hour

Response Structure

The response provides feedback about the bulk operation:

• errors: Empty array indicating all orders succeeded
• meta: Optional metadata about the operation

Error Handling

When an individual order fails to update, the operation continues processing other orders. Failed orders will appear in the messages array with:

• title: Brief error description
• detail: Detailed error message
• meta.salesOrderNumber: The specific order that failed

Example Workflows

Hold orders until the hold is manually removed

{
  "referenceIds": ["ORDER-001", "ORDER-002", "ORDER-003"],
  "onHold": {}
}

Hold orders until a specific hour in the future

{
  "referenceIds": ["ORDER-001", "ORDER-002", "ORDER-003"],
  "onHold": {
    "releaseDate": "2024-12-25T10:00:00Z"
  }
}

Remove a hold from orders manually

{
  "referenceIds": ["ORDER-001", "ORDER-002", "ORDER-003"],
  "onHold": null
}