> ## 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 / search inventory holds

> Returns a list of `Hold` objects. Cross-merchant by design — filter by `merchant_id` or
`product_id`/`sku` to scope to a specific merchant.



## OpenAPI

````yaml GET /v1/inventory/holds
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/holds:
    get:
      tags:
        - Holds
      summary: List / search inventory holds
      description: >-
        Returns a list of `Hold` objects. Cross-merchant by design — filter by
        `merchant_id` or

        `product_id`/`sku` to scope to a specific merchant.
      operationId: listHolds
      parameters:
        - 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` — hold_id
              - `merchant_id`
              - `warehouse_id`
              - `product_id`
              - `location_id`
              - `lot_id`
              - `lot_number`
              - `reason_code` — exact match (does NOT roll up to parent)
              - `held_at` — supports `{from:...}`, `{to:...}` range syntax
              - `status` — `active` or `released` (only `eq` and `in` operators supported)
          examples:
            Active only:
              summary: Only active holds
              value:
                - status:active
            For a given merchant:
              summary: Filter to a single merchant
              value:
                - merchant_id:2
            By reason code:
              summary: Holds with reason "damaged"
              value:
                - reason_code:damaged
        - name: sort
          in: query
          required: false
          schema:
            type: string
          description: >-
            Default sort is **descending** by `id` (`sort=-id`) — PRIMARY-key
            backed and

            chronologically equivalent to `held_at` for unreleased rows under
            the canonical

            insert path. Pass `sort=-held_at` explicitly if your dataset
            includes backfilled

            or timestamp-corrected rows where insert order diverges from
            `held_at`.


            Using the [sorting syntax](/global-api/sorting-syntax), the
            following fields are available

            for sorting:
              - `id`
              - `held_at`
        - $ref: '#/components/parameters/Inventory_API_v1_fields-merchant'
        - $ref: '#/components/parameters/Inventory_API_v1_fields-warehouse'
        - $ref: '#/components/parameters/Inventory_API_v1_fields-product'
        - $ref: '#/components/parameters/Inventory_API_v1_fields-location'
        - $ref: '#/components/parameters/Inventory_API_v1_fields-lot'
        - $ref: '#/components/parameters/Inventory_API_v1_fields-held_by'
        - $ref: '#/components/parameters/Inventory_API_v1_fields-released_by'
        - $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: List of `Hold` objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection:
                    type: array
                    description: A list of `Hold` objects.
                    items:
                      $ref: '#/components/schemas/Inventory_API_v1_Hold'
                  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_fields-merchant:
      name: fields:merchant
      in: query
      required: false
      description: >-
        Specify additional fields of the `Merchant` 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_merchant-fields-enum'
    Inventory_API_v1_fields-warehouse:
      name: fields:warehouse
      in: query
      required: false
      description: >-
        Specify additional fields of the `Warehouse` 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_warehouse-fields-enum'
    Inventory_API_v1_fields-product:
      name: fields:product
      in: query
      required: false
      description: >-
        Specify additional fields of the `Product` or `Packaging*` 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_product-packaging-fields-enum'
    Inventory_API_v1_fields-location:
      name: fields:location
      in: query
      required: false
      description: >-
        Specify additional fields of the `Location` 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_location-fields-enum'
    Inventory_API_v1_fields-lot:
      name: fields:lot
      in: query
      required: false
      description: >-
        Specify additional fields of the `Lot` 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_lot-fields-enum'
    Inventory_API_v1_fields-held_by:
      name: fields:held_by
      in: query
      required: false
      description: >-
        Specify additional fields of the `Requester` object (the entity that
        placed the hold) to be included in the response. See the [selecting
        fields](/global-api/selecting-fields) page for more information.
      explode: false
      schema:
        type: array
        items:
          type: string
          enum:
            - all
    Inventory_API_v1_fields-released_by:
      name: fields:released_by
      in: query
      required: false
      description: >-
        Specify additional fields of the `Requester` object (the entity that
        released the hold) to be included in the response. See the [selecting
        fields](/global-api/selecting-fields) page for more information.
      explode: false
      schema:
        type: array
        items:
          type: string
          enum:
            - all
    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_Hold:
      title: Hold
      type: object
      description: >-
        An inventory hold record. Cross-merchant view (Global API surface).


        **Releasing cascaded holds:** when `holdLot` is called with
        `cascade_bom=true`, free the

        cascade tree by releasing each child via `POST /holds/{id}/release`,
        using

        `origin.created_origin_hold_ids ∪ cascade.child_hold_ids` from the
        original `holdLot`

        response.


        **Do not** include `origin.root_hold_ids` blindly in the release set —
        those may include

        pre-existing roots from a prior `cascadeLotHold` call that this call
        attached children to,

        and releasing them would also release siblings the current caller did
        not place.
      properties:
        type:
          type: string
          enum:
            - Hold
          readOnly: true
        id:
          type: integer
          format: int64
          description: Internal `hold_id` primary key.
          readOnly: true
          example: 142
        merchant:
          description: Merchant that owns the held product.
          allOf:
            - $ref: '#/components/schemas/Inventory_API_v1_MerchantRef'
        warehouse:
          description: Warehouse where the held inventory lives.
          allOf:
            - $ref: '#/components/schemas/Inventory_API_v1_WarehouseRef'
        product:
          description: Product whose inventory is on hold.
          allOf:
            - $ref: '#/components/schemas/Inventory_API_v1_StockableProductRef'
        location:
          description: Specific location holding the inventory (label included).
          allOf:
            - $ref: '#/components/schemas/Inventory_API_v1_LocationRef'
        lot:
          description: >-
            Lot whose inventory is on hold (NULL when the hold is location-scope
            without a lot).
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Inventory_API_v1_LotRef'
        reason:
          type: object
          description: Hold reason — emitted inline with parent_code resolved.
          properties:
            code:
              type: string
              description: Reason code (system or user-defined).
              example: damaged
            label:
              type: string
              description: Human-readable reason label.
              example: Damaged
            parent_code:
              type: string
              nullable: true
              description: >-
                Parent (system) reason code; NULL when this reason is itself a
                system parent.
              example: damaged
          required:
            - code
            - label
        qty:
          type: number
          format: float
          description: Held quantity.
          example: 12
        held_at:
          type: string
          format: date-time
          description: When the hold was placed.
          example: '2026-04-28T14:32:00Z'
        held_by:
          nullable: true
          description: >-
            Requester who placed the hold (admin user, client user, API key,
            integration, etc.).
          allOf:
            - $ref: '#/components/schemas/Inventory_API_v1_RequesterRef'
        released_at:
          type: string
          format: date-time
          nullable: true
          description: When the hold was released (NULL while still active).
          example: null
        released_by:
          nullable: true
          description: Requester who released the hold.
          allOf:
            - $ref: '#/components/schemas/Inventory_API_v1_RequesterRef'
        notes:
          type: string
          nullable: true
          description: Free-form notes attached at place / release time.
          example: Damaged in receiving
        status:
          type: string
          enum:
            - active
            - released
          description: Computed from released_at; 'active' when released_at IS NULL.
          example: active
        updated_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            Last meaningful timestamp (released_at when present, otherwise
            held_at).
          example: '2026-04-28T14:32:00Z'
      required:
        - type
        - id
        - qty
        - held_at
        - status
    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_merchant-fields-enum:
      title: Merchant
      type: array
      items:
        type: string
        enum:
          - basic
          - all
          - code
          - name
          - status
          - created_at
          - updated_at
          - brands
          - default_brand
          - custom_fields
    Inventory_API_v1_warehouse-fields-enum:
      title: Warehouse
      description: >-
        Specify additional fields of the `Warehouse` object to be included in
        the response.
      type: array
      items:
        type: string
        enum:
          - basic
          - all
          - id
          - name
          - is_active
          - abbreviation
    Inventory_API_v1_product-packaging-fields-enum:
      title: Product Or Packaging
      description: >-
        Specify additional fields of the `Product` or `Packaging*` object to be
        included in the response.
      type: array
      items:
        type: string
        enum:
          - basic
          - all
          - created_at
          - updated_at
          - container_options
          - supplies_options
          - data_collection_options
          - instruction_options
          - infill_options
          - vendor_sku
          - external_id
          - barcodes
          - goods_type
          - is_available
          - is_visible
          - weight
          - dimensions
          - volume
          - inventory
          - export
          - regulated_goods
          - packaging
          - custom_fields
    Inventory_API_v1_location-fields-enum:
      title: Location
      description: >-
        Specify additional fields of the `Location` object to be included in the
        response.
      type: array
      items:
        type: string
        enum:
          - basic
          - all
          - label
          - priority
          - qty_on_hand
          - qty_putaway
          - qty_unreserved
          - qty_reserved
          - qty_locked
          - is_temp
          - is_pickable
          - is_type_auto
          - created_at
          - updated_at
          - last_cyclecount_at
          - lot
          - product
          - rack
          - location_type
    Inventory_API_v1_lot-fields-enum:
      title: Lot
      description: >-
        Specify additional fields of the `Lot` object to be included in the
        response.
      type: array
      items:
        type: string
        enum:
          - basic
          - all
          - id
          - lot_number
          - origination_date
          - expiration_date
          - is_expired
          - is_active
          - lot_number_input
          - expiration_input
          - sort_value
          - days_until_expiration
          - sort_direction
          - group_value
          - created_at
          - updated_at
          - created_by
          - lot_type
          - product
    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_WarehouseRef:
      title: WarehouseRef
      type: object
      description: A reference to a `Warehouse` by `id`.
      properties:
        type:
          type: string
          enum:
            - Warehouse
          description: This property describes the type of object in the response body.
        id:
          type: integer
          format: int32
          description: >-
            The internal `id` property used as a path parameter in a resource
            lookup.
      required:
        - type
        - id
      nullable: true
      additionalProperties: false
    Inventory_API_v1_StockableProductRef:
      title: StockableProductRef
      type: object
      description: A reference to a `Product` or stockable packaging type object by `id`.
      properties:
        type:
          type: string
          description: >-
            This is a read-only property that describes the type of object in
            the response body.
          enum:
            - Product
            - PackagingContainer
            - PackagingInfill
            - PackagingSupplies
        id:
          type: integer
          description: >-
            The internal, read-only, `id` property used as a path parameter in a
            resource lookup.
          format: int32
      required:
        - type
        - id
      nullable: true
      additionalProperties: false
    Inventory_API_v1_LocationRef:
      title: LocationRef
      type: object
      description: A reference to a `Location` by `id`.
      properties:
        type:
          type: string
          description: This property describes the type of object in the response body.
          enum:
            - Location
        id:
          type: integer
          format: int32
          example: 42
          description: >-
            The internal `id` property used as a path parameter in a resource
            lookup.
      required:
        - type
        - id
      nullable: true
      additionalProperties: false
    Inventory_API_v1_LotRef:
      title: LotRef
      type: object
      description: >-
        A reference to a `Lot` object. The Lot records the time some inventory
        was originated (first received or

        otherwise created) and optionally a lot number and expiration date and
        may affect the order in which

        inventory is "burned" depending on the `LotType`.
      properties:
        type:
          type: string
          enum:
            - Lot
          description: This property describes the type of object in the response body.
        id:
          type: integer
          example: 54
          description: >-
            The internal `id` property used as a path parameter in a resource
            lookup.
      required:
        - type
        - id
      nullable: true
      additionalProperties: false
    Inventory_API_v1_RequesterRef:
      title: RequesterRef
      type: object
      description: Reference a requester (who/what performed an action) by `type` and `id`.
      properties:
        type:
          type: string
          enum:
            - Requester
          example: Requester
          description: The resource type (always "Requester").
        id:
          type: integer
          format: int32
          example: 3
          description: The internal requester ID (`requester_id`).
      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.

````