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

# 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:

<Steps>
  <Step>
    ### Upload assets

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

  <Step>
    ### Import chains

    A store cannot be imported before its chain exists.
  </Step>

  <Step>
    ### Import stores
  </Step>

  <Step>
    ### Import opening hours adjustments
  </Step>

  <Step>
    ### Read back

    Use the retrieval endpoints — search and get-by-id — from your internal services.
  </Step>
</Steps>

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

<Warning>
  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
</Warning>

## API reference

Endpoint documentation: [Stores](/api-reference/retail-master-data/stores).