Getting Started

This guide walks you through integrating with the KitchenClick Ecommerce API to build ordering experiences.

Prerequisites

A ShopHero service account with KitchenClick scopes (for authenticated endpoints)
A location ID where you'll be accepting orders
Understanding of REST APIs and JSON

Understanding the Data Model

Before building, understand the KitchenClick hierarchy:

Location (physical store)
  └── Concepts (restaurant brands at the location)
       └── Menus (collections of items)
            └── Categories (e.g., "Appetizers")
                 └── Subcategories (e.g., "Fried Appetizers")
                      └── Items (e.g., "Mozzarella Sticks")
                           └── Option Groups (e.g., "Dipping Sauce")
                                └── Modifiers (e.g., "Marinara", "Ranch")

Step 1: Discover Locations

First, get information about a location:

bash

curl https://api.kitchenclick.retailsuccessplatform.com/api/v1/ecommerce/locations/loc_xxxxx

Response:

json

{
  "status": "success",
  "data": {
    "location_id": "loc_xxxxx",
    "name": "Downtown Store",
    "address": {
      "street": "123 Main St",
      "city": "Austin",
      "state": "TX",
      "zip": "78701"
    },
    "timezone": "America/Chicago",
    "order_types": ["dine-in", "takeout", "delivery"],
    "prep_time_minutes": 15,
    "delivery_settings": {
      "radius_miles": 5,
      "fee": 3.99,
      "minimum_order": 15.00
    }
  }
}

Get operating hours:

bash

curl https://api.kitchenclick.retailsuccessplatform.com/api/v1/ecommerce/locations/loc_xxxxx/hours

Step 2: Get Available Concepts

A location may have multiple restaurant concepts:

bash

curl https://api.kitchenclick.retailsuccessplatform.com/api/v1/ecommerce/locations/loc_xxxxx/concepts

Response:

json

{
  "status": "success",
  "data": [
    {
      "concept_id": "con_yyyyy",
      "name": "Bistro Kitchen",
      "description": "Fresh American cuisine",
      "logo_url": "https://cdn.example.com/logos/bistro.png",
      "hero_url": "https://cdn.example.com/heroes/bistro.jpg",
      "status": "active"
    },
    {
      "concept_id": "con_zzzzz",
      "name": "Taco Corner",
      "description": "Authentic Mexican flavors",
      "logo_url": "https://cdn.example.com/logos/taco.png",
      "status": "active"
    }
  ]
}

Step 3: Browse Menus

Get menus for a concept:

bash

curl https://api.kitchenclick.retailsuccessplatform.com/api/v1/ecommerce/locations/loc_xxxxx/concepts/con_yyyyy/menus

Response:

json

{
  "status": "success",
  "data": [
    {
      "menu_id": "mnu_aaaaa",
      "name": "All Day Menu",
      "menu_type": "regular",
      "hero_url": "https://cdn.example.com/menus/allday.jpg",
      "status": "live"
    },
    {
      "menu_id": "mnu_bbbbb",
      "name": "Breakfast Menu",
      "menu_type": "breakfast",
      "availability_rules": {
        "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
        "time_ranges": [{"start": "06:00", "end": "11:00"}]
      },
      "status": "live"
    }
  ]
}

Fetch the full menu hierarchy:

bash

curl https://api.kitchenclick.retailsuccessplatform.com/api/v1/ecommerce/locations/loc_xxxxx/concepts/con_yyyyy/menus/mnu_aaaaa/items

Response (hierarchical):

json

{
  "status": "success",
  "data": {
    "menu": {
      "menu_id": "mnu_aaaaa",
      "name": "All Day Menu"
    },
    "hierarchy": [
      {
        "item_id": "itm_cat1",
        "name": "Appetizers",
        "type": "category",
        "display_order": 1,
        "children": [
          {
            "item_id": "itm_item1",
            "name": "Mozzarella Sticks",
            "type": "item",
            "description": "Golden fried mozzarella served with marinara",
            "base_price": 8.99,
            "hero_url": "https://cdn.example.com/items/mozz.jpg",
            "nutritional_info": {
              "calories": 450,
              "protein": 18,
              "carbs": 35,
              "fat": 28
            },
            "allergens": ["dairy", "gluten"],
            "dietary_tags": ["vegetarian"],
            "prep_time_minutes": 8,
            "is_featured": true,
            "is_86d": false
          }
        ]
      }
    ]
  }
}

Step 5: Get Item Details with Modifiers

For items with customization options:

bash

curl https://api.kitchenclick.retailsuccessplatform.com/api/v1/ecommerce/locations/loc_xxxxx/concepts/con_yyyyy/items/itm_item1

Response:

json

