# 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

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

#### Successful response 200

```json
[
  {
    "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": "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",
    "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

| 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`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.bead.xyz/entity-management/location-management/list-locations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.