List Locations

Returns all locations that belong to a merchant. There is no server side pagination. The entire list returns in one response.

Endpoint

GET /Merchants/{id}/locations

Path parameters

Name	Type	Required	Description
id	string	Yes	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-09-02T16:08:03.226Z",
    "updated": "2025-09-02T16:08:03.226Z",
    "merchantId": "mer_4e5a13aa",
    "name": "Downtown Flagship",
    "externalId": "store-001",
    "address": {
      "address1": "123 Main St",
      "address2": "Suite 200",
      "city": "Springfield",
      "region": "MA",
      "country": "US",
      "postalCode": "01109"
    },
    "businessType": "physical",
    "merchantCategoryCode": "5812",
    "additionalMerchantCategoryCodes": [],
    "descriptionOfServices": "Quick service restaurant",
    "grossAnnualVolume": 1200000,
    "highestMonthlyVolume": 150000,
    "averageTicketSize": 25.0,
    "maximumTicketSize": 2000.0,
    "contactPhone": "508-555-1234",
    "contactEmail": "[email protected]",
    "website": null,
    "tenderTypes": ["usdcBase", "ethereum"],
    "terminals": ["term_123", "term_456"]
  },
  {
    "id": "loc_c3d1e8fa",
    "created": "2025-09-02T09:15:44.112Z",
    "updated": "2025-09-02T09:15:44.112Z",
    "merchantId": "mer_4e5a13aa",
    "name": "Airport Kiosk",
    "externalId": null,
    "address": {
      "address1": "987 Terminal Rd",
      "address2": null,
      "city": "Springfield",
      "region": "MA",
      "country": "US",
      "postalCode": "01109"
    },
    "businessType": "physical",
    "merchantCategoryCode": "5812",
    "additionalMerchantCategoryCodes": [],
    "descriptionOfServices": "Grab and go food",
    "grossAnnualVolume": 300000,
    "highestMonthlyVolume": 60000,
    "averageTicketSize": 18.0,
    "maximumTicketSize": 600.0,
    "contactPhone": "508-555-5678",
    "contactEmail": "[email protected]",
    "website": null,
    "tenderTypes": ["usdcBase"],
    "terminals": []
  }
]

Each array element is the same object returned by Get Location.

Error responses

Code	Condition
401	Missing or invalid token
403	Authenticated but not permitted to view locations for the merchant

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	The server returns everything, so slice locally for performance
Request at most once per minute when polling for changes	Reduces bandwidth and stays within rate limits
Watch the changelog for future pagination	Cursor or page and size parameters may be added later

Related endpoints

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

• Get Location — GET /Locations/{id}

• List Terminals for Location — GET /Locations/{id}/terminals