> ## 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.

# Stock Movements

Stock Movements record every change to inventory items such as when an order is received and allocated to a warehouse or a shipment is picked from the shelf.

## Methods

* [stock\_movement.list](#stock-movement-list)

***

## Entity Properties

* [Stock Movement](#stock-movement-properties)

***

## `stock_movement.list`

`stock_movement.list (null|object $filters, null|object $options)`

Retrieve list of stock movements.

### Parameters

<ParamField path="filters" type="object | null">
  [Filters](/merchant-api/search-filters) to apply to the request. Allowed properties for filtering: "id", "entity\_type", "entity\_action", "entity\_id", "sku", "created\_at", "warehouse\_id", "location", "adjustment\_reason\_code", "hold\_reason\_code".

  `hold_reason_code` filters by the rolled-up parent reason code on movements attributed to a governing hold and accepts the standard filter operators. Movements without a governing hold have a null hold reason, so a `null` condition also matches those movements. This field is filter-only and cannot be used as a `sort_field`.
</ParamField>

<ParamField path="options" type="object | null">
  [Options](/merchant-api/search-options) to apply to the request.
</ParamField>

### Return Value

An array of [Stock Movements](#stock-movement-properties) or an empty array.

### Example Request

Get all stock movements:

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "stock_movement.list"
    ]
}
```

Get all stock movements for warehouse "2":

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "stock_movement.list",
        [
            {
                "warehouse_id": {
                    "eq": "2"
                }
            }
        ]
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "result": {
        "results": [
            {
                "id": "12",
                "entity_type": "order",
                "entity_action": "create",
                "product_id": "4",
                "qty_expected": null,
                "qty_processed": null,
                "qty_putaway": null,
                "qty_available": "-1.0000",
                "qty_allocated": "1.0000",
                "qty_reserved": null,
                "qty_picked": null,
                "qty_backordered": null,
                "qty_held": null,
                "created_at": "2022-09-12T19:47:50+00:00",
                "sku": "12-345-6789",
                "comment": null,
                "warehouse_id": "2",
                "entity_id": "100000001",
                "location": "",
                "adjustment_reason_code": null,
                "hold_reason_code": null,
                "hold": null
            },
            {
                "id": "13",
                "entity_type": "hold",
                "entity_action": "hold",
                "product_id": "4",
                "qty_expected": null,
                "qty_processed": null,
                "qty_putaway": null,
                "qty_available": "-2.0000",
                "qty_allocated": null,
                "qty_reserved": null,
                "qty_picked": null,
                "qty_backordered": null,
                "qty_held": "2.0000",
                "created_at": "2026-07-13T10:15:00+00:00",
                "sku": "12-345-6789",
                "comment": null,
                "warehouse_id": "2",
                "entity_id": "A-01-02",
                "location": "A-01-02",
                "adjustment_reason_code": null,
                "hold_reason_code": "qc_inspection",
                "hold": {
                    "scope_type": "location",
                    "lot_id": 42,
                    "parent_hold_id": 731,
                    "reason": {
                        "code": "merchant_review",
                        "label": "Merchant Review",
                        "display_group": "Review"
                    }
                }
            }
        ],
        "totalCount": 2,
        "numPages": 1
    },
    "id": "1",
    "jsonrpc": "2.0"
}
```

### Error Codes

| code | message                                          |
| ---- | ------------------------------------------------ |
| 101  | Invalid filters given. Details in error message. |

## Entity Properties

### Stock Movement Properties

<Expandable title="Stock Movement Properties">
  <ParamField path="id" type="string">
    The internal stock movement ID.
  </ParamField>

  <ParamField path="entity_type" type="string">
    The "Type" property. Allowed values: "delivery", "order", "work\_order", "stock", "relocation", "hold".
  </ParamField>

  <ParamField path="entity_action" type="string">
    The "Action" property. Allowed values: "create", "edit", "cancel", "void", "adjust", "process", "unprocess", "putaway", "commit", "transfer", "ship", "unship", "pick", "unpick", "relocate", "pull", "push", "convert", "allocate", "deallocate", "correction", "assemble", "hold", "release".
  </ParamField>

  <ParamField path="entity_id" type="string">
    The "Entity ID" property.
  </ParamField>

  <ParamField path="product_id" type="string">
    The internal product ID.
  </ParamField>

  <ParamField path="sku" type="string">
    The "Product SKU" property.
  </ParamField>

  <ParamField path="warehouse_id" type="string">
    The internal warehouse ID.
  </ParamField>

  <ParamField path="qty_expected" type="string">
    The "Expected" qty.
  </ParamField>

  <ParamField path="qty_processed" type="string">
    The "Processed" qty.
  </ParamField>

  <ParamField path="qty_putaway" type="string">
    The "Put-Away" qty.
  </ParamField>

  <ParamField path="qty_available" type="string">
    The "Available" qty.
  </ParamField>

  <ParamField path="qty_allocated" type="string">
    The "Allocated" qty.
  </ParamField>

  <ParamField path="qty_reserved" type="string">
    The "Reserved" qty.
  </ParamField>

  <ParamField path="qty_picked" type="string">
    The "Picked" qty.
  </ParamField>

  <ParamField path="qty_backordered" type="string">
    The "Backordered" qty.
  </ParamField>

  <ParamField path="qty_held" type="string | null">
    The "Held" qty. Populated on movements that affect held quantity; otherwise null.
  </ParamField>

  <ParamField path="created_at" type="string">
    The "Timestamp" property.
  </ParamField>

  <ParamField path="comment" type="string">
    The "Comment" property.
  </ParamField>

  <ParamField path="location" type="string">
    The "Location" property.
  </ParamField>

  <ParamField path="adjustment_reason_code" type="string | null">
    The code of the structured Adjustment Reason recorded when an inventory adjustment was made (for example, a cycle count or manual correction). Allowed values: "cycle\_count", "found", "shrinkage", "damaged", "defective", "expired", "destroyed", "receiving\_error", "shipping\_error", "customer\_return", "sample", "other".
  </ParamField>

  <ParamField path="hold_reason_code" type="string | null">
    The rolled-up parent reason code for the movement's governing hold. User-defined reasons roll up to their parent system code (for example, a custom "Merchant Review" reason reports its parent "qc\_inspection"). Null when the movement has no governing hold. Filterable through the `hold_reason_code` filter using the standard filter operators.
  </ParamField>

  <ParamField path="hold" type="object | null">
    Hold detail for the movement's governing hold; null when the movement has no governing hold.

    <Expandable title="hold">
      <ParamField path="scope_type" type="string | null">
        The scope recorded on the movement's hold. Movement-producing holds currently use `location`; lot-scope sentinel holds do not create movement rows.
      </ParamField>

      <ParamField path="lot_id" type="integer | null">
        The internal lot ID recorded on the hold, or null when the held location is not associated with a lot.
      </ParamField>

      <ParamField path="parent_hold_id" type="integer | null">
        The internal parent hold ID, or null for a direct location hold. This can reference a lot-scope sentinel that has no stock movement row, so it provides partial relationship metadata and does not guarantee that the complete hold tree can be reconstructed from this endpoint.
      </ParamField>

      <ParamField path="reason" type="object | null">
        The specific hold reason applied to the movement. Null if the reason could not be resolved.

        <Expandable title="reason">
          <ParamField path="code" type="string | null">
            The exact hold reason code applied. This is the child reason and can differ from the top-level `hold_reason_code`, which rolls up to the parent system code.
          </ParamField>

          <ParamField path="label" type="string | null">
            The human-readable name of the hold reason.
          </ParamField>

          <ParamField path="display_group" type="string">
            The hold group the reason belongs to — one of the canonical English tokens ("Hold", "Review", "Expired", "Unsellable") or a custom group.
          </ParamField>
        </Expandable>
      </ParamField>
    </Expandable>
  </ParamField>
</Expandable>