> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/entity-management/location-management/create-location.md).

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

{% hint style="warning" %}
**Boarding creates the location and terminals for you.** When a merchant application is boarded through [Onboarding](https://developers.bead.xyz/onboarding.md), Bead creates the merchant, its location, and its terminals as part of boarding. Do not create your own location or terminal for a merchant that is still in onboarding, or before the application reaches `boarded`. Use this endpoint to add further locations to a merchant that has already been boarded. Use Get Status to confirm the application status and to retrieve `onboardedMerchantId`.
{% endhint %}

#### Endpoint

`POST /Merchants/{id}/locations`

#### Path parameters

| Name | Type   | Required | Description                                     |
| ---- | ------ | -------- | ----------------------------------------------- |
| `id` | string | Yes      | The `merchantId` that will own the new location |

#### 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 for the location                                                           |
| `address`                         | object         | Yes      | See Address object below                                                                |
| `businessType`                    | string         | Yes      | `physical`, `virtual`, or `both`. See Business type values below                        |
| `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 | Yes      | Required when `businessType` is `virtual` or `both`. Send `null` for physical locations |
| `tenderTypes`                     | array\<string> | No       | Tender types 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                                                   |

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

**Business type values**

| Value      | Use when                                                                 |
| ---------- | ------------------------------------------------------------------------ |
| `physical` | The location takes payments in person only. Send `website` as `null`.    |
| `virtual`  | The location takes payments online only. `website` is required.          |
| `both`     | The location takes payments in person and online. `website` is required. |

These are the only accepted values. Send them in lowercase exactly as shown.

**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

```bash
curl -X POST "https://api.test.devs.beadpay.io/Merchants/{merchantId}/locations" \
  -H "X-Api-Key: {adminApiKey}" \
  -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 — 201

```json
{
  "id": "loc_bfdc6a7f",
  "created": "2025-06-04T16:08:03.226Z",
  "updated": "2025-06-04T16:08:03.226Z",
  "merchantId": "mer_4e5a13aa",
  "name": "Downtown Flagship",
  "isEnabled": true,
  "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: `200` (location created) and `202` (accepted for asynchronous processing).

#### Error responses

| Code | Condition                                                                   |
| ---- | --------------------------------------------------------------------------- |
| 400  | Missing or invalid fields                                                   |
| 401  | Missing or invalid API key                                                  |
| 403  | Not permitted to create locations for this merchant                         |
| 404  | Merchant `{id}` does not exist or is not visible to your key                |
| 409  | Duplicate location — a location with the same address is 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. Use `PUT /Locations/{id}/enabled` to stop new payments before decommissioning.
* Ensure address accuracy. Provide the full address up front — changing it later can affect tax or compliance data.
* Set realistic ticket sizes. `averageTicketSize` and `maximumTicketSize` should reflect real expected usage.
* Send `null` for `website` on physical locations. The field is required in the request — do not omit it.

#### Related pages

* [List Locations](https://developers.bead.xyz/entity-management/location-management/list-locations.md)
* [Get Location](https://developers.bead.xyz/entity-management/location-management/get-location.md)
* [Update Location](https://developers.bead.xyz/entity-management/location-management/update-location.md)
* [Create Terminal](https://developers.bead.xyz/entity-management/terminal-management/create-terminal.md)
* [Get Status](https://developers.bead.xyz/onboarding/get-status.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
