> 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. #### 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` | | `merchantCategoryCode` | string | Yes | Four digit MCC such as `5812` | | `additionalMerchantCategoryCodes` | array\ | 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\ | 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. **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](/entity-management/location-management/list-locations.md) * [Get Location](/entity-management/location-management/get-location.md) * [Update Location](/entity-management/location-management/update-location.md) * [Create Terminal](/entity-management/terminal-management/create-terminal.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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers.bead.xyz/entity-management/location-management/create-location.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.