Create Location

Creates a new store or branch (“location”) under an existing merchant. The call returns a locationId that you will reference when you create terminals or pull reporting data.

Endpoint

POST /Merchants/{id}/locations

Purpose

Attach a new location to the merchant identified by {id} and return its unique identifier.

Path parameters

Name	Type	Required	Description
id	string	✔︎	The merchantId that will own the new location

Request headers

Header	Value
Authorization	Bearer <access-token>
Content-Type	application/json
Accept	application/json

Request body

Field	Type	Required	Notes
address	object	✔︎	Must include at least address1, city, country, postalCode
name	string	✘	Friendly label shown in dashboards (e.g., “Downtown Flagship”)
tenderTypes	array<string>	✘	Allowed rails; omit to inherit merchant defaults
maxTransactionAmount	integer	✘	Hard ceiling (minor units) for a single sale; 0 = no limit

Example request

curl -X POST "https://api.test.devs.beadpay.io/Merchants/mer_4e5a13aa/locations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Downtown Flagship",
        "address": {
          "address1": "123 Main St",
          "address2": "Suite 200",
          "city": "Springfield",
          "region": "MA",
          "country": "US",
          "postalCode": "01109"
        },
        "maxTransactionAmount": 1000000,
        "tenderTypes": ["ethereum"]
      }'

Successful response — 200

{
  "id": "loc_bfdc6a7f",
  "created": "2025-06-04T16:08:03.226Z",
  "updated": "2025-06-04T16:08:03.226Z",
  "merchantId": "mer_4e5a13aa",
  "name": "Downtown Flagship",
  "tenderTypes": ["ethereum"],
  "maxTransactionAmount": 1000000,
  "address": {
    "address1": "123 Main St",
    "address2": "Suite 200",
    "city": "Springfield",
    "region": "MA",
    "country": "US",
    "postalCode": "01109"
  },
  "terminals": []
}

Field	Description
id	New locationId; store for later calls
created, updated	ISO-8601 timestamps (UTC)
tenderTypes	Effective tender list after inheritance rules
terminals	Empty until you create terminals

Error responses

Code	Condition
400	Missing required address fields or invalid values
404	Merchant {id} does not exist or is not visible to your token
409	Duplicate location (same address already registered for this merchant)

Best practices

• Create under the right merchant – pass the correct merchantId so dashboards aggregate correctly

• Consistent naming – adopt a clear pattern (city + store #) to ease support look-ups

• Disable before delete – always disable production locations before deleting to prevent accidental transactions

• Address accuracy – provide the full address up front; correcting it later may affect tax or compliance data

Next steps

• Confirm the store appears with GET /Merchants/{id}/locations

• Create one or more terminals under the new locationId (POST /Terminals)