> ## Documentation Index > Fetch the complete documentation index at: https://docs.shipstream.io/llms.txt > Use this file to discover all available pages before exploring further. # Create user-defined hold reason > Creates a new user-defined child hold reason under an existing top-level system reason. System fields (`is_system`, `reason_id`, `parent_code`, `parent_reason_id`) are server-controlled and must not be included in the request body. The `code` must be unique, match `^[a-z0-9_]+$`, and be ≤ 64 characters. The `parent.id` must reference a top-level system reason. ## OpenAPI ````yaml POST /v1/inventory/hold-reasons openapi: 3.0.3 info: title: ShipStream version: '1.0' license: name: Commercial (Copyright 2025 - All Rights Reserved) url: https://shipstream.io contact: name: ShipStream Support email: help@shipstream.io termsOfService: https://shipstream.io/legal/api-terms/ servers: - url: https://{base_url_domain}/api/global description: Direct API Url variables: base_url_domain: default: example.shipstream.app description: >- The fully qualified domain name for your ShipStream WMS instance. This is either a custom domain, or a subdomain of shipstream.app, and will be the same as the domain name for the page which you use to login to ShipStream WMS. security: - ShipStream_bearerAuth: [] tags: - name: Warehouses x-displayName: Warehouses - name: Products x-displayName: Products - name: Locations x-displayName: Locations - name: Levels x-displayName: Levels - name: HoldReasons x-displayName: HoldReasons - name: Holds x-displayName: Holds - name: Deliveries description: Every thing about a Delivery Receiving x-displayName: Deliveries - name: Shipments x-displayName: Shipments - name: Orders x-displayName: Orders - name: Retailers x-displayName: Retailers - name: Users x-displayName: Users - name: User Roles x-displayName: User Roles - name: Merchants x-displayName: Merchants - name: Healthcheck x-displayName: Healthcheck paths: /v1/inventory/hold-reasons: post: tags: - HoldReasons summary: Create user-defined hold reason description: >- Creates a new user-defined child hold reason under an existing top-level system reason. System fields (`is_system`, `reason_id`, `parent_code`, `parent_reason_id`) are server-controlled and must not be included in the request body. The `code` must be unique, match `^[a-z0-9_]+$`, and be ≤ 64 characters. The `parent.id` must reference a top-level system reason. operationId: createHoldReason parameters: - $ref: '#/components/parameters/Inventory_API_v1_hold-reason-fields' - $ref: '#/components/parameters/Inventory_API_v1_fields-parent' requestBody: required: true content: application/json: schema: type: object properties: code: type: string description: >- Stable identifier. Must match `^[a-z0-9_]+$`, ≤ 64 characters, unique. example: qc_followup label: type: string description: Human-readable label, ≤ 255 characters. example: QC Follow-up parent: $ref: '#/components/schemas/Inventory_API_v1_HoldReasonRef' description: >- Reference to the top-level system reason that owns this child. display_group: type: string nullable: true description: >- Display group name, ≤ 25 characters. Defaults to "Hold" via model. example: Hold allow_relocation: type: boolean nullable: true description: >- Whether inventory under this hold may be relocated. `null` = inherit from parent. example: null merchants: type: array nullable: true description: >- Merchant scope restrictions. Empty array or omit for unrestricted. items: $ref: '#/components/schemas/Inventory_API_v1_MerchantRef' is_active: type: boolean description: Whether this reason is active. Defaults to `true`. example: true sort_order: type: integer description: Display order within siblings. Defaults to `0`. example: 0 required: - code - label - parent responses: '201': description: Hold reason created. content: application/json: schema: type: object properties: resource: $ref: '#/components/schemas/Inventory_API_v1_HoldReason' '400': $ref: '#/components/responses/Inventory_API_v1_400-bad-request' '404': $ref: '#/components/responses/Inventory_API_v1_404-not-found' '422': $ref: '#/components/responses/Inventory_API_v1_422-unprocessable' '500': $ref: '#/components/responses/Inventory_API_v1_500-internal-server-error' components: parameters: Inventory_API_v1_hold-reason-fields: name: fields in: query required: false description: >- Specify additional fields of the `HoldReason` object to be included in the response. See the [selecting fields](/global-api/selecting-fields) page for more information. explode: false schema: $ref: '#/components/schemas/Inventory_API_v1_hold-reason-fields-enum' Inventory_API_v1_fields-parent: name: fields:parent in: query required: false description: >- Specify additional fields of the parent `HoldReason` object to be included in the response. See the [selecting fields](/global-api/selecting-fields) page for more information. explode: false schema: $ref: '#/components/schemas/Inventory_API_v1_hold-reason-fields-enum' schemas: Inventory_API_v1_HoldReasonRef: title: HoldReasonRef type: object description: Reference to a `HoldReason` by `id`. properties: type: type: string enum: - HoldReason description: This property describes the type of object in the response body. id: type: integer format: int32 example: 3 description: The internal `reason_id` of the hold reason. required: - type - id nullable: true additionalProperties: false Inventory_API_v1_MerchantRef: title: MerchantRef type: object description: Reference a `Merchant` by `id`. properties: type: type: string enum: - Merchant id: type: integer format: int32 example: 4 description: >- The internal `id` property used as a path parameter in a resource lookup. required: - type - id additionalProperties: false Inventory_API_v1_HoldReason: title: HoldReason type: object description: >- An inventory hold reason. System (parent) reasons are seeded and immutable; user-defined child reasons can be added under any system parent and inherit `allow_relocation` semantics. Schema enforces a single nesting level: parent reasons MAY include a `children` array; child reasons do NOT carry a `children` key. properties: type: type: string enum: - HoldReason readOnly: true description: >- This is a read-only property that describes the type of object in the response body. id: type: integer format: int32 description: > Internal reason_id. Emitted on top-level reasons (the framework merges it into every resource envelope); inline child reasons under a parent's `children` array omit it, so this property is optional. example: 12 code: type: string description: Stable identifier (immutable for system reasons). example: damaged label: type: string description: Human-readable label. example: Damaged parent_code: type: string nullable: true description: > For child reasons, the `code` of the parent (system) reason. NULL for parent (system) reasons. example: damaged allow_relocation: type: boolean nullable: true description: > Whether held inventory under this reason may be relocated. NULL means "inherit from parent". example: false sort_order: type: integer description: Display order within siblings. example: 30 is_active: type: boolean description: Whether this reason is currently active. example: true is_system: type: boolean description: Whether this reason is a seeded system reason (immutable). example: true children: type: array description: > User-defined child reasons under this parent. Present only on parent reasons; child reasons omit this key. Each child has the same field shape minus `children`. items: $ref: '#/components/schemas/Inventory_API_v1_HoldReason' parent: allOf: - $ref: '#/components/schemas/Inventory_API_v1_HoldReasonRef' nullable: true description: >- Reference to the parent system reason. Opt-in via `?fields=parent`; only meaningful on single-resource GET/POST endpoints. NULL for system (root) reasons.\ `Optional Field` merchants: type: array description: >- Merchant scope restrictions. Opt-in via `?fields=merchants`. Empty array means visible to all merchants (unrestricted). Each entry is a compact `{type, id}` ref.\ `Optional Field` items: $ref: '#/components/schemas/Inventory_API_v1_MerchantRef' required: - type - code - label - sort_order - is_active - is_system additionalProperties: false Inventory_API_v1_hold-reason-fields-enum: title: HoldReason description: >- Specify additional fields of the `HoldReason` object to be included in the response. type: array items: type: string enum: - basic - all - code - label - parent_code - allow_relocation - sort_order - is_active - is_system - children - parent - merchants responses: Inventory_API_v1_400-bad-request: description: >- The request was invalid. The client must change the request. See the response body for more details. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: type: type: string description: The error type code. enum: - parser - parameters - openapi message: type: string description: An English sentence describing the error type. details: type: array description: >- An array of objects describing which keys are responsible for the error and detailed messages describing why they are not valid. items: type: object properties: key: type: string description: The path to the key which relates to the error. message: type: string description: >- An English sentence describing the details of the error. additionalProperties: false additionalProperties: false minItems: 1 additionalProperties: false example: errors: - type: parameters message: The supplied parameters are invalid. details: - key: hold_until_date message: The date must be in the future. Inventory_API_v1_404-not-found: description: >- The requested resource was not found. It may have been deleted, it may have never existed, or you may not have permission to view it. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: type: type: string description: The error type code. enum: - not_found message: type: string description: An English sentence describing the error type. details: type: array description: >- An array of objects describing which keys are responsible for the error and detailed messages describing why they are not valid. items: type: object properties: key: type: string description: The path to the key which relates to the error. message: type: string description: >- An English sentence describing the details of the error. additionalProperties: false additionalProperties: false minItems: 1 additionalProperties: false example: errors: - type: not_found message: The server could not find the requested resource. Inventory_API_v1_422-unprocessable: description: >- There was an error processing the request. See the response body for more details. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: type: type: string description: The error type code. enum: - application - unable_to_process message: type: string description: An English sentence describing the error type. details: type: array description: >- An array of objects describing which keys are responsible for the error and detailed messages describing why they are not valid. items: type: object properties: key: type: string description: The path to the key which relates to the error. message: type: string description: >- An English sentence describing the details of the error. additionalProperties: false additionalProperties: false minItems: 1 additionalProperties: false example: errors: - type: unable_to_process message: The supplied parameters are invalid. details: - key: hold_until_date message: The date must be in the future. Inventory_API_v1_500-internal-server-error: description: >- Internal Server Error - Something wrong happened at server side. Contact server administrator for more details. securitySchemes: ShipStream_bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Generate a JWT access token through a Custom Global Integration and provide it with each request in the `Authorization` header prefixed with "Bearer" and then a single space. ````