Location Resource

Use the Location resource to fetch a single location.

Resources:

Location Address Coordinates Couriers
FreeFulfillmentCondition Money Duration Fulfillment
Hours OpenInterval Pickup Delivery
SchedulePickup Timezone    

Schema type

Use location to reference this resource in the template schema.

Querying

Filters required

  • id string

    id of Location to retrieve.

      {
      "filters": {
          "id": "LXGG1JK52W3Z8"
      }
  }

Filters nullable

  • square_online_id boolean

    Flag to identify the resource to be fetched using legacy square_online_ids

      {
      "filters": {
          "id": "11edb2cfc4a95e22ba3b2c600c83e955",
          "square_online_id": true
      }
  }

Optional

  • optional boolean
    • Default: false

    A resource marked as optional will not cause the page to render a 404 view. Optional only applies to a single resource.

      {
      "filters": {
          "id": "some_id_that_does_not_exist"
      },
      "optional": true
  }

Output 

{
    "__SO_RESOURCE_TYPE__": "location", // internally used resource property. do not modify.
    "id": "LXGG1JK52W3Z8",
    "square_online_id": "11edb2cfc4a95e22ba3b2c600c83e955",
    "name": "My Business",
    "resource_type": "LOCATION",
    "description": "",
    "country": "US",
    "timezone": {
        "name": "America/Toronto",
        "offset_minutes": -300,
        "offset_string": "-05:00"
    },
    "address": {
        "name": "My Business",
        "country": "US",
        "locality": "New york",
        "postal_code": "10016",
        "address_line_1": "1583 Duncan Ave",
        "administrative_district_level_1": "NY",
        "formatted": "1583 Duncan Ave New York, NY 10016 US",
        "multiline_formatted": ["1583 Duncan Ave", "New York, NY 10016", "US"],
        "phone": "+14152323232",
        "email": ""
    },
    "coordinates": {
        "latitude": 40.728951,
        "longitude": -74.081657
    },
    "dine_in": {
        "enabled": true
    },
    "PICKUP": {
        "enabled": true,
        "curbside_pickup_enabled": true,
        "instructions": "These are my pickup instructions",
        "order_subtotal_minimum": {
            "amount": 0,
            "currency": "USD",
            "formatted": "$0.00"
        },
        "prep_time_duration": {
            "in_minutes": 30,
            "rfc3339_interval": "PT30M"
        },
        "schedule_pickup": {
            "enabled": true,
            "max_days": 90
        },
        "timeslot_type": "SPECIFIC",
        "minimum_days_required": 0,
        "auto_assign_time": true,
        "max_orders_per_window": 8,
        "cutoff_time": "10:00:00",
        "hours": {
            "SUN": [],
            "SAT": [],
            "MON": [
                {
                    "open": "09:00:00",
                    "close": "17:00:00"
                }
            ],
            "TUE": [
                {
                    "open": "09:00:00",
                    "close": "17:00:00"
                }
            ],
            "WED": [
                {
                    "open": "09:00:00",
                    "close": "17:00:00"
                }
            ],
            "THU": [
                {
                    "open": "09:00:00",
                    "close": "17:00:00"
                }
            ],
            "FRI": [
                {
                    "open": "09:00:00",
                    "close": "17:00:00"
                }
            ]
        }
    },
    "DELIVERY": {
        "enabled": true,
        "areas": [
            {
                "id": "11ee24b2e5f222ca9e9886f5c1e4bcd8",
                "type": "zipcode",
                "radius_center": {
                    "latitude": null,
                    "longitude": null
                },
                "radius_length": {
                    "unit": "mile",
                    "length": null
                },
                "zipcode": "10002"
            }
        ],
        "couriers": [
            {
                "id": "11ee24b2e5f2895498d786f5c1e4bcd8",
                "name": "seller",
                "is_choose_for_me_selection": false
            }
        ],
        "estimated_max_duration": {
            "in_minutes": 10,
            "rfc3339_interval": "PT10M"
        },
        "estimated_min_duration": {
            "in_minutes": 5,
            "rfc3339_interval": "PT5M"
        },
        "no_contact_enabled": false,
        "order_subtotal_minimum": {
            "amount": 0,
            "currency": "USD",
            "formatted": "$0.00"
        },
        "prep_time_duration": {
            "in_minutes": null,
            "rfc3339_interval": null
        },
        "schedule_delivery_enabled": true,
        "service_fee_money": {
            "amount": 125,
            "currency": "USD",
            "formatted": "$1.25"
        },
        "service_fee_percentage": null,
        "min_fee": {
            "amount": 500,
            "currency": "USD",
            "formatted": "$5.00"
        },
        "max_fee": {
            "amount": 500,
            "currency": "USD",
            "formatted": "$5.00"
        },
        "hours": {
            "SUN": [],
            "MON": [
                {
                    "open": "09:00:00",
                    "close": "17:00:00",
                    "open_formatted": "9:00 AM",
                    "close_formatted": "5:00 PM"
                }
            ],
            "TUE": [
                {
                    "open": "09:00:00",
                    "close": "17:00:00",
                    "open_formatted": "9:00 AM",
                    "close_formatted": "5:00 PM"
                }
            ],
            "WED": [
                {
                    "open": "09:00:00",
                    "close": "17:00:00",
                    "open_formatted": "9:00 AM",
                    "close_formatted": "5:00 PM"
                }
            ],
            "THU": [
                {
                    "open": "09:00:00",
                    "close": "17:00:00",
                    "open_formatted": "9:00 AM",
                    "close_formatted": "5:00 PM"
                }
            ],
            "FRI": [
                {
                    "open": "09:00:00",
                    "close": "17:00:00",
                    "open_formatted": "9:00 AM",
                    "close_formatted": "5:00 PM"
                }
            ],
            "SAT": []
        }
    }
    "fulfillment": {
        "no_eta_instructions": "go to the store and say whats up for pickup.",
        "no_eta_short_instructions": "short message for manual set pickup"
    },
    "free_fulfillment_conditions": [
        {
            "fulfillment_type": "SHIPMENT",
            "min_order": {
                "amount": 10000,
                "currency": "USD",
                "formatted": "$100.00"
            },
            "coverage": "country"
        }
    ]
}

