---
title: "List warehouse locations with pagination"
method: POST
path: "/api/warehouse/location/list"
tags: ["Warehouse"]
---

# List warehouse locations with pagination

`POST /api/warehouse/location/list`

## Request

- Base URL: `https://api.desty.app`
- URL: `https://api.desty.app/api/warehouse/location/list`
- Auth: none declared. Required headers: `Authorization`

Returns a flat location list. Filters are combined; Default Storage participates in matching.

Pagination is optional: supply both `pageNumber` and `pageSize`, or omit both.

## Headers

- `Authorization` string, required

## Request body

- object
  - `externalWarehouseId` string, required: External warehouse ID from /api/warehouse/list, belonging to the authenticated tenant.
  - `parentLocationId` union: Optional parent location ID. Omit/null to search the whole warehouse. With a parent, return its direct children unless includeDescendants=true; exclude the parent itself. 64-bit ID; send as a decimal string (recommended) or a number.
    - string
    - integer
  - `level` integer, nullable: Optional exact level-number filter; normally 1–7. A nonmatching level returns no rows.
  - `keyword` string, nullable: Optional case-insensitive substring of the location's own name. Trimmed before filtering.
  - `includeDescendants` boolean, nullable: With parentLocationId: true includes all descendants; omitted/null/false includes direct children only.
  - `pageNumber` integer, nullable: Optional. Supply together with pageSize; omit both to return all matching locations.
  - `pageSize` integer, nullable: Optional (1–200). Supply together with pageNumber.

## Response `200`

successful operation

- object
  - `code` string, required: Business result code: "0" on success; otherwise INVALID_PARAMETER, INVALID_TOKEN, LIMIT_REQUEST or SERVER_ERROR.
  - `msg` string, nullable: Result message; normally null on success.
  - `data` object, nullable
    - `storageActivated` boolean, required: Whether Storage Locations are activated. If false, totalCount=0 and results=[].
    - `totalCount` string, int64, required: Number of matching locations before pagination. Returned as a decimal string in this endpoint.
    - `results` object[], required: Flat list sorted by level, then locationId, ascending. Includes Default Storage when it matches the filters.
      - `locationId` string, required: Location ID. 64-bit ID returned as a decimal string.
      - `locationName` string, required: Location's own name, without ancestors.
      - `parentLocationId` string, nullable: Parent location ID; null when no parent. 64-bit ID returned as a decimal string.
      - `level` integer, required: Location level number. Default Storage is returned at level 7.
      - `path` string, required: Warehouse name followed by the location's full path, separated by ' / ' (space, slash, space), e.g. "Gudang A / Zone 1 / Bin 01".
      - `isUnassigned` boolean, required: True for the warehouse's Default Storage location.
      - `childCount` integer, required: Number of direct child locations; not the total number of descendants.
      - `skuCount` integer, nullable: Number of SKUs directly associated with a normal Storage location, including zero-stock associations. Null for Organizational and, in the current implementation, Default Storage.
      - `status` 'OCCUPIED' | 'EMPTY' | 'null', nullable: OCCUPIED when directly associated product count is greater than zero; otherwise EMPTY. Null for Organizational.
      - `stockToMarketplace` boolean, nullable: Marketplace-stock flag returned by the storage service. Organizational locations cannot operate this switch.
      - `storingPreference` 'ORGANIZATIONAL' | 'STORAGE', required: Effective storage type inherited from the location level. The system Default Storage is STORAGE.
      - `updatedAt` integer, nullable, required: This location's last update time as a UTC Unix timestamp in milliseconds, encoded as a JSON number. For example, 1793689500123 represents 2026-11-03T07:05:00.123Z. Null when the source timestamp is absent.
    - `pageNumber` integer: Requested page number; omitted when pagination is not requested.
    - `pageSize` integer: Requested page size; omitted when pagination is not requested.
  - `success` boolean, required: True when code equals "0".

## Changes

- **2026-11-06** `4946760fb77d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/desty/apis/desty-omni-openapi-2026-6-26/changes/api/warehouse/location/list/post.md)

---

[API](https://skmtc.dev/desty/apis/desty-omni-openapi-2026-6-26.md) - [All operations](https://skmtc.dev/desty/apis/desty-omni-openapi-2026-6-26/llms.txt) - [OpenAPI document](https://skmtc.dev/desty/apis/desty-omni-openapi-2026-6-26/revisions/4946760fb77d?raw)