Place a manual hold on an order
Places a manual hold on an order (is_on_hold: true, hold_type: 'manual').
Stamps held_at, records held_by, logs a hold_placed timeline event, writes a
HOLD_PLACED activity log entry, and fires an order.hold_placed broadcast.
API callers may only place holds with hold_type: 'manual'. The credit_limit
hold type is set automatically by POST /v1/orders/{id}/confirm when the account
exceeds its credit limit and is not settable via this endpoint.
Guards:
- Order must exist and belong to the entity (Layer 1)
- Order must not already be on hold (400
already_on_hold) - Order must not be in a terminal status:
cancelled,archived(422terminal_status) hold_reasonis required
A user_id is required for the audit trail. API key callers may pass user_id in
the body; if omitted, the API key’s owner user is used as the held-by actor.
Idempotent via Idempotency-Key header. Requires orders:write scope.
Industry parallels:
- Shopify Admin GraphQL
orderHoldmutation (manual reason required) - NetSuite “Place on Credit Hold” per-order override
Authorizations
API key issued per entity via Settings > Developers > API Keys.
Each key carries scopes (e.g. orders:read, products:write).
Bearer token format: Authorization: Bearer ark_live_ent_Test keys use ark_test_ent_. Both are issued per entity
via Settings > Developers > API Keys.
Headers
Client-generated unique key for idempotent POST/PATCH/DELETE operations. Alias for the Idempotency parameter. Max 255 chars. On retry with the same key, the original response is returned without re-executing the operation. Keys expire after 24 hours.
255Path Parameters
UUID of the order to place on hold.
Body
Response
Hold placed successfully.

