List locations for a menu

Overview

Get a simple name/id list of the locations the calling user can access.

Use this to populate a location picker in your own app.

You'll need an account or partner token.

Returns a flat list of label/value pairs. Send search or limit to get a short, filtered list instead of every location.

Prerequisites

A Partner or Account token. See Authentication.

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

GET /api/v1/store/list

Authentication

Partner or Account token

The list is always the locations the user behind the token can access: a Partner token sees every location under its tree, an Account token only its own account's locations.
There are no ids to pass.

Rate limit

This endpoint has no rate limit.

Request parameters

Parameter	In	Type	Required	Description
`active_plan`	query	integer	No	`1` to list only locations on an active plan. `0` (default): all.
`appendAll`	query	integer	No	`1` to add the `All` entry even when there's only one location.
`search`	query	string	No	Return only locations whose name, `storeid` or `client_location_id` contains this text. Max 255 characters. No `All` entry is added while searching.
`limit`	query	integer	No	The most locations to return when searching, 10 to 50. Default 10 when you send `search`. Values below 10 are raised to 10; above 50 returns `422`. With neither `search` nor `limit`, every location is returned.

Request body

None.

Request payload

None.

Response body

The payload is inside data.

Field	Type	Description
`status`	string	`success`.
`response`	array	The locations. When there's more than one (or with `appendAll=1`) and no `search`, the first entry is `{"label": "All", "value": ""}`. An empty array `[]` when the user has no locations.
`response[].label`	string	The location's name, plus `- <client_location_id>` (or `- <storeid>` when it has no `client_location_id`), plus `, <state code>` when known.
`response[].value`	integer	The location's id (`store_id`). `""` for the `All` entry.

Response payload

{
  "data": {
    "status": "success",
    "response": [
      { "label": "All", "value": "" },
      { "label": "Acme Coffee - docs-test-loc-001, NSW", "value": 3007 },
      { "label": "Acme Coffee - Circular Quay - Sydney, NSW", "value": 3008 }
    ]
  }
}

Examples

Success payload

With search=Circular:

{
  "data": {
    "status": "success",
    "response": [
      { "label": "Acme Coffee - Circular Quay - Sydney, NSW", "value": 3008 }
    ]
  }
}

Error payload

422 limit too large

{
  "message": "The limit field must not be greater than 50.",
  "errors": {
    "limit": ["The limit field must not be greater than 50."]
  }
}

Status	Meaning
`200`	The locations.
`401`	The token is missing, expired or invalid.
`422`	A parameter failed validation, e.g. `limit` above 50.
`500`	Unexpected server error.

Example request

curl --request GET \
  --url "https://production-api.shoutaboutus.com/api/v1/store/list?active_plan=1&appendAll=1" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'

Updated 17 days ago

Did this page help you?