Time	Status	User Agent
Retrieving recent requests…

Get locations

Search and retrieve stores, zones, tills, and concepts in your org. Filter by type, entity code, name, code, or external ID. Results are paginated and sorted by last update time by default.

Example request

curl -X GET "https://{host}/v2/locations?type=STORE&limit=1" \
  -H "Authorization: Basic {base64-encoded-credentials}" \
  -H "X-CAP-API-AUTH-ORG-ID: {orgId}"

Prerequisites

Authenticate using Basic authentication (Base64-encoded username:password).

Resource information


Pagination support	Yes
Batch support	No

Query parameters

Field	Type	Required	Description
`type`	string	Optional	Filter by location type. Must be one of: `STORE`, `ZONE`, `TILL`, `CONCEPT`. Case-insensitive. Omit to return all types.
`entityCodes`	string	Optional	Comma-separated list of entity codes to filter by. Maximum 30 codes.
`q`	string	Optional	Prefix filter in `field:value` format. Valid fields: `name`, `code`, `external_id`. Comma-separate multiple filters (for example, `name:North,code:store`). When multiple filters are provided, results match any one of them (OR logic). Each field may appear at most once.
`isActive`	boolean	Optional	Filter by active status. `true` returns active locations only; `false` returns inactive locations only. Omit to return both.
`isAdmin`	boolean	Optional	Filter by admin access. `true` returns locations with admin access only; `false` returns locations with general access only. Omit to return all.
`isOrgUnit`	boolean	Optional	Filter by org unit status. Works with any `type`; most relevant for `type=CONCEPT`.
`limit`	integer	Optional	Number of results per page. Between 1 and 100. Defaults to `20`.
`offset`	integer	Optional	Number of results to skip. Must be non-negative. Defaults to `0`.
`sortBy`	string	Optional	Field to sort results by. Must be one of: `entityCode`, `name`, `lastUpdated`. Defaults to `lastUpdated`.
`sortOrder`	string	Optional	Sort direction. Must be one of: `ASC`, `DESC`. Defaults to `DESC`.
`includeCustomFields`	boolean	Optional	When `true`, includes custom field values for each location in the response. Defaults to `false`.
`includeChildren`	boolean	Conditional	When `true`, returns child locations under `hierarchy.children`. Requires `entityCodes` to contain exactly one code.
`childrenLimit`	integer	Conditional	Number of child results per page. Between 1 and 100. Defaults to `10`. Only applies when `includeChildren=true`.
`childrenOffset`	integer	Conditional	Number of child results to skip. Must be non-negative. Defaults to `0`. Only applies when `includeChildren=true`.

Example response

{
  "limit": 1,
  "offset": 0,
  "total": 10,
  "data": [
    {
      "id": 76100001,
      "type": "STORE",
      "code": "store-north-01",
      "externalIds": {
        "erpId": "ERP-STORE-001"
      },
      "name": "North Flagship Store",
      "description": "Main flagship store in the north region",
      "isActive": true,
      "isDefault": false,
      "isAdmin": false,
      "isOuEnabled": false,
      "createdBy": 76100002,
      "createdOn": "2026-06-30T08:54:23Z",
      "lastUpdatedOn": "2026-06-30T13:31:08Z",
      "lastUpdatedBy": 76100003,
      "timezoneId": 191,
      "languageId": 148,
      "currencyId": 23,
      "standardAttributes": {
        "currency": "INR",
        "language": "en-IN",
        "latitude": "28.6139",
        "longitude": "77.2090",
        "timezone": "Asia/Kolkata"
      },
      "hierarchy": {
        "areaParent": {
          "id": 76100010,
          "type": "ZONE",
          "name": "North Zone",
          "code": "north-zone",
          "externalIds": {
            "erpId": "ERP-ZONE-NORTH"
          }
        },
        "groupParent": {
          "id": 76100020,
          "type": "CONCEPT",
          "name": "Flagship Concept",
          "code": "flagship",
          "isOrgUnit": false
        }
      },
      "email": "[email protected]",
      "mobile": "9876543210",
      "landline": "01123456789"
    }
  ]
}

{
  "limit": 1,
  "offset": 0,
  "total": 10,
  "data": [
    {
      "id": 76100001,
      "type": "STORE",
      "code": "store-north-01",
      "externalIds": {
        "erpId": "ERP-STORE-001"
      },
      "name": "North Flagship Store",
      "description": "Main flagship store in the north region",
      "isActive": true,
      "isDefault": false,
      "isAdmin": false,
      "isOuEnabled": false,
      "createdBy": 76100002,
      "createdOn": "2026-06-30T08:54:23Z",
      "lastUpdatedOn": "2026-06-30T13:31:08Z",
      "lastUpdatedBy": 76100003,
      "timezoneId": 191,
      "languageId": 148,
      "currencyId": 23,
      "customFields": {
        "StoreCF": "flagship",
        "age": "5"
      },
      "standardAttributes": {
        "currency": "INR",
        "language": "en-IN",
        "latitude": "28.6139",
        "longitude": "77.2090",
        "timezone": "Asia/Kolkata"
      },
      "hierarchy": {
        "areaParent": {
          "id": 76100010,
          "type": "ZONE",
          "name": "North Zone",
          "code": "north-zone",
          "externalIds": {
            "erpId": "ERP-ZONE-NORTH"
          }
        },
        "groupParent": {
          "id": 76100020,
          "type": "CONCEPT",
          "name": "Flagship Concept",
          "code": "flagship",
          "isOrgUnit": false
        }
      },
      "email": "[email protected]",
      "mobile": "9876543210",
      "landline": "01123456789"
    }
  ]
}