{
  "status": "success",
  "data": {
    "item_id": "itm_item1",
    "name": "Mozzarella Sticks",
    "base_price": 8.99,
    "option_groups": [
      {
        "option_group_id": "opg_sauce",
        "name": "Choose Dipping Sauce",
        "is_required": true,
        "min_selections": 1,
        "max_selections": 2,
        "modifiers": [
          {
            "modifier_id": "mod_marinara",
            "name": "Marinara",
            "price_adjustment": 0,
            "is_default": true
          },
          {
            "modifier_id": "mod_ranch",
            "name": "Ranch",
            "price_adjustment": 0
          },
          {
            "modifier_id": "mod_buffalo",
            "name": "Buffalo",
            "price_adjustment": 0.50
          }
        ]
      },
      {
        "option_group_id": "opg_extra",
        "name": "Extras",
        "is_required": false,
        "min_selections": 0,
        "max_selections": 3,
        "modifiers": [
          {
            "modifier_id": "mod_cheese",
            "name": "Extra Cheese",
            "price_adjustment": 1.50
          }
        ]
      }
    ]
  }
}

Step 6: Calculate Order Total

Before creating an order, calculate the total with tax:

bash

curl -X POST https://api.kitchenclick.retailsuccessplatform.com/api/v1/ecommerce/orders/calculate \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "location_id": "loc_xxxxx",
    "order_type": "pickup",
    "items": [
      {
        "item_id": "itm_item1",
        "quantity": 2,
        "modifiers": [
          {"modifier_id": "mod_marinara", "quantity": 1},
          {"modifier_id": "mod_cheese", "quantity": 1}
        ]
      }
    ],
    "save_quote": true
  }'

Response (save_quote: true returns a reusable quote_token_id):

json

{
  "status": "success",
  "data": {
    "items": [
      {
        "item_id": "itm_item1",
        "name": "Mozzarella Sticks",
        "quantity": 2,
        "unit_price": 10.49,
        "subtotal": 20.98,
        "tax": 1.31
      }
    ],
    "totals": {
      "subtotal": 20.98,
      "tax_amount": 1.73,
      "deposits_amount": 0,
      "fees_amount": 0,
      "delivery_fee": 0,
      "tip_amount": 0,
      "total": 22.71
    },
    "breakdown": {
      "tax": [
        {"name": "State Tax", "rate": 0.0625, "taxable_amount": 20.98, "amount": 1.31}
      ],
      "deposits": [],
      "fees": []
    },
    "quote": {
      "quote_token_id": "kqt_xxxxx",
      "expires_at": "2026-06-17T14:30:00Z",
      "validity_minutes": 15
    }
  }
}

Step 7: Create the Order

Submit the order:

bash

curl -X POST https://api.kitchenclick.retailsuccessplatform.com/api/v1/ecommerce/orders \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "location_id": "loc_xxxxx",
    "customer": {
      "name": "John Doe",
      "phone": "(555) 123-4567",
      "email": "john@example.com"
    },
    "order_type": "pickup",
    "items": [
      {
        "item_id": "itm_item1",
        "quantity": 2,
        "modifiers": [
          {"modifier_id": "mod_marinara", "quantity": 1},
          {"modifier_id": "mod_cheese", "quantity": 1}
        ]
      }
    ],
    "payment_method": "cash",
    "tip_amount": 3.00
  }'

For card payments, pay with Stripe first and use POST /orders/stripe instead — see Payments. This example uses payment_method: "cash" (pay in store).

Response:

json

{
  "status": "success",
  "message": "Order placed successfully",
  "data": {
    "order_id": "ord_xxxxx",
    "order_number": "1234",
    "status": "confirmed",
    "order_type": "takeout",
    "channel": "ecommerce",
    "estimated_ready_time": "2026-06-17T14:30:00Z",
    "totals": {
      "subtotal": 20.98,
      "tax": 1.73,
      "delivery_fee": 0,
      "tip": 3.00,
      "total": 25.71
    },
    "tracking_url": "https://api.kitchenclick.retailsuccessplatform.com/api/v1/ecommerce/orders/ord_xxxxx/track"
  }
}

Step 8: Track Order Status

Poll the tracking endpoint (public, no auth):

bash

curl https://api.kitchenclick.retailsuccessplatform.com/api/v1/ecommerce/orders/ord_xxxxx/track

Response:

json

{
  "status": "success",
  "data": {
    "order_number": "1234",
    "status": "preparing",
    "estimated_ready_time": "2024-01-15T14:30:00Z",
    "status_history": [
      {"status": "confirmed", "timestamp": "2024-01-15T14:15:00Z"},
      {"status": "preparing", "timestamp": "2024-01-15T14:18:00Z"}
    ]
  }
}

Next Steps

Authentication - Set up OAuth tokens
Menus Reference - Complete menu API docs
Orders Reference - Order management details

Changelog

Date	Change
2026-01-15	Initial publication.

Getting Started ​

Prerequisites ​

Understanding the Data Model ​

Step 1: Discover Locations ​

Step 2: Get Available Concepts ​

Step 3: Browse Menus ​

Step 4: Get Menu Items ​

Step 5: Get Item Details with Modifiers ​

Step 6: Calculate Order Total ​

Step 7: Create the Order ​

Step 8: Track Order Status ​

Next Steps ​

Getting Started

Prerequisites

Understanding the Data Model

Step 1: Discover Locations

Step 2: Get Available Concepts

Step 3: Browse Menus

Step 4: Get Menu Items

Step 5: Get Item Details with Modifiers

Step 6: Calculate Order Total

Step 7: Create the Order

Step 8: Track Order Status

Next Steps