Get Location

Retrieves the full details of a single location, including address, tender type settings, and current metadata.

Endpoint

GET /Locations/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The locationId returned when the location was created

Request headers

Header	Value
Authorization	Bearer <access_token>
Accept	application/json

Example request

curl -X GET "https://api.test.devs.beadpay.io/Locations/loc_bfdc6a7f" \
     -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"]
}

Field reference

Field	Description
id	Unique locationId
created, updated	ISO 8601 timestamps in UTC
merchantId	Parent merchant identifier
name	Friendly display name
externalId	Optional external reference used by your system
address.*	Full postal address object
businessType	physical or virtual
merchantCategoryCode	Four digit MCC such as 5812
additionalMerchantCategoryCodes	Optional list of additional MCCs, can be empty
descriptionOfServices	What the merchant sells or provides
grossAnnualVolume	Estimated annual processing volume
highestMonthlyVolume	Peak expected monthly volume if known
averageTicketSize	Typical transaction amount
maximumTicketSize	Maximum expected transaction amount
contactPhone, contactEmail	Primary contact details for the location
website	Required when businessType is virtual, otherwise optional
tenderTypes	Enabled rails for this location
terminals	Array of terminal identifiers under this location. For details, call GET /Locations/{id}/terminals.

Error responses

Code	Condition
401	Missing or invalid token
403	Authenticated but not permitted to view this location
404	Location id does not exist or is not visible to your token

Best practices

• Cache the response to avoid redundant calls when rendering dashboards

• Use the updated timestamp to decide when to refresh local copies

• If the terminal list is large, use GET /Locations/{id}/terminals for a paginated view

Related endpoints

• Update Location — PUT /Locations/{id}

• Delete Location — DELETE /Locations/{id}

• List Locations — GET /Merchants/{id}/locations