Update Location

Replaces all editable fields of an existing location. PUT is a full object update. Any fields you omit will be reset to their defaults, so always send the complete object you want stored.

Endpoint

PUT /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>
Content-Type	application/json
Accept	application/json

Request body (full replacement)

Field	Type	Required	Notes
name	string	Yes	Display name shown in dashboards
address	object	Yes	Provide the full address block even if one line changed
tenderTypes	array<string>	Yes	Pass an empty array [] to inherit merchant defaults
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
highestMonthlyVolume	number or null	No	Peak expected monthly volume if known
contactPhone	string	Yes	Local formats accepted
contactEmail	string	Yes	Contact inbox for the location
website	string or null	Conditional	Required when businessType is virtual
externalId	string or null	No	Optional external reference for your system

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 PUT "https://api.test.devs.beadpay.io/Locations/loc_bfdc6a7f" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Downtown Flagship Renovated",
    "address": {
      "address1": "123 Main St",
      "address2": "Suite 300",
      "city": "Springfield",
      "region": "MA",
      "country": "US",
      "postalCode": "01109"
    },
    "businessType": "physical",
    "merchantCategoryCode": "5812",
    "additionalMerchantCategoryCodes": [],
    "descriptionOfServices": "Quick service restaurant",
    "grossAnnualVolume": 1200000,
    "highestMonthlyVolume": 150000,
    "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-09-02T16:22:11.015Z",
  "merchantId": "mer_4e5a13aa",
  "name": "Downtown Flagship Renovated",
  "externalId": "store-001",
  "address": {
    "address1": "123 Main St",
    "address2": "Suite 300",
    "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"]
}

Immutable fields

id, merchantId, and timestamp fields cannot be changed. Any attempt returns a 400 invalid request.

Error responses

Code	Condition
400	Missing required fields, immutable field modified, or validation error
401	Missing or invalid token
403	Authenticated but not permitted to update this location
404	Location id does not exist or is not visible to your token
409	Duplicate address already used by another location for this merchant
500	Unexpected server error

Best practices

Action	Why
Fetch the current object, update locally, then send the full object	Prevents accidental nulling of fields you forgot to include
Use clear names such as city and store number	Helps support locate a store quickly
Disable the location before large updates in production if the field is exposed	Avoids transactions during maintenance
Log and display the updated timestamp	Useful for audit trails and cache control

Related endpoints

• Get Location — GET /Locations/{id}

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

• Delete Location — DELETE /Locations/{id}