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

Request body

Field	Type	Required	Description
name	string	Yes	Display name shown in dashboards
address	object	Yes	Provide the full address block even if only one field changed
businessType	string	Yes	physical, virtual, or both
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	No	Required when businessType is virtual or both. Send null for physical locations
tenderTypes	array<string>	No	Pass an empty array [] to inherit merchant defaults
highestMonthlyVolume	number or null	No	Peak expected monthly volume if known
externalId	string or null	No	Optional external reference for your system

Note: maxTransactionAmount is not used at the location level. Use averageTicketSize and maximumTicketSize instead.

Address object

Field	Type	Required	Description
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

Example request

curl -X PUT "https://api.test.devs.beadpay.io/Locations/{locationId}" \
  -H "X-Api-Key: {adminApiKey}" \
  -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": "[e-mail]",
    "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",
  "isEnabled": true,
  "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": "[e-mail]",
  "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 error.

Error responses

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

Best practices

• Fetch the current object first, update locally, then send the full object back. This prevents accidentally nulling fields you didn't intend to change.

• Use PUT /Locations/{id}/enabled to disable a location before making large updates in production.

• Use the updated timestamp for audit trails and cache invalidation.

• Use clear, consistent location names — city and store number makes support lookups easier.

Related pages

• Get Location

• List Locations

• Delete Location