> ## 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. # List active hold reasons > Returns the active hold-reason tree as a flat list of parent (system) reasons; each parent inlines its user-defined child reasons via the `children` array. Schema enforces a single nesting level — child reasons never carry a `children` key. Cross-merchant by design (no website scoping). System reasons are always returned; user-defined reasons are returned regardless of which merchant created them. See the **Inventory Hold System** documentation for hold semantics. ## OpenAPI ````yaml GET /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: get: tags: - HoldReasons summary: List active hold reasons description: >- Returns the active hold-reason tree as a flat list of parent (system) reasons; each parent inlines its user-defined child reasons via the `children` array. Schema enforces a single nesting level — child reasons never carry a `children` key. Cross-merchant by design (no website scoping). System reasons are always returned; user-defined reasons are returned regardless of which merchant created them. See the **Inventory Hold System** documentation for hold semantics. operationId: listHoldReasons parameters: - $ref: '#/components/parameters/Inventory_API_v1_hold-reason-fields' - $ref: '#/components/parameters/Inventory_API_v1_fields-parent' - name: filter in: query schema: type: array items: type: string required: false style: form explode: true allowReserved: true description: >- Using the [filtering syntax](/global-api/filtering-syntax), you may filter the results using the following fields: - `id` — reason_id - `code` - name: sort in: query required: false schema: type: string description: >- Default sort is **ascending** by `id`. Using the [sorting syntax](/global-api/sorting-syntax), the following fields are available for sorting: - `id` - `code` - `sort_order` - $ref: '#/components/parameters/Inventory_API_v1_count' - $ref: '#/components/parameters/Inventory_API_v1_cursor_end' - $ref: '#/components/parameters/Inventory_API_v1_cursor_start' - $ref: '#/components/parameters/Inventory_API_v1_limit' responses: '200': description: >- A dictionary with a `collection` property containing an array of `HoldReason` objects (parents only; each parent's `children` array carries any user-defined sub-reasons). If no active reasons exist the array will be empty. content: application/json: schema: type: object properties: collection: type: array description: >- A list of parent `HoldReason` objects with their `children` inlined. items: $ref: '#/components/schemas/Inventory_API_v1_HoldReason' has_more: $ref: '#/components/schemas/Inventory_API_v1_has_more' next: $ref: '#/components/schemas/Inventory_API_v1_next' previous: $ref: '#/components/schemas/Inventory_API_v1_previous' meta: $ref: '#/components/schemas/Inventory_API_v1_meta' '400': $ref: '#/components/responses/Inventory_API_v1_400-bad-request' '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' Inventory_API_v1_count: name: count in: query description: >- If specified as `1`, the `meta.count` property of the response will be present and populated with the total count of items matching the query before any paging is applied. This is not included by default to improve performance in some edge cases and is not required to perform paging using the `next` property of the response. See [paging parameters](/global-api/paging-parameters) for more information. style: form schema: type: integer minimum: 0 maximum: 1 Inventory_API_v1_cursor_end: name: cursor_end in: query description: >- A cursor for use in pagination which defines the last `id` of the next page of results, non-inclusive. See [paging parameters](/global-api/paging-parameters) for more information on paging. schema: type: integer style: form Inventory_API_v1_cursor_start: name: cursor_start in: query description: >- A cursor for use in pagination which defines the starting `id` of the next page of results. See [paging parameters](/global-api/paging-parameters) for more information on paging. schema: type: integer style: form Inventory_API_v1_limit: name: limit in: query description: A limit on the number of objects to be returned. style: form schema: type: integer example: 100 default: 100 minimum: 1 maximum: 1000 schemas: 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_has_more: type: boolean description: |- True if the collection has more items on the next page. Use the "next" link to retrieve the next page of results. Inventory_API_v1_next: type: string nullable: true description: The resource path for the next page of results if any are expected. Inventory_API_v1_previous: type: string nullable: true description: The resource path for the previous page of results if any are expected. Inventory_API_v1_meta: type: object properties: processing_time: type: number description: Total time in which request is processed and response is sent back. example: 0.2525252525 cursor_start: type: integer description: >- A cursor for use in pagination which defines the starting `id` of the next page of results. See [paging parameters](/global-api/paging-parameters) for more information on paging. nullable: true cursor_end: type: integer description: >- A cursor for use in pagination which defines the last `id` of the next page of results, non-inclusive. See [paging parameters](/global-api/paging-parameters) for more information on paging. nullable: true count: type: integer description: >- The total number of items matching the query before applying paging parameters. This field is only present if the query parameter `count=1` is present in the request. description: Additional metadata pertaining to the response. 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 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 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_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. ````