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
X-Api-Key	{adminApiKey}
Accept	application/json

Example request

curl -X GET "https://api.test.devs.beadpay.io/Locations/{locationId}" \
     -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": "[e-mail]",
  "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
isEnabled	Whether the location is currently accepting new transactions
externalId	Optional external reference used by your system
address.*	Full postal address object
businessType	physical, virtual, or both
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 or both, otherwise null
tenderTypes	Enabled tender rails for this location
terminals	Array of terminal IDs under this location. Use GET /Locations/{id}/terminals for full terminal details

Error responses

Code	Condition
401	Missing or invalid API key
403	Not permitted to view this location
404	Location {id} does not exist or is not visible to your key

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 rather than reading the terminals array from this response.

Related pages

• Update Location

• Delete Location

• List Locations

• List Terminals