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

# The location object

> Create and manage the business locations where Terminals operate.

<ResponseExample>
  ```json The location object theme={null}
  {
    "id": "loc_01JEXAMPLE2K8V4N9C6M1Q7R",
    "object": "terminal.location",
    "display_name": "Main Street store",
    "address": {
      "line1": "…",
      "line2": "…",
      "city": "…",
      "state": "…",
      "postal_code": "…",
      "country": "…"
    },
    "timezone": "America/New_York",
    "merchant_category_code": "…",
    "metadata": {},
    "livemode": false
  }
  ```
</ResponseExample>

A Location (`loc_…`) is the Merchant-owned business location where
[Terminals](/api-reference/terminals) operate. It holds a display name, address, timezone, and merchant
category code, and it can carry your own `external_reference` and `metadata`.
Your server creates it. A Location does not represent a hardware serial number
or device credential.

Every Terminal belongs to a Location. You pass a Location's ID when you
[request physical hardware](/api-reference/terminal-provisioning). Test and live Locations are isolated by the mode of
the secret key. Every test account already has two Ionic fixture Locations;
create more to model your own store topology. See
[The Terminal object](/concepts/terminal-object) and
[Accept in-person terminal payments](/guides/in-person-payments). Platforms follow
[In-person payments for connected accounts](/guides/connect-in-person-payments).

## Attributes

<ResponseField name="id" type="string">
  Unique identifier for the location (`loc_…`).
</ResponseField>

<ResponseField name="display_name" type="string">
  Name for the location.
</ResponseField>

<ResponseField name="address" type="object">
  Street address of a location.
</ResponseField>

<ResponseField name="timezone" type="string">
  IANA timezone name for the location, such as `America/Chicago`.
</ResponseField>

<ResponseField name="merchant_category_code" type="string">
  Four-digit Merchant Category Code for the location.
</ResponseField>

<ResponseField name="metadata" type="object">
  Up to 50 string keys; keys are at most 40 characters and values are at most 500 characters.
</ResponseField>

See every field in the response of [Retrieve a terminal Location](/api-reference/terminal-locations/retrieve-a-terminal-location).

## Endpoints

| Endpoint | Use it for |
| - | - |
| [Create a terminal Location](/api-reference/terminal-locations/create-a-terminal-location) | Add a business location in the key's mode. |
| [List terminal Locations](/api-reference/terminal-locations/list-terminal-locations) | Review Locations with cursor pagination. |
| [Retrieve a terminal Location](/api-reference/terminal-locations/retrieve-a-terminal-location) | Read one Location. |
| [Update a terminal Location](/api-reference/terminal-locations/update-a-terminal-location) | Change a Location when its business profile changes. |

## Rules

* There is no delete operation. Update the Location when its business profile changes.
* `external_reference` is optional. When present, it must be unique for the Merchant within the key mode. It is an empty string when none is assigned, and sending an empty value on update clears it.
* On update, omitted fields remain unchanged. A supplied `address` must be a complete address, not a partial patch. A supplied `metadata` replaces the whole map; send an empty object to clear it.
* `livemode` comes from the secret key and cannot be set in the request body. Test keys never return live Locations, and live keys never return test Locations.
* `timezone` is an IANA timezone name such as `America/Chicago`. `merchant_category_code` is four digits.
* Pagination: a page returns up to 100 Locations and defaults to 20.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.