📍 Locations & Stores API

Kitchenhub operates with two primary entities in its system architecture:

Location — a physical venue (e.g., a restaurant address or kitchen facility).
Store — a virtual representation of a brand or service concept running within a specific location. Stores are commonly used for managing multiple virtual brands or services in a shared kitchen environment.

This guide provides a comprehensive explanation of how to create and manage these entities through either the Admin Dashboard or the Kitchenhub API. It also highlights key configuration fields (especially timezone), the importance of the partner_id for external mapping, and detailed usage scenarios.

🛠 Creation Methods: Dashboard vs API

Entities can be created in two ways depending on your operational scale and team structure:

1. Admin Dashboard

Best For: Initial setup, small-scale businesses, manual operations.
Benefits:
- User-friendly UI.
- Ideal for one-off or infrequent changes.
- Good for testing and debugging configurations.

2. Programmatic API

Best For: Scaling operations, automation, system integration.
Benefits:
- Enables bulk creation and updates.
- Integrates directly with your internal tooling and workflows.
- Reduces human error.

🔗 `partner_id` for External System Mapping

The partner_id field is supported on both locations and stores, allowing you to maintain a reference between your system and Kitchenhub.

Used in API requests and responses.
Included in order payloads as:
- partner_location_id
- partner_store_id

Use case: When syncing data from Kitchenhub into your internal tools, partner_id allows for a reliable match without relying on internal Kitchenhub IDs.

⚙️ Configuration Settings to Pay Attention To

Each location and store has configurable attributes. The most critical include:

name: Display name.
address (location only): Physical address.
timezone:
- Highly critical.
  - A mismatch in timezone can lead to serious issues with order timing.
  - Scheduled orders may fire at incorrect local times if misconfigured.
partner_id: Used for system integration as noted above.

⚠️
Always verify the timezone before activating a new location or store. It must match the local time where kitchen operations occur.

💡 When to Use Locations vs Stores

Understanding when to create new locations vs additional stores is key to maintaining a clean and logical structure:

Scenario	Use Location	Use Store
Standalone restaurant	✅ One location	✅ One store
Multi-location chain	✅ One per venue	✅ One per brand in each venue
Dark/ghost kitchens with multiple brands	✅ One shared kitchen location	✅ One store per brand
Franchise with shared address but different owners	✅ One per franchise operator	✅ One per brand they operate

🔹
Important:
If your system does not support nested stores (i.e., multiple brands per physical location), always default to creating one location with one store inside it. This is the simplest and most compatible setup with Kitchenhub’s structure.
This setup ensures correct mapping of orders, proper timezone handling, and avoids unnecessary complexity.

Typical schemes of locations and stores

Single restaurant

Restaurant chain

Virtual brands chain

🧪 API Endpoints & Examples

Each API section below includes:

A short description.
Request & response samples.
Common error responses.
Recommended HTTP headers.

Consider displaying this content in a collapsible UI layout to make scanning easier.

📍 Locations

`GET /locations`

Retrieves a list of all configured locations.

GET /locations HTTP/1.1
Host: api.kitchenhub.com
Authorization: Bearer {token}

Response (200 OK):

[
  {
    "id": "loc_001",
    "name": "Downtown Restaurant",
    "address": "123 Main St, City, Country",
    "timezone": "Europe/Nicosia",
    "partner_id": "partner_loc_001"
  }
]

Error (401 Unauthorized):

{
  "error": "Unauthorized",
  "message": "Invalid or missing API token."
}

`POST /locations`

Creates a new physical location.

POST /locations HTTP/1.1
Host: api.kitchenhub.com
Content-Type: application/json
Authorization: Bearer {token}

Request:

{
  "name": "Downtown Restaurant",
  "address": "123 Main St, City, Country",
  "timezone": "Europe/Nicosia",
  "partner_id": "partner_loc_001"
}

Response (201 Created):

{
  "id": "loc_001",
  "name": "Downtown Restaurant",
  "address": "123 Main St, City, Country",
  "timezone": "Europe/Nicosia",
  "partner_id": "partner_loc_001"
}

Error (400 Bad Request):

{
  "error": "Bad Request",
  "message": "The 'name' and 'address' fields are required."
}

