List all locations under your partner

Overview

Get every location across every account under your partner, with its account name, address, and current plan.

Use this for a partner-level view of everything you manage, or to find a location's store_id.

You'll need a partner token. Results are paginated. Add call_for=dropdown to get a simple name/ID list instead.

Returns one entry per active or pending location.

Prerequisites

A Partner token. See Authentication.

Base URL

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

Endpoint

GET /api/v1/partner/store/list

Authentication

Partner token

Lists locations in accounts under your partner and under your sub-partners.
A user who is assigned to particular accounts or locations sees only those accounts' locations.
account_id and client_account_id must be inside your account tree; otherwise 422. A location_id or client_location_id that isn't one of yours returns an empty page.

Rate limit

This endpoint has no rate limit.

Request parameters

Parameter	In	Type	Required	Description
`limit`	query	integer	No	Page size, 10 to 100. Default 10. Values below 10 are raised to 10; above 100 returns `422`. With `call_for=dropdown`, at most 50 entries are returned, and with no `limit` the whole list is returned.
`page`	query	integer	No	Page number. Default 1.
`plan_subscription`	query	string	No	`all` (default), `active` (the location's latest plan is active or expired) or `inactive` (it's inactive or closed).
`active_plan`	query	integer	No	Ignored by this endpoint. Use `plan_subscription`.
`account_id`	query	integer	No	Return only this account's locations.
`client_account_id`	query	string	No	Return only the locations of the account with this id of yours. Max 255 characters.
`location_id`	query	integer	No	Return only this location. Must be an existing location id.
`client_location_id`	query	string	No	Return only the location with this id of yours. Max 255 characters.
`call_for`	query	string	No	`dropdown` to get a label/value list instead of the paginated list.
`sort_field`	query	string	No	A field of the response to sort by, e.g. `store_name` (default), `account_name` or `plan_name`.
`sort_by`	query	string	No	`ASC` (default) or `DESC`.
`search_field`	query	string	No	`name` (also matches `client_location_id` and `storeid`), `storeid`, `client_location_id`, `full_address`, `plan_name` (exact match) or `account_name`. Use with `search_value`.
`search_value`	query	string	No	The text to search for.

Request body

None.

Request payload

None.

Response body

The paginated list. Each entry in data is one location.

Field	Type	Description
`data`	array	The locations on this page.
`data[].id`	integer	The location's id (`store_id`).
`data[].name`	string	The location's name.
`data[].storeid`	string	The location's display label.
`data[].client_location_id`	string or null	Your own id for the location.
`data[].account_name`	string	The account's name.
`data[].store_name`	string	The name, plus `- <storeid>` when it has one.
`data[].full_address`	string	The address, plus `- <address2>` when it has a second line.
`data[].address1`	string	Street address.
`data[].address2`	string or null	Second address line.
`data[].zip`	string	Postal code.
`data[].plan_name`	string or null	The plan on the location's latest subscription.
`data[].activation_date`	string or null	When that subscription started.
`data[].expiry_date`	string or null	When that subscription ends.
`data[].cancellation_date`	string or null	When it was cancelled, or `null`.
`data[].sub_partner_name`	string or null	The sub-partner the location belongs to, or `null` when its account sits directly under your partner.
`links`	object	URLs of the `first`, `last`, `prev` and `next` pages (`null` when there's no such page).
`meta`	object	Paging details: `current_page`, `from`, `last_page`, `links`, `path`, `per_page`, `to` and `total`.

With call_for=dropdown, the payload is inside data instead:

Field	Type	Description
`status`	string	`success`.
`response`	array	The locations. When there's more than one and no `search_value`, the first entry is `{"label": "All", "value": ""}`.
`response[].label`	string	The location's name, plus `- <client_location_id>` (or `- <storeid>` when it has no `client_location_id`).
`response[].value`	integer	The location's id.

Response payload

{
  "data": [
    {
      "id": 3007,
      "name": "Acme Coffee",
      "storeid": "Sydney",
      "client_location_id": "docs-test-loc-001",
      "account_name": "Acme Coffee",
      "store_name": "Acme Coffee - Sydney",
      "full_address": "1 George St",
      "address1": "1 George St",
      "address2": null,
      "zip": "2000",
      "plan_name": "Growth — Unlimited",
      "activation_date": "2026-10-01 01:00:23",
      "expiry_date": "2026-10-31 23:59:59",
      "cancellation_date": null,
      "sub_partner_name": null
    }
  ],
  "links": {
    "first": "https://production-api.shoutaboutus.com/api/v1/partner/store/list?page=1",
    "last": "https://production-api.shoutaboutus.com/api/v1/partner/store/list?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      { "url": null, "label": "&laquo; Previous", "page": null, "active": false },
      { "url": "https://production-api.shoutaboutus.com/api/v1/partner/store/list?page=1", "label": "1", "page": 1, "active": true },
      { "url": null, "label": "Next &raquo;", "page": null, "active": false }
    ],
    "path": "https://production-api.shoutaboutus.com/api/v1/partner/store/list",
    "per_page": 10,
    "to": 1,
    "total": 1
  }
}

Examples

Success payload

With call_for=dropdown:

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

Error payload

422 Page size too large

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

422 Account outside your tree

{
  "message": "The selected account id does not belong to your company hierarchy.",
  "errors": {
    "account_id": ["The selected account id does not belong to your company hierarchy."]
  }
}

Status	Meaning
`200`	The locations.
`401`	The token is missing, expired or invalid.
`422`	A parameter failed validation, e.g. `limit` above 100, an unknown `plan_subscription`, or an account outside your tree.
`500`	Unexpected server error.

Example request

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