List Locations
Returns all locations that belong to a merchant. There is no server-side pagination — the entire list is returned in one response.
Endpoint
GET /Merchants/{id}/locations
Path parameters
id
string
Yes
The merchantId whose locations you want to list
Request headers
X-Api-Key
{adminApiKey}
Accept
application/json
Example request
curl -X GET "https://api.test.devs.beadpay.io/Merchants/{merchantId}/locations" \
-H "X-Api-Key: {adminApiKey}"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",
"isEnabled": true,
"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": "ops@downtownflagship.com",
"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",
"isEnabled": true,
"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": "airport@downtownflagship.com",
"website": null,
"tenderTypes": ["usdcBase"],
"terminals": []
}
]Each array element is the same object returned by Get Location.
Error responses
401
Missing or invalid API key
403
Not permitted to view locations for this merchant
Best practices
Cache the result client-side for the session to avoid fetching the full list on every page change.
Filter and paginate in your UI — the server returns everything, so slice locally for performance.
Poll at most once per minute when checking for changes to stay within rate limits.
The response does not currently support server-side pagination. Watch the changelog if cursor or page parameters are added in the future.
Related pages
Last updated