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
Address fields
The address object holds the structured postal and geocoding data 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 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 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. 