Response parameters

Field	Type	Description
`limit`	integer	Page size used for this response.
`offset`	integer	Pagination offset used for this response.
`total`	integer	Total number of matching locations.
`data`	array	List of location objects.
`.id`	integer	System-assigned ID of the location.
`.type`	string	Type of the location. Possible values: `STORE`, `ZONE`, `TILL`, `CONCEPT`.
`.code`	string	Unique code identifying the location within the org.
`.name`	string	Display name of the location.
`.description`	string	Free-text description. Returns an empty string when set to empty.
`.isActive`	boolean	Whether the location is active.
`.isDefault`	boolean	Whether this is the default location for the org.
`.isAdmin`	boolean	Whether the location has admin access.
`.isOuEnabled`	boolean	Whether the location is configured as an org unit.
`.externalIds`	object	Key-value map of external identifiers (for example, `{"erpId": "ERP-001"}`). Absent when no external identifiers are assigned.
`.createdBy`	integer	User ID of the user who created this location. Absent when not available.
`.createdOn`	string	Creation timestamp in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`), in UTC. Absent when not available.
`.lastUpdatedOn`	string	Last-update timestamp in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`), in UTC.
`.lastUpdatedBy`	integer	User ID of the last updater. Absent when not available.
`.timezoneId`	integer	System ID of the location's timezone.
`.languageId`	integer	System ID of the location's language.
`.currencyId`	integer	System ID of the location's currency.
`.customFields`	object	Key-value map of custom field values for this location. Present only when `includeCustomFields=true`.
`.standardAttributes`	object	Object containing standard attribute values for the location.
`..currency`	string	ISO 4217 currency code (for example, `INR`). Absent when the location's currency is not configured.
`..language`	string	IETF BCP 47 language tag (for example, `en-IN`). Absent when the location's language is not configured.
`..timezone`	string	Timezone name (for example, `Asia/Kolkata`). Absent when the location's timezone is not configured.
`..latitude`	string	Latitude coordinate. Present for stores only. Returns an empty string when coordinates are not configured.
`..longitude`	string	Longitude coordinate. Present for stores only. Returns an empty string when coordinates are not configured.
`.hierarchy`	object	Object containing hierarchy relationships for this location. Structure varies by location type.
`..areaParent`	object	Object containing the area parent. Present for stores and zones.
`..groupParent`	object	Object containing the group parent (concept). Present for stores and concepts.
`..parent`	object	Object containing the direct parent store. Present for tills only.
`..children`	array	List of child location objects. Present when `includeChildren=true` with a single entity code.
`..totalChildCount`	integer	Total count of child entities. Present when `includeChildren=true`.
`...id`	integer	System-assigned ID of the related location.
`...type`	string	Type of the related location. Possible values: `STORE`, `ZONE`, `TILL`, `CONCEPT`.
`...name`	string	Display name of the related location.
`...code`	string	Code of the related location.
`...externalIds`	object	Key-value map of external identifiers for the related location. Absent when none are assigned.
`...isOrgUnit`	boolean	Whether the related location is an org unit. Present for concept hierarchy entries only.
`.email`	string	Email address of the store. Present for stores only. Returns an empty string when not configured.
`.mobile`	string	Mobile number of the store. Present for stores only. Returns an empty string when not configured.
`.landline`	string	Landline number of the store. Present for stores only. Returns an empty string when not configured.

Error and warning codes

Code	Error number	Type	Description
`PARAM_TYPE_IS_NOT_VALID`	1217	Error	`type` is not one of `STORE`, `ZONE`, `TILL`, `CONCEPT`. HTTP 400.
`INVALID_LOCATIONS_Q_FORMAT`	1236	Error	`q` is not in `field:value` format, contains an invalid field name, has an empty value, or repeats a field. Valid fields: `name`, `code`, `external_id`. HTTP 400.
`ENTITY_CODES_MAX_30_EXCEEDED`	1237	Error	`entityCodes` contains more than 30 codes. HTTP 400.
`INVALID_LOCATIONS_SORT_BY`	1238	Error	`sortBy` is not one of `entityCode`, `name`, `lastUpdated`. HTTP 400.
`INVALID_LOCATIONS_SORT_ORDER`	1239	Error	`sortOrder` is not `ASC` or `DESC`. HTTP 400.
`LOCATIONS_LIMIT_OUT_OF_RANGE`	1240	Error	`limit` is not between 1 and 100. HTTP 400.
`LOCATIONS_OFFSET_NEGATIVE`	1241	Error	`offset` is negative. HTTP 400.
`LOCATIONS_CHILDREN_LIMIT_OUT_OF_RANGE`	1242	Error	`childrenLimit` is not between 1 and 100. HTTP 400.
`LOCATIONS_CHILDREN_OFFSET_NEGATIVE`	1243	Error	`childrenOffset` is negative. HTTP 400.
`INCLUDE_CHILDREN_REQUIRES_SINGLE_ENTITY_CODE`	1244	Error	`includeChildren=true` requires `entityCodes` to contain exactly one code. HTTP 400.

Get locations

Example request

Prerequisites

Resource information

Query parameters

Example response

Response parameters

Error and warning codes

200Locations retrieved successfully.

400Invalid query parameters.