# 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

```bash
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": "ops@downtownflagship.com",
    "website": null,
    "tenderTypes": ["usdcBase", "ethereum"],
    "externalId": "store-001"
  }'
```

#### Successful response 200

```json
{
  "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": "ops@downtownflagship.com",
  "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}`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.bead.xyz/entity-management/location-management/update-location.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.