Location resources

Location

A business location.

Field Type Description
address Address Store location address
coordinates Coordinates Latitidue / Longitude coordinates
country String Store location country, in the two-letter format of ISO 3166
created_at String Date at which the location was created in RFC3339 format
description String Description of the location
fulfillment Fulfillment Fulfillment settings for the location
id String Store location ID
is_shipping_location Boolean Whether the location is shipping location
name String Location name
PICKUP Pickup Pickup settings for the location
DELIVERY Delivery Delivery settings for the location
resource_type String The resource type identifier
square_online_id String Store Location ID in Square Online
timezone Timezone Location timezone
free_fulfillment_conditions FreeFulfillmentCondition[] Free fulfillment conditions

Back to top

Address

A physical address.

Field Type Description
address_line_1 String The first line of the address
administrative_district_level_1 String A civil entity within the address’s country. In the US, this is the state
country String The address’s country, in the two-letter format of ISO 3166. For example, US or FR
email String Email associated with the address
locality String The city or town of the address
name String Store Location name
phone String Phone associated with the address
postal_code String The address’s postal code
formatted String The address formatted according to the site’s locale
multiline_formatted String[] The address formatted as multiline according to the site’s locale

Back to top

Coordinates

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

Field Type Description
latitude Number Latitude as a float
longitude Number Longitude as a float

Back to top

Couriers

Field Type Description
name String Name of courier provider. Set to seller if using seller powered delivery (i.e. “my own couriers”), otherwise using on-demand delivery
is_choose_for_me_selection Boolean If courier is choosable or automatic

Back to top

FreeFulfillmentCondition

Field Type Description
fulfillment_type String SHIPMENT or DELIVERY
min_order Money Min order amount needed for free fulfillment
coverage String worldwide, country, mainland, partial, or custom

Back to top

Duration

Duration.

Field Type Description
in_minutes Number Duration in minutes.
rfc3339_interval String Duration in RFC3339 format.

Back to top

Fulfillment

Fulfillment settings for a location.

