> ## Documentation Index > Fetch the complete documentation index at: https://docs.omneo.io/llms.txt > Use this file to discover all available pages before exploring further. # Locations > Store and location records used to contextualise transactions, profiles, and personalisation. Locations in Omneo represent a brand's physical or virtual stores, including storefronts, kiosks, warehouses, and eCommerce. They are referenced throughout the platform to provide context to transactions, profiles, and customer experiences, and they power store-level analytics, staff attribution, store locators, click and collect, and location-aware incentives. At a minimum, a location should have a `name`, a `phone`, and an `external_id` so it can be matched back to your POS, OMS, or eCommerce platform. The richer the location record (address, hours, geocoordinates, tags, departments), the more it can be used in customer-facing experiences and reaction logic. ## Location fields | Field | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Omneo's internal numeric identifier for the location | | `type` | Free-form classification of the location (e.g., `store`, `kiosk`, `warehouse`, `online`). Used to distinguish physical, virtual, and operational location types. Values are normalized to lowercase on write. | | `name` | Store display name | | `handle` | URL-friendly identifier used to reference the location in experiences and integrations | | `description` | Long-form description of the location, used in store locators and customer-facing experiences | | `phone` | Store phone number | | `email` | Store email address | | `timezone` | IANA timezone (e.g., `Australia/Melbourne`) used to interpret opening hours and schedule-based reactions | | `external_id` | The location's ID in your POS or eCommerce system. Used to match transactions and imports back to the correct location. See [External identifiers](#external-identifiers) | | `external_code` | Secondary external identifier (for example, a store code) when an additional third-party system needs its own reference. See [External identifiers](#external-identifiers) | | `is_published` | Whether the location is publicly visible in customer-facing surfaces such as store locators | | `is_permanently_closed` | Marks the location as permanently closed. Retained for historical transaction attribution but hidden from active selection | | `icon` | URL of an icon representing the location (e.g., a pin or marker image) | | `image_url` | URL of a representative store image used in store locators and experiences | | `country_iso_3` | ISO 3166-1 alpha-3 country code (e.g., `AUS`, `USA`) for the location | | `address` | Structured address object. See [Address fields](#address-fields) | | `normal_hours` | Recurring weekly opening hours. See [Opening hours](#opening-hours) | | `special_hours` | Date-bound overrides such as public holidays or special events. See [Opening hours](#opening-hours) | | `tags` | Tags applied to the location for grouping, filtering, and segmentation | | `departments` | Departments associated with the location, used for staff attribution and reporting | | `custom_fields` | Brand-defined key-value pairs. See [Custom fields](#custom-fields) | | `created_at` | Timestamp the location record was created | | `updated_at` | Timestamp the location record was last updated | ### Address fields The `address` object holds the structured postal and geocoding data for the location. | Field | Description | | ---------------- | --------------------------------------------------------- | | `address_line_1` | Street address line 1 | | `address_line_2` | Street address line 2 | | `address_line_3` | Street address line 3 | | `company` | Company or building name | | `city` | City or suburb | | `state` | State or region | | `postcode` | Postcode | | `country` | Country name | | `iso` | ISO 3166-1 alpha-2 country code | | `iso_state` | ISO 3166-2 state/region subdivision code | | `latitude` | Latitude (for geocoding and proximity features) | | `longitude` | Longitude (for geocoding and proximity features) | | `notes` | Free-form notes such as access instructions or directions | | `is_default` | Whether this is the default address for the location | ### Opening hours Locations expose two sets of hours: * `normal_hours`: recurring weekly hours, with `day_of_week` (`MON` to `SUN`), `open_at`, and `close_at` for each entry. * `special_hours`: date-bound overrides for public holidays, sales events, or one-off closures, with `name`, `start_at`, `end_at`, `open_at`, `close_at`, and `is_repeating` for annual events. ## External identifiers `external_id` and `external_code` let other systems reference an Omneo location without needing visibility of the native Omneo `id`. They are independent slots so that different upstream systems can each use the identifier that makes sense for them. For example, a transaction system might send transactions in against the location's `external_id`, while a workforce or rostering system allocates staff to locations by `external_code`. If you need additional location identifiers beyond these two, use [Custom fields](#custom-fields) rather than overloading `external_id` or `external_code`. `external_id` and `external_code` can be set when a location is created in CX Manager, but they cannot be changed afterwards. Treat them like handles on other Omneo objects: choose them deliberately at creation time, since downstream systems will rely on them as stable references. ## How locations are used ### Profile context * `join_location_id`, the store where a profile was created * `preferred_location_id`, the customer's favourite store (user-defined) * `most_transacted_location`, the store where the customer most frequently shops (aggregation) ### Transaction context Every transaction includes a `location_id` linking it to the store where the purchase occurred. This drives store-level analytics and staff attribution. ### Incentive context Reactions and benefit definitions can filter or apply logic based on the transaction's location. For example, a reaction can issue a benefit only when a transaction occurs at a specific location. ### Click and collect Locations are referenced as pickup points in order records for click and collect fulfilment. ## Custom fields Locations support custom fields, brand-defined key-value pairs for any additional location-specific data (e.g., manager name, floor number, mall name, parking information). Each custom field has a `namespace`, `handle`, `type` (`string`, `integer`, `float`, `boolean`, `json`, or `array`), and a `value`. ## Sync and management Locations are managed in CX Manager under Configuration. They can also be created and updated via the API or bulk imported from your POS system.