# 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

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


---

# 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/create-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.