> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usenash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Store locations

> A store location is a physical origin — a restaurant, warehouse, or store — that deliveries depart from. Learn how to model store locations, upsert them by your own identifier, and look up which stores cover a location.

A **store location** is a physical origin — a restaurant, warehouse, or store — that deliveries depart from. Store locations let you register your pickup points once and then reference them from orders, associate them with [zones](/reference/zones), and answer coverage questions like *"which of my stores serves this address?"*

## Modeling store locations

A store location describes a single origin and the information a driver and the dispatch system need to pick up from it. Create one with [Create store location](/api-reference/store-locations/create-store-location) (`POST /v1/store_locations`). A store location can carry:

* A **name** (the store's business name) and a **phone number** — the two required fields
* A **first name** and **last name** for the contact at the location
* An **email** and **pickup instructions** for the courier
* An **address** (as a single line) or pre-geocoded **address components**
* An **external ID** that maps the location to your own systems
* Free-form **tags** for your own classification
* **Operating hours** and a **prep time** in minutes (both integration-specific)
* **Zone associations** that link the location to one or more [zones](/reference/zones)

Retrieve a single store location with [Get store location](/api-reference/store-locations/get-store-location) (`GET /v1/store_locations/{id}`), or list them with [Get store locations](/api-reference/store-locations/get-store-locations) (`GET /v1/store_locations`). Update an existing location with `PATCH /v1/store_locations/{id}` and remove one with `DELETE /v1/store_locations/{id}`.

<Info>
  `name` and `phoneNumber` are the only required fields. If you don't know the contact's name, pass `Manager` for `firstName` and `lastName`.
</Info>

## External identifiers

Most teams already have their own identifier for each store. Rather than store and reconcile Nash's IDs, you can address store locations by your **external identifier** and let Nash perform an idempotent upsert.

Use [Create or update store location by external identifier](/api-reference/store-locations/create-or-update-store-location-by-external-identifier) (`POST /v1/store_locations/external-identifier/{externalIdentifier}`). If a store location with that external identifier already exists, it is updated in place; if not, a new one is created. This makes it safe to replay the same request — for example when syncing your store catalog on a schedule — without creating duplicates.

To read a location back by your own identifier, use [Get store location by external identifier](/api-reference/store-locations/get-store-location-by-external-identifier) (`GET /v1/store_locations/external_identifier/{externalIdentifier}`).

<Note>
  There is also a plain upsert endpoint, [Create or update store location](/api-reference/store-locations/create-or-update-store-location) (`POST /v1/store_locations/upsert`), and a bulk variant, [Upsert multiple store locations](/api-reference/store-locations/upsert-multiple-store-locations) (`POST /v1/store_locations/upsert/bulk`), for syncing many locations at once.
</Note>

## Coverage lookups

A coverage lookup answers *"which store locations cover this point?"* by testing a location against the delivery zones associated with your store locations. Use [Get store locations that cover a specified latitude and longitude](/api-reference/store-locations/get-store-locations-that-cover-specified-latitude-and-longitude) (`GET /v1/store_locations/coverage`). You can query by:

<Tabs>
  <Tab title="Latitude & longitude">
    Provide both `latitude` and `longitude` to find the store locations whose zones cover that exact point.

    ```
    GET /v1/store_locations/coverage?latitude=37.76&longitude=-122.43
    ```
  </Tab>

  <Tab title="City & zip code">
    Provide a `cityZipcode` pair, or a `zipcode` alone. The location must have coverage set up using the matching field.

    ```
    GET /v1/store_locations/coverage?cityZipcode=sanfrancisco_94114
    ```
  </Tab>
</Tabs>

<Info>
  `latitude` and `longitude` must be supplied together — if you pass one, you must pass the other.
</Info>

## Store locations vs. zones

Store locations and [zones](/reference/zones) are distinct but related:

* A **store location** is a physical origin that deliveries depart from.
* A **zone** is a geographic area — a polygon boundary or a list of cities, zip codes, states, or countries — where delivery is available.

You connect them through **zone associations**: associate a store location with one or more zones, and a coverage lookup can tell you whether a given dropoff point falls inside a store's delivery area. The store location coverage endpoint returns the *stores* serving a point; the [zones coverage endpoint](/api-reference/zones/get-zones-that-cover-specified-location-latitude-and-longitude-city_zipcode) returns the *zones* containing it.

## Next steps

<CardGroup cols={2}>
  <Card title="Create store location" icon="store" href="/api-reference/store-locations/create-store-location">
    Register a pickup origin and its contact details.
  </Card>

  <Card title="Upsert by external identifier" icon="arrows-rotate" href="/api-reference/store-locations/create-or-update-store-location-by-external-identifier">
    Create or update a store location idempotently by your own ID.
  </Card>

  <Card title="Coverage lookup" icon="location-crosshairs" href="/api-reference/store-locations/get-store-locations-that-cover-specified-latitude-and-longitude">
    Find the stores that cover a latitude/longitude or city/zip.
  </Card>

  <Card title="Zones" icon="draw-polygon" href="/reference/zones">
    Define the delivery areas your stores serve.
  </Card>
</CardGroup>