API Reference

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

ScenarioUse LocationUse 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.