Importing store and chain data

Chains, stores, opening hours and adjustments - import modes, validation rules and the typical flow.

The Store service holds the chains, stores and opening hours that the rest of Lobyco uses for targeting, validation and configuration. You keep it in sync from your master system through Service2Service import endpoints.

The order to do it in

Dependencies run downhill, so import in this order:

1. Upload assets

   Optional. Upload brand assets such as logos first; the returned asset IDs are referenced by chain records.

2. Import chains

   A store cannot be imported before its chain exists.

3. Import stores

4. Import opening hours adjustments

5. Read back

   Use the retrieval endpoints — search and get-by-id — from your internal services.

All imports are upserts: an existing record is updated, a missing one is created, and bulk payloads are supported.

Chains

Chains represent the retailer’s brands. A retailer may have several, each with its own identity.

Field	Meaning
id	Unique chain identifier
name	Chain name
primaryColor / secondaryColor	Brand colours
logoAssetId	Reference to an uploaded asset
alternateIds	Mapping to identifiers in your systems

Chains can be read individually or in full, which is what internal services use for validation and lookups.

Stores

Field	Meaning
id	Unique store ID
chainId	Must already exist
name	Store name
country, city, street, streetNumber, postalCode	Address
location	Latitude and longitude
timeZone	IANA timezone identifier
phone, email	Contact details
status	Open, Closed or ComingSoon
alternateIds	Mapping for POS, ERP, SAP and similar

Stores can be fetched by ID, searched free-text, or paged through when the estate is large. They can be imported directly or through the Data Import Service. Once imported, the data is immediately available to every other service that consumes Store Service.

Updates use the same endpoints as creation — address corrections, contact details, revised coordinates, status changes and new alternate IDs all arrive as upserts.

Removing a store

There are two ways, and they behave differently:

• Set its status to Closed — the store stays in the system but is hidden from operational features.
• Omit it from a full import — see the import modes below.

Opening hours

Regular opening hours are the store’s default weekly schedule — Monday 08:00–22:00, Sunday closed, and so on.

Adjustments override that schedule for a date range, and exist for public holidays, special events, seasonal changes, renovations and unexpected closures. An early close on Christmas Eve, a week-long shutdown, or extended hours during a promotion are all adjustments.

Field	Meaning
storeId	The store affected
startDate / endDate	The period the adjustment covers
openTime / closeTime	Replacement hours
closed	Set when the store does not open at all
reason	Why the hours changed

Import modes

	Incremental (default)	Full
New records	Inserted	Inserted
Existing records	Updated	Updated
Records absent from the payload	Left alone	Removed or deactivated
Use for	Daily syncs, partial updates	Full dataset replacement, cleanup
Risk	Low	A truncated export can wipe your estate

Incremental is the safer default. Reach for full only when the source really is the authoritative master for the whole estate.

Validation rules

Imports are rejected when:

• chainId does not already exist
• latitude falls outside −90 to 90, or longitude outside −180 to 180
• timeZone is not a valid IANA identifier
• adjustment date ranges are invalid, or overlap each other

API reference

Endpoint documentation: Stores.