Admin API

This endpoint requires admin-level roles (platform_admin, tenant_admin, or system_admin). Accessible via the API gateway at /v1/platform/*.

Settings API

Manage tenant settings, location configuration, business preferences, and system options.

Overview

Attribute	Value
Base Path	/api/v1/settings
Authentication	Bearer Token
Required Roles	tenant_admin, platform_admin, system_admin, super_admin

Tenant Settings

Get Tenant Settings

GET /api/v1/settings/tenant

Response

{
  "tenant_id": "tenant_abc",
  "name": "Downtown Restaurant Group",
  "branding": {
    "logo_url": "https://...",
    "primary_color": "#2563EB",
    "secondary_color": "#1E40AF",
    "favicon_url": "https://..."
  },
  "business": {
    "legal_name": "Downtown Restaurant Group LLC",
    "tax_id": "XX-XXXXXXX",
    "industry": "restaurant",
    "business_type": "full_service"
  },
  "contact": {
    "email": "contact@downtownrestaurants.com",
    "phone": "+15551234567",
    "address": {
      "street": "100 Corporate Plaza",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US"
    }
  },
  "localization": {
    "timezone": "America/New_York",
    "currency": "USD",
    "language": "en-US",
    "date_format": "MM/DD/YYYY",
    "time_format": "12h"
  },
  "features": {
    "multi_location": true,
    "online_ordering": true,
    "reservations": true,
    "loyalty_program": true,
    "gift_cards": true,
    "catering": true,
    "delivery": true
  },
  "integrations": {
    "accounting": "quickbooks_online",
    "payroll": "gusto",
    "pos_hardware": "stripe"
  },
  "subscription": {
    "plan": "enterprise",
    "billing_cycle": "annual",
    "seats": 100,
    "locations": 5
  }
}

---

Update Tenant Settings

PUT /api/v1/settings/tenant

Request Body

{
  "branding": {
    "primary_color": "#3B82F6"
  },
  "localization": {
    "timezone": "America/Los_Angeles"
  }
}

---

Location Settings

Get Location Settings

GET /api/v1/settings/locations/{location_id}

Response

{
  "location_id": "loc_123",
  "name": "Downtown Location",
  "status": "active",
  "contact": {
    "phone": "+15551234567",
    "email": "downtown@example.com",
    "address": {
      "street": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US",
      "coordinates": {
        "lat": 37.7749,
        "lng": -122.4194
      }
    }
  },
  "hours": {
    "regular": {
      "monday": {"open": "11:00", "close": "22:00"},
      "tuesday": {"open": "11:00", "close": "22:00"},
      "wednesday": {"open": "11:00", "close": "22:00"},
      "thursday": {"open": "11:00", "close": "23:00"},
      "friday": {"open": "11:00", "close": "23:00"},
      "saturday": {"open": "10:00", "close": "23:00"},
      "sunday": {"open": "10:00", "close": "21:00"}
    },
    "special": [
      {
        "date": "2026-12-25",
        "status": "closed",
        "reason": "Christmas Day"
      },
      {
        "date": "2026-12-31",
        "open": "17:00",
        "close": "02:00",
        "reason": "New Year's Eve"
      }
    ],
    "timezone": "America/New_York"
  },
  "operations": {
    "service_types": ["dine_in", "takeout", "delivery"],
    "table_count": 25,
    "seating_capacity": 100,
    "reservation_enabled": true,
    "waitlist_enabled": true,
    "online_ordering_enabled": true
  },
  "tax": {
    "default_rate": 8.875,
    "rates": [
      {"name": "State Tax", "rate": 6.0, "applies_to": "all"},
      {"name": "City Tax", "rate": 1.5, "applies_to": "all"},
      {"name": "District Tax", "rate": 1.375, "applies_to": "all"},
      {"name": "Alcohol Tax", "rate": 2.5, "applies_to": "alcohol"}
    ],
    "tax_inclusive_pricing": false
  },
  "payment": {
    "accepted_methods": ["card", "cash", "apple_pay", "google_pay"],
    "tip_suggestions": [15, 18, 20, 25],
    "tip_default": 18,
    "auto_gratuity": {
      "enabled": true,
      "party_size_threshold": 6,
      "percentage": 18
    },
    "service_charge": {
      "enabled": false
    }
  },
  "printing": {
    "receipt_printer": "dev_004",
    "kitchen_printers": [
      {"station": "hot", "printer_id": "dev_005"},
      {"station": "cold", "printer_id": "dev_006"},
      {"station": "bar", "printer_id": "dev_007"}
    ],
    "auto_print_receipt": true,
    "receipt_footer": "Thank you for dining with us!"
  },
  "notifications": {
    "order_alerts": ["manager@example.com"],
    "low_inventory_alerts": ["kitchen@example.com"],
    "daily_summary": ["owner@example.com"]
  }
}

---

Update Location Settings

PUT /api/v1/settings/locations/{location_id}

Request Body

{
  "hours": {
    "regular": {
      "monday": {"open": "10:00", "close": "22:00"}
    }
  },
  "payment": {
    "tip_suggestions": [18, 20, 22, 25]
  }
}

---

Order Settings

Get Order Settings

GET /api/v1/settings/locations/{location_id}/orders

Response

{
  "location_id": "loc_123",
  "dine_in": {
    "enabled": true,
    "auto_fire_kitchen": false,
    "course_firing": true,
    "split_checks_allowed": true,
    "max_split_ways": 10,
    "table_assignment_required": true,
    "server_assignment_required": true
  },
  "takeout": {
    "enabled": true,
    "lead_time_minutes": 20,
    "max_future_days": 7,
    "require_phone": true,
    "require_name": true,
    "sms_notifications": true
  },
  "delivery": {
    "enabled": true,
    "provider": "in_house",
    "delivery_radius_miles": 5,
    "minimum_order": 25.00,
    "delivery_fee": 4.99,
    "free_delivery_threshold": 50.00,
    "estimated_time_minutes": 45,
    "driver_tracking_enabled": true
  },
  "online_ordering": {
    "enabled": true,
    "url": "https://order.downtownrestaurant.com",
    "menu_sync": "real_time",
    "inventory_check": true,
    "modifier_limits": true,
    "special_instructions_allowed": true,
    "max_instruction_length": 200
  },
  "order_numbers": {
    "format": "daily_sequential",
    "prefix": "",
    "reset_daily": true,
    "starting_number": 1
  },
  "timing": {
    "order_hold_minutes": 5,
    "auto_close_minutes": 60,
    "reminder_after_minutes": 30
  }
}

---

Update Order Settings

PUT /api/v1/settings/locations/{location_id}/orders

---

Menu Settings

Get Menu Settings

GET /api/v1/settings/locations/{location_id}/menu

Response

{
  "location_id": "loc_123",
  "pricing": {
    "price_levels_enabled": true,
    "price_levels": [
      {"id": "regular", "name": "Regular", "modifier": 0},
      {"id": "happy_hour", "name": "Happy Hour", "modifier": -25},
      {"id": "delivery", "name": "Delivery", "modifier": 10}
    ],
    "rounding": {
      "enabled": true,
      "method": "nearest",
      "increment": 0.05
    }
  },
  "modifiers": {
    "max_modifiers_per_item": 20,
    "required_modifiers_enforcement": true,
    "price_adjustments_allowed": true
  },
  "availability": {
    "real_time_86": true,
    "auto_restore_next_day": true,
    "low_quantity_warning_threshold": 5
  },
  "display": {
    "show_calories": true,
    "show_allergens": true,
    "show_dietary_icons": true,
    "dietary_icons": ["vegetarian", "vegan", "gluten_free", "spicy"]
  },
  "dayparts": [
    {"name": "Breakfast", "start": "06:00", "end": "11:00"},
    {"name": "Lunch", "start": "11:00", "end": "15:00"},
    {"name": "Dinner", "start": "15:00", "end": "22:00"},
    {"name": "Late Night", "start": "22:00", "end": "02:00"}
  ]
}

---

Notification Settings

Get Notification Settings

GET /api/v1/settings/notifications

Response

{
  "channels": {
    "email": {
      "enabled": true,
      "from_address": "noreply@downtownrestaurant.com",
      "reply_to": "contact@downtownrestaurant.com"
    },
    "sms": {
      "enabled": true,
      "from_number": "+15551234567"
    },
    "push": {
      "enabled": true,
      "ios_enabled": true,
      "android_enabled": true
    },
    "slack": {
      "enabled": true,
      "workspace": "Downtown Restaurant",
      "default_channel": "#operations"
    }
  },
  "preferences": {
    "order_notifications": {
      "new_order": ["push", "sound"],
      "order_ready": ["push"],
      "order_delayed": ["push", "sms"]
    },
    "staff_notifications": {
      "schedule_published": ["email", "push"],
      "shift_reminder": ["push"],
      "time_clock_reminder": ["push"]
    },
    "alert_notifications": {
      "low_inventory": ["email", "slack"],
      "equipment_issue": ["push", "slack"],
      "security_alert": ["push", "sms", "email"]
    },
    "report_notifications": {
      "daily_summary": ["email"],
      "weekly_report": ["email"],
      "monthly_report": ["email"]
    }
  },
  "quiet_hours": {
    "enabled": true,
    "start": "23:00",
    "end": "07:00",
    "exceptions": ["security_alert", "equipment_issue"]
  }
}

---

Update Notification Settings

PUT /api/v1/settings/notifications

---

Feature Flags

Get Feature Flags

GET /api/v1/settings/features

Response

{
  "features": [
    {
      "key": "ai_recommendations",
      "name": "AI Menu Recommendations",
      "enabled": true,
      "rollout_percentage": 100,
      "description": "Show AI-powered menu recommendations to customers"
    },
    {
      "key": "voice_ordering",
      "name": "Voice Ordering",
      "enabled": true,
      "rollout_percentage": 50,
      "locations": ["loc_123"],
      "description": "Enable voice ordering in drive-thru"
    },
    {
      "key": "table_qr_ordering",
      "name": "QR Code Table Ordering",
      "enabled": false,
      "description": "Allow guests to order from their phone via QR code"
    },
    {
      "key": "beta_kds_v2",
      "name": "New KDS Interface (Beta)",
      "enabled": true,
      "rollout_percentage": 25,
      "description": "New kitchen display system interface"
    }
  ]
}

---

Toggle Feature Flag

PUT /api/v1/settings/features/{feature_key}

Request Body

{
  "enabled": true,
  "rollout_percentage": 100,
  "locations": null
}

---

System Preferences

Get System Preferences

GET /api/v1/settings/system

Response

{
  "security": {
    "session_timeout_minutes": 480,
    "require_mfa": true,
    "mfa_methods": ["totp", "sms"],
    "password_policy": {
      "min_length": 12,
      "require_uppercase": true,
      "require_lowercase": true,
      "require_number": true,
      "require_special": true,
      "max_age_days": 90
    },
    "ip_allowlist_enabled": false,
    "ip_allowlist": []
  },
  "data": {
    "backup_frequency": "daily",
    "backup_retention_days": 30,
    "data_export_enabled": true,
    "api_rate_limit": 1000
  },
  "integrations": {
    "webhook_retry_attempts": 3,
    "webhook_timeout_seconds": 30,
    "api_version": "v1"
  },
  "maintenance": {
    "scheduled_maintenance_window": {
      "day": "sunday",
      "start": "02:00",
      "end": "04:00",
      "timezone": "America/New_York"
    },
    "auto_update_enabled": true
  }
}

---

Update System Preferences

PUT /api/v1/settings/system

---

Webhooks

Event	Description
settings.updated	Settings were updated
settings.feature_toggled	Feature flag changed
settings.hours_changed	Business hours changed

---

Error Responses

Status	Code	Description
400	invalid_setting	Invalid setting value
403	settings_locked	Setting cannot be changed
404	location_not_found	Location not found
409	conflict	Setting conflicts with another

---

Related Documentation

• Locations API - Location management
• Tenants API - Tenant management
• Gating API - Feature gating