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	Yes	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
name	string	Yes	Display name for the location
address	object	Yes	See Address object fields below
businessType	string	Yes	physical or virtual
merchantCategoryCode	string	Yes	Four digit MCC such as 5812
additionalMerchantCategoryCodes	array<string>	Yes	Can be an empty array
descriptionOfServices	string	Yes	What the merchant sells or provides
grossAnnualVolume	number	Yes	Estimated annual processing volume
averageTicketSize	number	Yes	Typical transaction amount
maximumTicketSize	number	Yes	Maximum expected transaction amount
contactPhone	string	Yes	E.164 or local format accepted
contactEmail	string	Yes	Contact inbox for the location
website	string or null	Conditional	Required when businessType is virtual
tenderTypes	array<string>	No	Allowed rails for this location. Omit to inherit merchant defaults
externalId	string or null	No	Optional external reference for your system
highestMonthlyVolume	number or null	No	Peak expected monthly volume if known

Address object

Field	Type	Required	Notes
address1	string	Yes	Street line one
address2	string	No	Suite, floor, unit
city	string	Yes	City or locality
region	string	Yes	State or province such as MA
country	string	Yes	ISO 3166-1 alpha-2 such as US
postalCode	string	Yes	ZIP or postal code

Note: maxTransactionAmount is not used. Provide averageTicketSize and maximumTicketSize instead.

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"
    },
    "businessType": "physical",
    "merchantCategoryCode": "5812",
    "additionalMerchantCategoryCodes": [],
    "descriptionOfServices": "Quick service restaurant",
    "grossAnnualVolume": 1200000,
    "averageTicketSize": 25.00,
    "maximumTicketSize": 2000.00,
    "contactPhone": "508-555-1234",
    "contactEmail": "[email protected]",
    "website": null,
    "tenderTypes": ["usdcBase", "ethereum"],
    "externalId": "store-001"
  }'

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": ["usdcBase", "ethereum"],
  "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,
  "averageTicketSize": 25.0,
  "maximumTicketSize": 2000.0,
  "contactPhone": "508-555-1234",
  "contactEmail": "[email protected]",
  "website": null,
  "terminals": []
}

Other possible success codes

Code	When
201	Location accepted and created
202	Location accepted for asynchronous processing

Error responses

Code	Condition
400	Missing or invalid fields
401	Missing or invalid token
403	Authenticated but not permitted to create locations for the merchant
404	Merchant id does not exist or is not visible to your token
409	Duplicate location such as a location with the same address already registered
500	Unexpected server error

Best practices

• Create under the correct merchant. Pass the correct merchantId so dashboards aggregate correctly.

• Use consistent naming. A clear pattern such as city plus store number makes support lookups easier.

• Disable before delete. Always disable production locations before deleting to prevent accidental transactions.

• Ensure address accuracy. Provide the full address up front. Changing it later can affect tax or compliance data.

• Set realistic ticket sizes. Provide averageTicketSize and maximumTicketSize that match real usage.

• Include a website for virtual locations. Provide website when businessType is virtual.

Next steps

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

• Create one or more terminals under the new locationId using POST /Terminals.