API Explorer

You are viewing an old version of the API

All Versions

Create location

POST /v2/locations

Creates a location.

Open in API Reference

Access Tokens Sign in to populate your access tokens from the developer dashboard Sign In

Body

location

The initial values of the location being created. The name field is required and must be unique within a seller account. All other fields are optional, but any information you care about for the location should be included. The remaining fields are automatically added based on the data from the main location.

Location

address

The physical address of the location.

Address

address_line_1

The first line of the address.

Fields that start with address_line provide the address's most specific details, like street number, street name, and building name. They do not provide less specific details like city, state/province, or country (these details are provided in other fields).

string

address_line_2

The second line of the address, if any.

string

address_line_3

The third line of the address, if any.

string

administrative_district_level_1

A civil entity within the address's country. In the US, this is the state. For a full list of field meanings by country, see Working with Addresses.

string

administrative_district_level_2

A civil entity within the address's administrative_district_level_1. In the US, this is the county.

string

administrative_district_level_3

A civil entity within the address's administrative_district_level_2, if any.

string

country

The address's country, in the two-letter format of ISO 3166. For example, US or FR.

string

Select country

AU Australia
CA Canada
GB United Kingdom
IE Ireland
JP Japan
US United States of America

ZZ Unknown
AD Andorra
AE United Arab Emirates
AF Afghanistan
AG Antigua and Barbuda
AI Anguilla
AL Albania
AM Armenia
AO Angola
AQ Antartica
AR Argentina
AS American Samoa
AT Austria
AU Australia
AW Aruba
AX land Islands
AZ Azerbaijan
BA Bosnia and Herzegovina
BB Barbados
BD Bangladesh
BE Belgium
BF Burkina Faso
BG Bulgaria
BH Bahrain
BI Burundi
BJ Benin
BL Saint Barthlemy
BM Bermuda
BN Brunei
BO Bolivia
BQ Bonaire
BR Brazil
BS Bahamas
BT Bhutan
BV Bouvet Island
BW Botswana
BY Belarus
BZ Belize
CA Canada
CC Cocos Islands
CD Democratic Republic of the Congo
CF Central African Republic
CG Congo
CH Switzerland
CI Ivory Coast
CK Cook Islands
CL Chile
CM Cameroon
CN China
CO Colombia
CR Costa Rica
CU Cuba
CV Cabo Verde
CW Curaao
CX Christmas Island
CY Cyprus
CZ Czechia
DE Germany
DJ Djibouti
DK Denmark
DM Dominica
DO Dominican Republic
DZ Algeria
EC Ecuador
EE Estonia
EG Egypt
EH Western Sahara
ER Eritrea
ES Spain
ET Ethiopia
FI Finland
FJ Fiji
FK Falkland Islands
FM Federated States of Micronesia
FO Faroe Islands
FR France
GA Gabon
GB United Kingdom
GD Grenada
GE Georgia
GF French Guiana
GG Guernsey
GH Ghana
GI Gibraltar
GL Greenland
GM Gambia
GN Guinea
GP Guadeloupe
GQ Equatorial Guinea
GR Greece
GS South Georgia and the South Sandwich Islands
GT Guatemala
GU Guam
GW Guinea-Bissau
GY Guyana
HK Hong Kong
HM Heard Island and McDonald Islands
HN Honduras
HR Croatia
HT Haiti
HU Hungary
ID Indonesia
IE Ireland
IL Israel
IM Isle of Man
IN India
IO British Indian Ocean Territory
IQ Iraq
IR Iran
IS Iceland
IT Italy
JE Jersey
JM Jamaica
JO Jordan
JP Japan
KE Kenya
KG Kyrgyzstan
KH Cambodia
KI Kiribati
KM Comoros
KN Saint Kitts and Nevis
KP Democratic People's Republic of Korea
KR Republic of Korea
KW Kuwait
KY Cayman Islands
KZ Kazakhstan
LA Lao People's Democratic Republic
LB Lebanon
LC Saint Lucia
LI Liechtenstein
LK Sri Lanka
LR Liberia
LS Lesotho
LT Lithuania
LU Luxembourg
LV Latvia
LY Libya
MA Morocco
MC Monaco
MD Moldova
ME Montenegro
MF Saint Martin
MG Madagascar
MH Marshall Islands
MK North Macedonia
ML Mali
MM Myanmar
MN Mongolia
MO Macao
MP Northern Mariana Islands
MQ Martinique
MR Mauritania
MS Montserrat
MT Malta
MU Mauritius
MV Maldives
MW Malawi
MX Mexico
MY Malaysia
MZ Mozambique
NA Namibia
NC New Caledonia
NE Niger
NF Norfolk Island
NG Nigeria
NI Nicaragua
NL Netherlands
NO Norway
NP Nepal
NR Nauru
NU Niue
NZ New Zealand
OM Oman
PA Panama
PE Peru
PF French Polynesia
PG Papua New Guinea
PH Philippines
PK Pakistan
PL Poland
PM Saint Pierre and Miquelon
PN Pitcairn
PR Puerto Rico
PS Palestine
PT Portugal
PW Palau
PY Paraguay
QA Qatar
RE Runion
RO Romania
RS Serbia
RU Russia
RW Rwanda
SA Saudi Arabia
SB Solomon Islands
SC Seychelles
SD Sudan
SE Sweden
SG Singapore
SH Saint Helena, Ascension and Tristan da Cunha
SI Slovenia
SJ Svalbard and Jan Mayen
SK Slovakia
SL Sierra Leone
SM San Marino
SN Senegal
SO Somalia
SR Suriname
SS South Sudan
ST Sao Tome and Principe
SV El Salvador
SX Sint Maarten
SY Syrian Arab Republic
SZ Eswatini
TC Turks and Caicos Islands
TD Chad
TF French Southern Territories
TG Togo
TH Thailand
TJ Tajikistan
TK Tokelau
TL Timor-Leste
TM Turkmenistan
TN Tunisia
TO Tonga
TR Turkey
TT Trinidad and Tobago
TV Tuvalu
TW Taiwan
TZ Tanzania
UA Ukraine
UG Uganda
UM United States Minor Outlying Islands
US United States of America
UY Uruguay
UZ Uzbekistan
VA Vatican City
VC Saint Vincent and the Grenadines
VE Venezuela
VG British Virgin Islands
VI U.S. Virgin Islands
VN Vietnam
VU Vanuatu
WF Wallis and Futuna
WS Samoa
YE Yemen
YT Mayotte
ZA South Africa
ZM Zambia
ZW Zimbabwe

