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
id
string
Yes
The merchantId that will own the new location
Request headers
X-Api-Key
{adminApiKey}
Content-Type
application/json
Accept
application/json
Request body
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<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.
Address object
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
Successful response — 201
Other possible success codes: 200 (location created) and 202 (accepted for asynchronous processing).
Error responses
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
merchantIdso 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}/enabledto 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.
averageTicketSizeandmaximumTicketSizeshould reflect real expected usage.Send
nullforwebsiteon physical locations. The field is required in the request — do not omit it.
Related pages
Last updated