List Locations

Returns all locations that belong to a merchant. The current implementation has no server-side pagination—the entire list is returned in one response.

Endpoint

GET /Merchants/{id}/locations

Path parameters

Name	Type	Required	Description
id	string	✔︎	The merchantId whose locations you want to list

Request headers

Header	Value
Authorization	Bearer <access-token>
Accept	application/json

Example request

curl -X GET "https://api.test.devs.beadpay.io/Merchants/mer_4e5a13aa/locations" \
     -H "Authorization: Bearer $TOKEN"

Successful response — 200

[
  {
    "id": "loc_bfdc6a7f",
    "created": "2025-06-04T16:08:03.226Z",
    "updated": "2025-06-04T16:08:03.226Z",
    "merchantId": "mer_4e5a13aa",
    "name": "Downtown Flagship",
    "tenderTypes": ["ethereum"],
    "maxTransactionAmount": 1000000,
    "address": {
      "address1": "123 Main St",
      "address2": "Suite 200",
      "city": "Springfield",
      "region": "MA",
      "country": "US",
      "postalCode": "01109"
    }
  },
  {
    "id": "loc_c3d1e8fa",
    "created": "2025-06-12T09:15:44.112Z",
    "updated": "2025-06-12T09:15:44.112Z",
    "merchantId": "mer_4e5a13aa",
    "name": "Airport Kiosk",
    "tenderTypes": [],
    "maxTransactionAmount": 0,
    "address": {
      "address1": "987 Terminal Rd",
      "city": "Springfield",
      "region": "MA",
      "country": "US",
      "postalCode": "01109"
    }
  }
]

Each array element is the same object returned by Get Location, minus the nested terminals list.

Error responses

Code	Condition
404	Merchant {id} does not exist or is not visible to your token

Best practices for large estates

✔︎ Action	Why
Cache the result client-side for the session	Avoids fetching the full list on every page change
Filter and paginate in your UI	Server returns everything; handle slicing locally
Request once per minute at most when polling for changes	Reduces bandwidth and keeps within rate limits
Watch for future pagination in the changelog	Endpoint will add cursor or page/size params when merchant estates grow

Related endpoints

• Create Location – POST /Merchants/{id}/locations

• Get / Update / Delete Location – manage individual records

• List Terminals for Location – GET /Locations/{id}/terminals to drill into devices under a store