`PATCH /locations/{id}`

Updates fields of an existing location.

PATCH /locations/loc_001 HTTP/1.1
Host: api.kitchenhub.com
Content-Type: application/json
Authorization: Bearer {token}

Request:

{
  "timezone": "Europe/Athens"
}

Response (200 OK):

{
  "id": "loc_001",
  "name": "Downtown Restaurant",
  "address": "123 Main St, City, Country",
  "timezone": "Europe/Athens",
  "partner_id": "partner_loc_001"
}

🏬 Stores

`GET /stores`

Retrieves a list of all stores across all locations.

GET /stores HTTP/1.1
Host: api.kitchenhub.com
Authorization: Bearer {token}

Response (200 OK):

[
  {
    "id": "store_001",
    "location_id": "loc_001",
    "name": "Main Brand",
    "partner_id": "partner_store_001",
    "settings": {
      "timezone": "Europe/Nicosia"
    }
  }
]

`POST /stores`

Creates a new store under a specific location.

POST /stores HTTP/1.1
Host: api.kitchenhub.com
Content-Type: application/json
Authorization: Bearer {token}

Request:

{
  "location_id": "loc_001",
  "name": "Main Brand",
  "partner_id": "partner_store_001",
  "settings": {
    "timezone": "Europe/Nicosia"
  }
}

Response (201 Created):

{
  "id": "store_001",
  "location_id": "loc_001",
  "name": "Main Brand",
  "partner_id": "partner_store_001",
  "settings": {
    "timezone": "Europe/Nicosia"
  }
}

Error (400 Bad Request):

{
  "error": "Bad Request",
  "message": "The 'location_id' and 'name' fields are required."
}

`PATCH /stores/{id}`

Updates a store’s configuration.

PATCH /stores/store_001 HTTP/1.1
Host: api.kitchenhub.com
Content-Type: application/json
Authorization: Bearer {token}

Request:

{
  "settings": {
    "timezone": "Europe/Athens"
  }
}

Response (200 OK):

{
  "id": "store_001",
  "location_id": "loc_001",
  "name": "Main Brand",
  "partner_id": "partner_store_001",
  "settings": {
    "timezone": "Europe/Athens"
  }
}

✅ Final Notes on Design & Usability

Collapsible layout: Improves scanning, especially for mobile or dense documentation.
Terminology consistency: Terms like location, store, partner_id, and timezone are used consistently throughout for clarity.
Error handling: Always handle 4xx and 5xx errors gracefully in your integration logic.

📍 Locations & Stores API

🛠 Creation Methods: Dashboard vs API

1. Admin Dashboard

2. Programmatic API

🔗 `partner_id` for External System Mapping

⚙️ Configuration Settings to Pay Attention To

⚠️
Always verify the `timezone` before activating a new location or store. It must match the local time where kitchen operations occur.

💡 When to Use Locations vs Stores

🔹
Important:

Typical schemes of locations and stores

🧪 API Endpoints & Examples

📍 Locations

`GET /locations`

`POST /locations`

`PATCH /locations/{id}`

🏬 Stores

`GET /stores`

`POST /stores`

`PATCH /stores/{id}`

✅ Final Notes on Design & Usability

🛠 Creation Methods: Dashboard vs API

1. Admin Dashboard

2. Programmatic API

🔗 partner_id for External System Mapping

⚙️ Configuration Settings to Pay Attention To

⚠️Always verify the timezone before activating a new location or store. It must match the local time where kitchen operations occur.

💡 When to Use Locations vs Stores

🔹Important:

Typical schemes of locations and stores

🧪 API Endpoints & Examples

📍 Locations

GET /locations

POST /locations

PATCH /locations/{id}

🏬 Stores

GET /stores

POST /stores

PATCH /stores/{id}

✅ Final Notes on Design & Usability

🔗 `partner_id` for External System Mapping

⚠️
Always verify the `timezone` before activating a new location or store. It must match the local time where kitchen operations occur.

🔹
Important:

`GET /locations`

`POST /locations`

`PATCH /locations/{id}`

`GET /stores`

`POST /stores`

`PATCH /stores/{id}`