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 aDocumentation Index
Fetch the complete documentation index at: https://docs.omneo.io/llms.txt
Use this file to discover all available pages before exploring further.
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 |
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_code | Secondary external identifier (for example, a store code) when an additional third-party system needs its own reference. See 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 |
normal_hours | Recurring weekly opening hours. See Opening hours |
special_hours | Date-bound overrides such as public holidays or special events. See 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 |
created_at | Timestamp the location record was created |
updated_at | Timestamp the location record was last updated |
Address fields
Theaddress 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, withday_of_week(MONtoSUN),open_at, andclose_atfor each entry.special_hours: date-bound overrides for public holidays, sales events, or one-off closures, withname,start_at,end_at,open_at,close_at, andis_repeatingfor 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 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 createdpreferred_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 alocation_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 anamespace, handle, type (string, integer, float, boolean, json, or array), and a value.