Field Type Description
no_eta_instructions String Full instructions for No ETA orders. Handles both pickup and delivery.
no_eta_short_instructions String Short instructions for No ETA orders. Handles both pickup and delivery.

Back to top

Hours

Scheduled times when a pickup is available.

Field Type Description
FRI OpenInterval[] List of hours for Friday
MON OpenInterval[] List of hours for Monday
SAT OpenInterval[] List of hours for Saturday
SUN OpenInterval[] List of hours for Sunday
THU OpenInterval[] List of hours for Thursday
TUE OpenInterval[] List of hours for Tuesday
WED OpenInterval[] List of hours for Wednesday

Back to top

OpenInterval

Field Type Description
close_formatted String Closing time formatted
close String Closing time
open_formatted String Opening time formatted
open String Opening time

Back to top

PICKUP

Pickup details for a location.

Field Type Description
auto_assign_time Boolean Pickup order should automatically assign ETA
curbside_pickup_enabled Boolean Whether curbside pickup is enabled
cutoff_time String The maximum time in a day that batch orders can be placed, in HH:MM:SS format (for example: 16:00:00).
enabled Boolean Whether pickup is enabled
hours Hours Scheduled times when pickup is available
instructions String Pickup instructions
max_orders_per_window Number The limit of items or orders allowed in 15 minutes
minimum_days_required Number The minimum number of days needed to prepare batch order
order_subtotal_minimum Money A minimal order amount for a pickup order to be placed
prep_time_duration Duration Prep time duration
schedule_pickup SchedulePickup Details about scheduled pickup
timeslot_type String The fulfillment timeslot type

Back to top

SchedulePickup

Details about scheduled pickup.

Field Type Description
enabled Boolean Whether scheduled pickup is enabled
max_days Number Number of days (between 0-365) during which orders pickup can be scheduled in advance

Back to top

DELIVERY

Delivery details for a location.

Field Type Description
enabled Boolean Whether delivery is enabled
areas DeliveryAreas[] Delivery coverage area information
couriers Couriers Supported courier information
estimated_max_duration Duration Estimated delivery time maximum. This only applies to seller powered delivery (i.e. “my own couriers”)
estimated_min_duration Duration Estimated delivery time minimum. This only applies to seller powered delivery (i.e. “my own couriers”)
order_subtotal_minimum Money A minimal order amount for a delivery order to be placed
odd_fee_maximum_enabled Boolean If on-demand delivery fee maximum is enabled
odd_fee_maximum Money The on-demand delivery fee maximum
no_contact_enabled Boolean Whether no-contact delivery is enabled for couriers
prep_time_duration Duration Prep time duration
schedule_delivery_enabled Boolean Whether scheduled delivery is enabled
hours Hours Schedule times when delivery is enabled
service_fee_money Money Service fee charged for delivery orders at this location. null if service fee is charged by percentage
service_fee_percentage Number Service fee percentage charged for delivery orders at this location. null if service fee is charged by money
min_fee Money The minimum delivery fee. Note this does take into account any free delivery conditions. For on-demand delivery this will be set to zero
max_fee Money The maximum delivery fee. Note this does take into account any free delivery conditions. For on-demand delivery this will be set to zero

Back to top

DeliveryAreas

Field Type Description
type String Delivery coverage information. Radius or Zipcode.
radius_center RadiusCenter Center of delivery radius information
radius_length RadiusLength Delivery radius length
zipcode String Zipcode delivery is limited to if defined

Back to top

Money

Information about monetary amounts.

Field Type Description
amount Number Amount in the smallest subunit of the given currency
currency String The ISO 4217 three-letter currency code
formatted String Amount formatted with the symbol of the given currency. Formatted according to the site’s locale

Back to top

RadiusCenter

Field Type Description
latitude String Latitude of radius center
longitude String Longitude of radius center

Back to top

RadiusLength

Field Type Description
unit String Unit of measurement for length
length Number Length of radius per unit of measurement

Back to top

Timezone

Details about the location’s timezone.

Note: offset_minutes and offset_string are representative of the current day. Be aware that these can change the next day if exiting/entering daylight saving time.

Field Type Description
name String The name of the timezone
offset_minutes Number The timezone offset in minutes
offset_string String The timezone offset

Back to top