# Locations (/docs/api-reference/locations)

A **location** is a physical place you sell from, such as a shop or a market stall: a named point on the map with a radius. Locations anchor your in-person checkout terminals and your [drops](https://www.swopme.co/geobucks). Create and edit them in the Swop app; the API reads them.

## List locations [#list-locations]

<EndpointHeader method="GET" path="/api/v5/merchant/locations" />

Scope: **`drops.read`**

Returns your locations that aren't archived, oldest first.

```bash tab="curl"
curl https://apps.apiswop.co/api/v5/merchant/locations \
  -H "Authorization: Bearer $SWOP_MERCHANT_KEY"
```

```js tab="Node"
const res = await fetch('https://apps.apiswop.co/api/v5/merchant/locations', {
  headers: { Authorization: `Bearer ${process.env.SWOP_MERCHANT_KEY}` },
});
const { data } = await res.json();
```

```python tab="Python"
import os, requests

r = requests.get(
    "https://apps.apiswop.co/api/v5/merchant/locations",
    headers={"Authorization": f"Bearer {os.environ['SWOP_MERCHANT_KEY']}"},
)
data = r.json()["data"]
```

### Response [#response]

```json
{
  "success": true,
  "data": [
    {
      "locationId": "6701a2b3c4d5e6f7a8b9c0d1",
      "merchantId": "65f0c1a2b3c4d5e6f7a8b9c0",
      "micrositeId": null,
      "name": "Ember Coffee, Main St",
      "address": "12 Main St, Austin, TX",
      "location": { "lat": 30.2672, "lng": -97.7431 },
      "radiusMeters": 75,
      "status": "active",
      "viewerIsMerchant": true,
      "createdAt": "2026-09-16T10:00:00.000Z",
      "updatedAt": "2026-09-16T10:00:00.000Z"
    }
  ]
}
```


| Field | Meaning |
|---|---|
| `locationId` | The location's ID |
| `name`, `address` | As set in the app |
| `location` | The map pin |
| `radiusMeters` | How close someone must be, 10 to 5,000 metres (default 75) |
| `status` | `active` or `hidden` (archived locations aren't listed) |
| `micrositeId` | The SmartSite linked to this location, if any |

## Retrieve a location [#retrieve-a-location]

<EndpointHeader method="GET" path="/api/v5/merchant/locations/{id}" />

Scope: **`drops.read`**

Returns one location in the same shape, under `data`. `404` if it doesn't exist (or isn't yours and isn't active).

```bash tab="curl"
curl https://apps.apiswop.co/api/v5/merchant/locations/6701a2b3c4d5e6f7a8b9c0d1 \
  -H "Authorization: Bearer $SWOP_MERCHANT_KEY"
```

```js tab="Node"
const res = await fetch(`https://apps.apiswop.co/api/v5/merchant/locations/${id}`, {
  headers: { Authorization: `Bearer ${process.env.SWOP_MERCHANT_KEY}` },
});
```

```python tab="Python"
import os, requests

r = requests.get(
    f"https://apps.apiswop.co/api/v5/merchant/locations/{location_id}",
    headers={"Authorization": f"Bearer {os.environ['SWOP_MERCHANT_KEY']}"},
)
```

## List terminals [#list-terminals]

<EndpointHeader method="GET" path="/api/v5/merchant/locations/{id}/terminals" />

Scope: **`drops.read`**

A **terminal** is a tap-to-pay point at a location, such as an NFC tag on the counter that opens checkout when a phone taps it.

```bash tab="curl"
curl https://apps.apiswop.co/api/v5/merchant/locations/6701a2b3c4d5e6f7a8b9c0d1/terminals \
  -H "Authorization: Bearer $SWOP_MERCHANT_KEY"
```

```js tab="Node"
const res = await fetch(`https://apps.apiswop.co/api/v5/merchant/locations/${id}/terminals`, {
  headers: { Authorization: `Bearer ${process.env.SWOP_MERCHANT_KEY}` },
});
```

```python tab="Python"
import os, requests

r = requests.get(
    f"https://apps.apiswop.co/api/v5/merchant/locations/{location_id}/terminals",
    headers={"Authorization": f"Bearer {os.environ['SWOP_MERCHANT_KEY']}"},
)
```

```json title="Response"
{
  "success": true,
  "data": [
    { "terminalId": "…", "label": "Front counter", "status": "active", "programmed": true }
  ]
}
```

| Field | Meaning |
|---|---|
| `terminalId` | The terminal's ID |
| `label` | Your name for it |
| `status` | `active` or `disabled` |
| `programmed` | Whether a physical NFC tag has been written for it |
