# 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`.