first_name

Optional first name when it's representing recipient.

string

last_name

Optional last name when it's representing recipient.

string

locality

The city or town of the address. For a full list of field meanings by country, see Working with Addresses.

string

postal_code

The address's postal code. For a full list of field meanings by country, see Working with Addresses.

string

sublocality

A civil region within the address's locality, if any.

string

sublocality_2

A civil region within the address's sublocality, if any.

string

sublocality_3

A civil region within the address's sublocality_2, if any.

string

business_email

The email address of the location. This can be unique to the location and is not always the email address for the business owner or administrator.

Max Length 255

string

business_hours

The hours of operation for the location.

BusinessHours

periods[0] BusinessHoursPeriod [ ]

day_of_week

The day of the week for this time period.

string

Select day_of_week

THU Thursday

end_local_time

The end time of a business hours period, specified in local time using partial-time RFC 3339 format. For example, 21:00:00 for a period ending at 9:00 in the evening. Note that the seconds value is always :00, but it is appended for conformance to the RFC.

string

start_local_time

The start time of a business hours period, specified in local time using partial-time RFC 3339 format. For example, 8:30:00 for a period starting at 8:30 in the morning. Note that the seconds value is always :00, but it is appended for conformance to the RFC.

string

periods[1] BusinessHoursPeriod [ ]

day_of_week

The day of the week for this time period.

string

Select day_of_week

FRI Friday

end_local_time

string

start_local_time

string

periods[2] BusinessHoursPeriod [ ]

day_of_week

The day of the week for this time period.

string

Select day_of_week

SAT Saturday

end_local_time

string

start_local_time

string

business_name

The name of the location's overall business. This name is present on receipts and other customer-facing branding, and can be changed no more than three times in a twelve-month period.

Max Length 255

string

coordinates

The physical coordinates (latitude and longitude) of the location.

Coordinates

description

The description of the location. For example, Main Street location.

Max Length 1024

string

facebook_url

The Facebook profile URL of the location. The URL should begin with 'facebook.com/'. For example, https://www.facebook.com/square.

Max Length 255

string

instagram_username

The Instagram username of the location without the '@' symbol. For example, square.

Min Length 1 Max Length 30

string

language_code

The language associated with the location, in BCP 47 format. For more information, see Language Preferences.

Min Length 2 Max Length 5

string

mcc

A four-digit number that describes the kind of goods or services sold at the location. The merchant category code (MCC) of the location as standardized by ISO 18245. For example, 5045, for a location that sells computer goods and software.

Min Length 4 Max Length 4

string

name

The name of the location. This information appears in the Seller Dashboard as the nickname. A location name must be unique within a seller account.

Max Length 255

string

phone_number

The phone number of the location. For example, +1 855-700-6000.

Max Length 17

string

status

The status of the location.

string

Select status

ACTIVE A location that is active for business.
INACTIVE A location that is not active for business. Inactive locations provide historical information. Hide inactive locations unless the user has requested to see them.

timezone

The IANA time zone identifier for the time zone of the location. For example, America/Los_Angeles.

Max Length 30

string

twitter_username

The Twitter username of the location without the '@' symbol. For example, Square.

Min Length 1 Max Length 15

string

type

The type of the location.

string

Select type

MOBILE A place of business that is mobile, such as a food truck or online store.

website_url

The website URL of the location. For example, https://squareup.com.

Max Length 255

string

You are viewing an old version of the API

All Versions

Request

cURL

Ruby

Python

Java

PHP

Node.js

Response

// No response received yet.

Thanks for the feedback. For more help, check out our support resources.

Developer Support Developer Forums

There was an error submitting feedback. Try again later.

Developer Support Developer Forums