{
  "openapi": "3.1.0",
  "info": {
    "title": "BookNDish API",
    "version": "1.0.0",
    "summary": "Work with one restaurant: its menu, orders, bookings, guests and sales.",
    "description": "Every request acts for the restaurant that owns the bearer token and goes through the same rules as the admin: prices come from the menu, the owner's ordering and booking rules apply, status changes follow the order's lifecycle, and writes are audited. Money is an integer in the currency's minor unit (`price_minor: 1250` is 12.50 EUR, 12.500 TND). Names and descriptions are translation maps (`{\"en\": \"Soup\", \"fr\": \"Soupe\"}`). Times are ISO 8601 with offset. v1 only grows: new endpoints, new optional fields, new webhook events.",
    "contact": { "name": "BookNDish developers", "url": "/developers" }
  },
  "servers": [
    { "url": "/api/v1", "description": "This BookNDish host. A sandbox token (bnd_sbx_) works on the same address and acts for its sample venue." }
  ],
  "security": [{ "bearerAuth": [] }, { "oauth2": [] }],
  "tags": [
    { "name": "Menu", "description": "Menus, categories and dishes." },
    { "name": "Orders", "description": "Orders on any channel, and their status." },
    { "name": "Reservations", "description": "Bookings and table availability. Needs a plan with reservations." },
    { "name": "Guests", "description": "Guest profiles, with contact details only for guests who agreed to share them." },
    { "name": "Reports", "description": "Sales figures. Needs a plan with reporting." },
    { "name": "OAuth", "description": "Apps from the marketplace: a venue owner allows an app on the consent screen, and the app exchanges the code for an access token (used as the bearer token of every operation above) and a refresh token. Authorization code with PKCE (S256)." }
  ],
  "paths": {
    "/menus": {
      "get": {
        "tags": ["Menu"],
        "operationId": "listMenus",
        "summary": "Every menu with its categories",
        "x-scope": "menu:read",
        "responses": {
          "200": {
            "description": "The menus, in the owner's order.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta", "links"],
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/MenuWithCategories" } },
                    "meta": { "type": "object", "required": ["count", "currency"], "properties": { "count": { "type": "integer" }, "currency": { "$ref": "#/components/schemas/Currency" } } },
                    "links": { "$ref": "#/components/schemas/NoLinks" }
                  }
                },
                "example": {
                  "data": [{ "id": 3, "name": { "en": "Dinner" }, "is_active": true, "sort_order": 0, "categories": [{ "id": 7, "menu_id": 3, "name": { "en": "Mains" }, "is_active": true, "sort_order": 0 }] }],
                  "meta": { "count": 1, "currency": "EUR" },
                  "links": {}
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/menus/{menu}": {
      "get": {
        "tags": ["Menu"],
        "operationId": "getMenu",
        "summary": "One menu, its categories and their dishes",
        "description": "`meta.now` says what menus by time of day and happy hours make of the menu right now, on the default branch's clock: whether it and each category are open, and each dish or size a happy hour has cut, at the price charged now.",
        "x-scope": "menu:read",
        "parameters": [{ "$ref": "#/components/parameters/MenuId" }],
        "responses": {
          "200": {
            "description": "The menu.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta", "links"],
                  "properties": {
                    "data": { "$ref": "#/components/schemas/MenuWithItems" },
                    "meta": {
                      "type": "object",
                      "required": ["currency", "now"],
                      "properties": {
                        "currency": { "$ref": "#/components/schemas/Currency" },
                        "now": {
                          "type": "object",
                          "required": ["available", "closed_category_ids", "prices"],
                          "properties": {
                            "available": { "type": "boolean" },
                            "closed_category_ids": { "type": "array", "items": { "type": "integer" } },
                            "prices": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "required": ["item_id", "variant_id", "price_minor"],
                                "properties": { "item_id": { "type": "integer" }, "variant_id": { "type": ["integer", "null"] }, "price_minor": { "type": "integer" } }
                              }
                            }
                          }
                        }
                      }
                    },
                    "links": { "$ref": "#/components/schemas/NoLinks" }
                  }
                },
                "example": {
                  "data": {
                    "id": 3, "name": { "en": "Dinner" }, "is_active": true, "sort_order": 0,
                    "categories": [{
                      "id": 7, "menu_id": 3, "name": { "en": "Mains" }, "is_active": true, "sort_order": 0,
                      "items": [{
                        "id": 42, "category_id": 7, "name": { "en": "Burger" }, "description": { "en": "Beef, brioche" },
                        "price_minor": 1100, "is_available": true, "show_online": true, "dietary": "none", "allergens": ["gluten", "milk"], "sort_order": 1,
                        "variants": [], "modifier_groups": [], "updated_at": "2026-09-29T10:12:00+00:00"
                      }]
                    }]
                  },
                  "meta": { "currency": "EUR", "now": { "available": true, "closed_category_ids": [], "prices": [] } },
                  "links": {}
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/categories": {
      "get": {
        "tags": ["Menu"],
        "operationId": "listCategories",
        "summary": "Every category, or one menu's",
        "x-scope": "menu:read",
        "parameters": [{ "name": "menu_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Only this menu's categories." }],
        "responses": {
          "200": {
            "description": "The categories.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta", "links"],
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } },
                    "meta": { "type": "object", "required": ["count"], "properties": { "count": { "type": "integer" } } },
                    "links": { "$ref": "#/components/schemas/NoLinks" }
                  }
                },
                "example": { "data": [{ "id": 7, "menu_id": 3, "name": { "en": "Mains" }, "is_active": true, "sort_order": 0 }], "meta": { "count": 1 }, "links": {} }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/items": {
      "get": {
        "tags": ["Menu"],
        "operationId": "listItems",
        "summary": "Dishes, a page at a time",
        "x-scope": "menu:read",
        "parameters": [
          { "name": "category_id", "in": "query", "required": false, "schema": { "type": "integer" } },
          { "name": "available", "in": "query", "required": false, "schema": { "type": "string", "enum": ["true", "false", "1", "0"] } },
          { "$ref": "#/components/parameters/PerPage" },
          { "$ref": "#/components/parameters/Cursor" }
        ],
        "responses": {
          "200": {
            "description": "A page of dishes.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta", "links"],
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } },
                    "meta": { "$ref": "#/components/schemas/PageMetaWithCurrency" },
                    "links": { "$ref": "#/components/schemas/PageLinks" }
                  }
                },
                "example": {
                  "data": [{
                    "id": 42, "category_id": 7, "name": { "en": "Burger" }, "description": null, "price_minor": 1100, "is_available": true,
                    "show_online": true, "dietary": "none", "allergens": null, "sort_order": 1, "variants": [], "modifier_groups": [], "updated_at": "2026-09-29T10:12:00+00:00"
                  }],
                  "meta": { "currency": "EUR", "per_page": 25, "next_cursor": null, "prev_cursor": null },
                  "links": { "next": null, "prev": null }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "422": { "$ref": "#/components/responses/ValidationFailed" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "post": {
        "tags": ["Menu"],
        "operationId": "createItem",
        "summary": "Add a dish",
        "description": "`name` and `description` are a string in the restaurant's default language, or a translation map. A dish is priced by `price_minor`, or per size by `variants`.",
        "x-scope": "menu:write",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["category_id", "name"],
                "properties": {
                  "category_id": { "type": "integer" },
                  "name": { "$ref": "#/components/schemas/TextInput" },
                  "description": { "oneOf": [{ "$ref": "#/components/schemas/TextInput" }, { "type": "null" }] },
                  "price_minor": { "type": ["integer", "null"], "minimum": 0 },
                  "variants": {
                    "type": "array",
                    "maxItems": 20,
                    "items": { "type": "object", "required": ["name", "price_minor"], "properties": { "name": { "$ref": "#/components/schemas/Translations" }, "price_minor": { "type": "integer", "minimum": 0 }, "is_default": { "type": "boolean" } } }
                  },
                  "dietary": { "$ref": "#/components/schemas/Dietary" },
                  "allergens": { "type": ["array", "null"], "items": { "$ref": "#/components/schemas/Allergen" } },
                  "is_available": { "type": "boolean" },
                  "show_online": { "type": "boolean" },
                  "modifier_group_ids": { "type": "array", "items": { "type": "integer" } }
                }
              },
              "example": { "category_id": 7, "name": "Burger", "price_minor": 1100, "allergens": ["gluten"] }
            }
          }
        },
        "responses": {
          "201": { "$ref": "#/components/responses/ItemResponse" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "422": { "$ref": "#/components/responses/ValidationFailed" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/items/{item}": {
      "get": {
        "tags": ["Menu"],
        "operationId": "getItem",
        "summary": "One dish",
        "x-scope": "menu:read",
        "parameters": [{ "$ref": "#/components/parameters/ItemId" }],
        "responses": {
          "200": { "$ref": "#/components/responses/ItemResponse" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "patch": {
        "tags": ["Menu"],
        "operationId": "updateItem",
        "summary": "Change a dish",
        "description": "Only the fields sent change; variants and modifier groups are kept. A price change is recorded in the activity log. A dish priced per size refuses `price_minor`.",
        "x-scope": "menu:write",
        "parameters": [{ "$ref": "#/components/parameters/ItemId" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "category_id": { "type": "integer" },
                  "name": { "$ref": "#/components/schemas/TextInput" },
                  "description": { "oneOf": [{ "$ref": "#/components/schemas/TextInput" }, { "type": "null" }] },
                  "price_minor": { "type": "integer", "minimum": 0 },
                  "dietary": { "$ref": "#/components/schemas/Dietary" },
                  "allergens": { "type": ["array", "null"], "items": { "$ref": "#/components/schemas/Allergen" } },
                  "is_available": { "type": "boolean" },
                  "show_online": { "type": "boolean" }
                }
              },
              "example": { "price_minor": 1250 }
            }
          }
        },
        "responses": {
          "200": { "$ref": "#/components/responses/ItemResponse" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "422": { "$ref": "#/components/responses/ValidationFailed" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/items/{item}/availability": {
      "put": {
        "tags": ["Menu"],
        "operationId": "setItemAvailability",
        "summary": "Sold out, and back",
        "description": "Recorded like a flip on the till.",
        "x-scope": "menu:write",
        "parameters": [{ "$ref": "#/components/parameters/ItemId" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "type": "object", "required": ["is_available"], "properties": { "is_available": { "type": "boolean" } } },
              "example": { "is_available": false }
            }
          }
        },
        "responses": {
          "200": { "$ref": "#/components/responses/ItemResponse" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "422": { "$ref": "#/components/responses/ValidationFailed" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/orders": {
      "get": {
        "tags": ["Orders"],
        "operationId": "listOrders",
        "summary": "Orders, newest first",
        "x-scope": "orders:read",
        "parameters": [
          { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One status or a comma list: `placed,accepted`." },
          { "name": "type", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/OrderType" } },
          { "name": "channel", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "placed_from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "A date or date-time." },
          { "name": "placed_to", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/PerPage" },
          { "$ref": "#/components/parameters/Cursor" }
        ],
        "responses": {
          "200": {
            "description": "A page of orders.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta", "links"],
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } },
                    "meta": { "$ref": "#/components/schemas/PageMeta" },
                    "links": { "$ref": "#/components/schemas/PageLinks" }
                  }
                },
                "example": { "data": [], "meta": { "per_page": 25, "next_cursor": null, "prev_cursor": null }, "links": { "next": null, "prev": null } }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "422": { "$ref": "#/components/responses/ValidationFailed" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "post": {
        "tags": ["Orders"],
        "operationId": "createOrder",
        "summary": "Place an order",
        "description": "The order is priced from the menu (any price in the body is ignored), the owner's ordering rules apply (types offered, minimum order, delivery zones, opening hours; an order outside hours is held for the next opening), the kitchen gets its tickets and a connected POS gets the order. Dine-in orders need `table_code`.",
        "x-scope": "orders:write",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["type", "customer_name", "customer_phone", "lines"],
                "properties": {
                  "type": { "$ref": "#/components/schemas/OrderType" },
                  "channel": { "type": "string", "enum": ["web", "phone", "whatsapp"] },
                  "table_code": { "type": ["string", "null"] },
                  "customer_name": { "type": "string", "maxLength": 120 },
                  "customer_phone": { "type": "string", "maxLength": 40 },
                  "customer_email": { "type": ["string", "null"], "format": "email" },
                  "note": { "type": ["string", "null"], "maxLength": 500 },
                  "scheduled_for": { "type": ["string", "null"], "format": "date-time" },
                  "delivery_address": { "type": ["object", "null"], "properties": { "line1": { "type": "string" }, "city": { "type": "string" }, "phone": { "type": "string" } } },
                  "lines": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 100,
                    "items": {
                      "type": "object",
                      "required": ["item_id", "quantity"],
                      "properties": {
                        "item_id": { "type": "integer" },
                        "variant_id": { "type": ["integer", "null"] },
                        "quantity": { "type": "integer", "minimum": 1, "maximum": 99 },
                        "option_ids": { "type": "array", "items": { "type": "integer" } }
                      }
                    }
                  }
                }
              },
              "example": {
                "type": "delivery", "channel": "web", "customer_name": "Ada Lovelace", "customer_phone": "+15550100", "customer_email": "ada@example.com",
                "note": "Ring twice", "delivery_address": { "line1": "12 Main St", "city": "Springfield" },
                "lines": [{ "item_id": 42, "quantity": 2, "option_ids": [9] }, { "item_id": 43, "variant_id": 11, "quantity": 1 }]
              }
            }
          }
        },
        "responses": {
          "201": { "$ref": "#/components/responses/OrderResponse" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "422": { "$ref": "#/components/responses/ValidationFailed" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/orders/{order}": {
      "get": {
        "tags": ["Orders"],
        "operationId": "getOrder",
        "summary": "One order",
        "x-scope": "orders:read",
        "parameters": [{ "$ref": "#/components/parameters/OrderId" }],
        "responses": {
          "200": { "$ref": "#/components/responses/OrderResponse" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/orders/{order}/status": {
      "post": {
        "tags": ["Orders"],
        "operationId": "changeOrderStatus",
        "summary": "Move an order one step",
        "description": "`placed` to `accepted` or `rejected`, `accepted` to `ready`, `ready` to `completed`, and anything not finished to `cancelled`. Accepting fires the kitchen. A cancel with a `reason` (3 to 200 characters) also voids the kitchen tickets and keeps the reason.",
        "x-scope": "orders:write",
        "parameters": [{ "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["status"],
                "properties": {
                  "status": { "type": "string", "enum": ["accepted", "rejected", "ready", "completed", "cancelled"] },
                  "reason": { "type": ["string", "null"], "minLength": 3, "maxLength": 200 }
                }
              },
              "example": { "status": "accepted" }
            }
          }
        },
        "responses": {
          "200": { "$ref": "#/components/responses/OrderResponse" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "422": { "$ref": "#/components/responses/ValidationFailed" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/reservations": {
      "get": {
        "tags": ["Reservations"],
        "operationId": "listReservations",
        "summary": "Bookings for a day or a range",
        "x-scope": "reservations:read",
        "parameters": [
          { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } },
          { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } },
          { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } },
          { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ReservationStatus" } },
          { "$ref": "#/components/parameters/PerPage" },
          { "$ref": "#/components/parameters/Cursor" }
        ],
        "responses": {
          "200": {
            "description": "A page of bookings.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta", "links"],
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Reservation" } },
                    "meta": { "$ref": "#/components/schemas/PageMeta" },
                    "links": { "$ref": "#/components/schemas/PageLinks" }
                  }
                },
                "example": { "data": [], "meta": { "per_page": 25, "next_cursor": null, "prev_cursor": null }, "links": { "next": null, "prev": null } }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "422": { "$ref": "#/components/responses/ValidationFailed" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "post": {
        "tags": ["Reservations"],
        "operationId": "createReservation",
        "summary": "Write a booking down",
        "description": "The booking rules apply (party size, lead time, closing days); the guest gets the same confirmation as for a phone booking.",
        "x-scope": "reservations:write",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "phone", "party_size", "date", "time"],
                "properties": {
                  "name": { "type": "string", "maxLength": 120 },
                  "phone": { "type": "string", "maxLength": 40 },
                  "email": { "type": ["string", "null"], "format": "email" },
                  "party_size": { "type": "integer", "minimum": 1 },
                  "date": { "type": "string", "format": "date" },
                  "time": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$" },
                  "table_id": { "type": ["integer", "null"] },
                  "note": { "type": ["string", "null"], "maxLength": 500 },
                  "status": { "type": "string", "enum": ["pending", "confirmed"] }
                }
              },
              "example": { "name": "Ada Lovelace", "phone": "+15550100", "party_size": 2, "date": "2026-10-03", "time": "19:30" }
            }
          }
        },
        "responses": {
          "201": { "$ref": "#/components/responses/ReservationResponse" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "422": { "$ref": "#/components/responses/ValidationFailed" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/availability": {
      "get": {
        "tags": ["Reservations"],
        "operationId": "getAvailability",
        "summary": "Bookable times for a day and a party",
        "x-scope": "reservations:read",
        "parameters": [
          { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } },
          { "name": "party_size", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } }
        ],
        "responses": {
          "200": {
            "description": "The day's slots.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta", "links"],
                  "properties": {
                    "data": { "$ref": "#/components/schemas/Availability" },
                    "meta": { "$ref": "#/components/schemas/NoLinks" },
                    "links": { "$ref": "#/components/schemas/NoLinks" }
                  }
                },
                "example": {
                  "data": { "date": "2026-10-03", "party_size": 2, "engine": true, "slots": [{ "time": "19:00", "available": true, "guarantee": false }, { "time": "19:30", "available": false, "guarantee": false }], "guarantee": null, "notify": true },
                  "meta": {},
                  "links": {}
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "422": { "$ref": "#/components/responses/ValidationFailed" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/reservations/{reservation}": {
      "get": {
        "tags": ["Reservations"],
        "operationId": "getReservation",
        "summary": "One booking",
        "x-scope": "reservations:read",
        "parameters": [{ "$ref": "#/components/parameters/ReservationId" }],
        "responses": {
          "200": { "$ref": "#/components/responses/ReservationResponse" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/reservations/{reservation}/cancel": {
      "post": {
        "tags": ["Reservations"],
        "operationId": "cancelReservation",
        "summary": "Cancel a booking",
        "description": "Cancelled by the restaurant; the guest is told.",
        "x-scope": "reservations:write",
        "parameters": [{ "$ref": "#/components/parameters/ReservationId" }, { "$ref": "#/components/parameters/IdempotencyKey" }],
        "responses": {
          "200": { "$ref": "#/components/responses/ReservationResponse" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/guests": {
      "get": {
        "tags": ["Guests"],
        "operationId": "listGuests",
        "summary": "Guest profiles, a page at a time",
        "description": "Guests who asked to be forgotten never appear. Phone and email are included only for guests who agreed to hear from the restaurant. Staff notes are never included.",
        "x-scope": "guests:read",
        "parameters": [
          { "name": "marketing_opted_in", "in": "query", "required": false, "schema": { "type": "string", "enum": ["true", "false", "1", "0"] } },
          { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/PerPage" },
          { "$ref": "#/components/parameters/Cursor" }
        ],
        "responses": {
          "200": {
            "description": "A page of guests.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta", "links"],
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Guest" } },
                    "meta": { "$ref": "#/components/schemas/PageMeta" },
                    "links": { "$ref": "#/components/schemas/PageLinks" }
                  }
                },
                "example": {
                  "data": [{
                    "id": 5, "name": "Ada Lovelace", "phone": "+15550100", "email": "ada@example.com", "contact_shared": true, "locale": "en",
                    "marketing_opted_in": true, "marketing_opted_in_at": "2026-09-01T12:00:00+00:00", "visits_count": 4, "total_spend_minor": 9200,
                    "last_visit_at": "2026-09-28T20:15:00+00:00", "created_at": "2026-06-02T19:40:00+00:00"
                  }],
                  "meta": { "per_page": 25, "next_cursor": null, "prev_cursor": null },
                  "links": { "next": null, "prev": null }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "422": { "$ref": "#/components/responses/ValidationFailed" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/guests/{guest}": {
      "get": {
        "tags": ["Guests"],
        "operationId": "getGuest",
        "summary": "One guest profile",
        "x-scope": "guests:read",
        "parameters": [{ "name": "guest", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "responses": {
          "200": {
            "description": "The guest.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta", "links"],
                  "properties": { "data": { "$ref": "#/components/schemas/Guest" }, "meta": { "$ref": "#/components/schemas/NoLinks" }, "links": { "$ref": "#/components/schemas/NoLinks" } }
                },
                "example": {
                  "data": {
                    "id": 6, "name": "Alan Turing", "phone": null, "email": null, "contact_shared": false, "locale": null, "marketing_opted_in": false,
                    "marketing_opted_in_at": null, "visits_count": 1, "total_spend_minor": 2400, "last_visit_at": null, "created_at": "2026-09-30T11:00:00+00:00"
                  },
                  "meta": {},
                  "links": {}
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/reports/sales-summary": {
      "get": {
        "tags": ["Reports"],
        "operationId": "getSalesSummary",
        "summary": "Revenue, orders and average order for a period",
        "description": "With the preceding period of the same length. Defaults to today on the restaurant's clock; at most 366 days.",
        "x-scope": "reports:read",
        "parameters": [
          { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } },
          { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } },
          { "name": "branch_id", "in": "query", "required": false, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": {
            "description": "The summary.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta", "links"],
                  "properties": { "data": { "$ref": "#/components/schemas/SalesSummary" }, "meta": { "$ref": "#/components/schemas/NoLinks" }, "links": { "$ref": "#/components/schemas/NoLinks" } }
                },
                "example": {
                  "data": {
                    "from": "2026-09-01", "to": "2026-09-30", "branch_id": null, "currency": "EUR", "orders": 812, "revenue_minor": 1843200, "average_order_minor": 2270,
                    "previous": { "orders": 760, "revenue_minor": 1690000, "average_order_minor": 2223 },
                    "change": { "revenue_pct": 9.1, "orders_pct": 6.8 }
                  },
                  "meta": {},
                  "links": {}
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "422": { "$ref": "#/components/responses/ValidationFailed" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/oauth/token": {
      "servers": [{ "url": "/", "description": "This BookNDish host. The OAuth endpoints sit at its root, not under /api/v1." }],
      "post": {
        "operationId": "oauthToken",
        "tags": ["OAuth"],
        "summary": "Exchange a code, or refresh, for tokens",
        "description": "`authorization_code`: redeem the code the venue's consent sent to your redirect address, with the PKCE verifier. `refresh_token`: get a new access token and a new refresh token; the old pair stops working. Authenticate with your client id and secret, as HTTP Basic or as `client_id` and `client_secret` in the body. Answers are never cached.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/OAuthTokenRequest" } },
            "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenRequest" }, "example": { "grant_type": "authorization_code", "code": "bnd_ac_9fK2...", "redirect_uri": "https://app.example.com/callback", "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk", "client_id": "bnd_app_4kq8...", "client_secret": "bnd_cs_..." } }
          }
        },
        "responses": {
          "200": {
            "description": "Tokens.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokens" }, "example": { "access_token": "812|bnd_oat_Xf3k...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "bnd_ort_q8Lz...", "scope": "menu:read orders:read" } } }
          },
          "400": {
            "$ref": "#/components/responses/OAuthBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/OAuthInvalidClient"
          },
          "429": {
            "$ref": "#/components/responses/OAuthRateLimited"
          }
        }
      }
    },
    "/oauth/revoke": {
      "servers": [{ "url": "/", "description": "This BookNDish host. The OAuth endpoints sit at its root, not under /api/v1." }],
      "post": {
        "operationId": "oauthRevoke",
        "tags": ["OAuth"],
        "summary": "Revoke a token",
        "description": "Gives back a refresh token (with its access token) or an access token (RFC 7009). An unknown token is not an error. Authenticate with your client id and secret, as HTTP Basic or as `client_id` and `client_secret` in the body. To end the whole grant, the venue uninstalls the app.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/OAuthRevokeRequest" } },
            "application/json": { "schema": { "$ref": "#/components/schemas/OAuthRevokeRequest" }, "example": { "token": "bnd_ort_q8Lz...", "client_id": "bnd_app_4kq8...", "client_secret": "bnd_cs_..." } }
          }
        },
        "responses": {
          "200": {
            "description": "Revoked, or already unknown.",
            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false }, "example": {} } }
          },
          "400": {
            "$ref": "#/components/responses/OAuthBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/OAuthInvalidClient"
          },
          "429": {
            "$ref": "#/components/responses/OAuthRateLimited"
          }
        }
      }
    }
  },
  "webhooks": {
    "event": {
      "post": {
        "summary": "Every webhook delivery",
        "description": "A `POST` to each address subscribed to the event, signed with `BookNDish-Signature: t=<unix time>,v1=<hex HMAC-SHA256 of \"{t}.{raw body}\" keyed with the endpoint's secret>`. `BookNDish-Event` names the event and `BookNDish-Delivery` carries the event id, the same on a retry or resend. Answer with any 2xx within 10 seconds; anything else is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours. Deliveries may arrive more than once and out of order: deduplicate on `id`. `ping` is the test event sent from the Developers screen.",
        "parameters": [
          { "name": "BookNDish-Event", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/WebhookEventType" } },
          { "name": "BookNDish-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } },
          { "name": "BookNDish-Signature", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/WebhookEnvelope" },
              "example": {
                "id": "1f0c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
                "type": "stock.below_par",
                "created_at": "2026-09-29T10:15:02+00:00",
                "restaurant": { "id": 12, "slug": "trattoria", "currency": "EUR" },
                "data": { "stock": { "ingredient": { "id": 4, "name": "Tomatoes", "sku": "TOM-1", "unit": "kg" }, "branch_id": 1, "on_hand": 4, "par_level": 5, "previous_on_hand": 6 } }
              }
            }
          }
        },
        "responses": { "200": { "description": "Any 2xx marks the delivery done." } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A restaurant's API token, `<id>|bnd_...` (or `<id>|bnd_sbx_...` for a sandbox), created on Settings > Developers. Each operation names the scope it needs in `x-scope`." },
      "oauth2": {
        "type": "oauth2",
        "description": "For apps registered in the marketplace (Settings > Developers > Apps) and installed by a venue. The access token is a bearer token for this API, valid one hour, limited to the scopes the venue granted; refresh it with the refresh token, which is replaced on every use. Send the owner to `/oauth/authorize` with `response_type=code`, your `client_id`, a registered `redirect_uri`, the `scope`s, a `state` and a PKCE `code_challenge` (`code_challenge_method=S256`).",
        "flows": {
          "authorizationCode": { "authorizationUrl": "/oauth/authorize", "tokenUrl": "/oauth/token", "refreshUrl": "/oauth/token", "scopes": { "menu:read": "Read the menu", "menu:write": "Change dishes, prices and sold out", "orders:read": "Read orders", "orders:write": "Place orders and change their status", "reservations:read": "Read bookings", "reservations:write": "Make and cancel bookings", "guests:read": "Read guest profiles", "reports:read": "Read sales reports" } }
        }
      }
    },
    "parameters": {
      "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Any POST may carry one. A retry with the same key and body within 24 hours gets the first response back (`Idempotent-Replayed: true`)." },
      "PerPage": { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } },
      "Cursor": { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "From `meta.next_cursor`, or follow `links.next`." },
      "MenuId": { "name": "menu", "in": "path", "required": true, "schema": { "type": "integer" } },
      "ItemId": { "name": "item", "in": "path", "required": true, "schema": { "type": "integer" } },
      "OrderId": { "name": "order", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } },
      "ReservationId": { "name": "reservation", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
    },
    "responses": {
      "ItemResponse": {
        "description": "The dish.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": ["data", "meta", "links"],
              "properties": {
                "data": { "$ref": "#/components/schemas/Item" },
                "meta": { "type": "object", "required": ["currency"], "properties": { "currency": { "$ref": "#/components/schemas/Currency" } } },
                "links": { "$ref": "#/components/schemas/NoLinks" }
              }
            },
            "example": {
              "data": {
                "id": 42, "category_id": 7, "name": { "en": "Burger" }, "description": { "en": "Beef, brioche" }, "price_minor": 1100, "is_available": true, "show_online": true,
                "dietary": "none", "allergens": ["gluten", "milk"], "sort_order": 1, "variants": [],
                "modifier_groups": [{ "id": 5, "name": { "en": "Extras" }, "min_select": 0, "max_select": null, "options": [{ "id": 9, "name": { "en": "Cheese" }, "price_minor": 100, "is_available": true }] }],
                "updated_at": "2026-09-29T10:12:00+00:00"
              },
              "meta": { "currency": "USD" },
              "links": {}
            }
          }
        }
      },
      "OrderResponse": {
        "description": "The order.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": ["data", "meta", "links"],
              "properties": { "data": { "$ref": "#/components/schemas/Order" }, "meta": { "$ref": "#/components/schemas/NoLinks" }, "links": { "$ref": "#/components/schemas/NoLinks" } }
            },
            "example": {
              "data": {
                "id": "9d1c7a52-8f0e-4b8c-a1f5-3a1a5b1f0c2d", "status": "placed", "type": "delivery", "channel": "web", "branch_id": 1, "table": null,
                "customer": { "name": "Ada Lovelace", "phone": "+15550100", "email": "ada@example.com" }, "note": "Ring twice",
                "delivery_address": { "line1": "12 Main St", "city": "Springfield" }, "currency": "USD",
                "subtotal_minor": 2300, "discount_minor": 0, "service_charge_minor": 0, "tax_added_minor": 0, "delivery_fee_minor": 300, "total_minor": 2600,
                "tax_breakdown": null, "cancel_reason": null,
                "items": [{ "id": 1, "item_id": 42, "name": { "en": "Burger" }, "variant_name": null, "quantity": 2, "unit_price_minor": 1200, "line_total_minor": 2400, "voided": false, "modifiers": [{ "name": { "en": "Cheese" }, "price_minor": 100 }] }],
                "placed_at": "2026-09-29T10:15:00+00:00", "scheduled_for": null, "paid_at": null, "updated_at": "2026-09-29T10:15:00+00:00"
              },
              "meta": {},
              "links": {}
            }
          }
        }
      },
      "ReservationResponse": {
        "description": "The booking.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": ["data", "meta", "links"],
              "properties": { "data": { "$ref": "#/components/schemas/Reservation" }, "meta": { "$ref": "#/components/schemas/NoLinks" }, "links": { "$ref": "#/components/schemas/NoLinks" } }
            },
            "example": {
              "data": {
                "id": "1b6e1c1e-2f4f-4c43-9e0e-4b9d6f1a2c3d", "status": "confirmed", "name": "Ada Lovelace", "phone": "+15550100", "email": null, "party_size": 2,
                "date": "2026-10-03", "time": "19:30", "table_id": null, "note": null, "deposit_minor": null, "deposit_status": null,
                "created_at": "2026-10-01T09:00:00+00:00", "updated_at": "2026-10-01T09:00:00+00:00"
              },
              "meta": {},
              "links": {}
            }
          }
        }
      },
      "Unauthenticated": { "description": "Missing, unknown, revoked or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthenticated", "message": "A valid API token is required.", "details": {} } } } } },
      "Forbidden": { "description": "The token lacks the scope (`insufficient_scope`), the plan lacks the feature (`plan_feature_unavailable`), a write while the restaurant is suspended (`restaurant_suspended`), or any call while it has no plan in force (`plan_lapsed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "This token does not have the scope this endpoint needs.", "details": { "required_scope": "orders:write" } } } } } },
      "NotFound": { "description": "No such resource for this restaurant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Not found.", "details": {} } } } } },
      "Conflict": { "description": "An order or booking cannot move to that status from where it is (`invalid_transition`), or the first request with this Idempotency-Key is still running (`idempotency_key_in_use`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_transition", "message": "The order cannot move to that status.", "details": {} } } } } },
      "ValidationFailed": { "description": "Invalid fields (`validation_failed`, with `details` mapping each field to its messages), or an Idempotency-Key reused with another body (`idempotency_key_reused`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_failed", "message": "The request has invalid fields.", "details": { "lines.0.item_id": ["The selected lines.0.item_id is invalid."] } } } } } },
      "RateLimited": { "description": "Too many requests for this token; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too many requests.", "details": {} } } } } },
      "OAuthBadRequest": { "description": "The request or the grant is not valid (RFC 6749 section 5.2).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" }, "example": { "error": "invalid_grant", "error_description": "The code_verifier does not match the code_challenge." } } } },
      "OAuthInvalidClient": { "description": "The client id or secret is wrong.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" }, "example": { "error": "invalid_client", "error_description": "The client could not be authenticated." } } } },
      "OAuthRateLimited": { "description": "Too many requests from this address; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "type": "object", "required": ["message"], "properties": { "message": { "type": "string" } } }, "example": { "message": "Too Many Attempts." } } } }
    },
    "schemas": {
      "Currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217." },
      "Translations": { "type": "object", "description": "Text by language code.", "additionalProperties": { "type": ["string", "null"] } },
      "TextInput": { "oneOf": [{ "type": "string" }, { "$ref": "#/components/schemas/Translations" }] },
      "Dietary": { "type": "string", "enum": ["none", "veg", "non_veg", "egg", "vegan"] },
      "Allergen": { "type": "string", "enum": ["gluten", "crustaceans", "eggs", "fish", "peanuts", "soybeans", "milk", "nuts", "celery", "mustard", "sesame", "sulphites", "lupin", "molluscs"] },
      "OrderType": { "type": "string", "enum": ["dine_in", "pickup", "delivery"] },
      "OrderStatus": { "type": "string", "enum": ["placed", "accepted", "rejected", "ready", "completed", "cancelled"] },
      "ReservationStatus": { "type": "string", "enum": ["pending", "confirmed", "declined", "cancelled", "seated", "no_show"] },
      "NoLinks": { "type": "object", "description": "Empty here." },
      "PageMeta": {
        "type": "object",
        "required": ["per_page", "next_cursor", "prev_cursor"],
        "properties": { "per_page": { "type": "integer" }, "next_cursor": { "type": ["string", "null"] }, "prev_cursor": { "type": ["string", "null"] } }
      },
      "PageMetaWithCurrency": {
        "type": "object",
        "required": ["currency", "per_page", "next_cursor", "prev_cursor"],
        "properties": { "currency": { "$ref": "#/components/schemas/Currency" }, "per_page": { "type": "integer" }, "next_cursor": { "type": ["string", "null"] }, "prev_cursor": { "type": ["string", "null"] } }
      },
      "PageLinks": {
        "type": "object",
        "required": ["next", "prev"],
        "properties": { "next": { "type": ["string", "null"] }, "prev": { "type": ["string", "null"] } }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message", "details"],
            "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }
          }
        }
      },
      "Menu": {
        "type": "object",
        "required": ["id", "name", "is_active", "sort_order"],
        "properties": { "id": { "type": "integer" }, "name": { "$ref": "#/components/schemas/Translations" }, "is_active": { "type": "boolean" }, "sort_order": { "type": "integer" } }
      },
      "MenuWithCategories": {
        "type": "object",
        "required": ["id", "name", "is_active", "sort_order", "categories"],
        "properties": {
          "id": { "type": "integer" }, "name": { "$ref": "#/components/schemas/Translations" }, "is_active": { "type": "boolean" }, "sort_order": { "type": "integer" },
          "categories": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }
        }
      },
      "MenuWithItems": {
        "type": "object",
        "required": ["id", "name", "is_active", "sort_order", "categories"],
        "properties": {
          "id": { "type": "integer" }, "name": { "$ref": "#/components/schemas/Translations" }, "is_active": { "type": "boolean" }, "sort_order": { "type": "integer" },
          "categories": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryWithItems" } }
        }
      },
      "Category": {
        "type": "object",
        "required": ["id", "menu_id", "name", "is_active", "sort_order"],
        "properties": { "id": { "type": "integer" }, "menu_id": { "type": "integer" }, "name": { "$ref": "#/components/schemas/Translations" }, "is_active": { "type": "boolean" }, "sort_order": { "type": "integer" } }
      },
      "CategoryWithItems": {
        "type": "object",
        "required": ["id", "menu_id", "name", "is_active", "sort_order", "items"],
        "properties": {
          "id": { "type": "integer" }, "menu_id": { "type": "integer" }, "name": { "$ref": "#/components/schemas/Translations" }, "is_active": { "type": "boolean" }, "sort_order": { "type": "integer" },
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } }
        }
      },
      "Item": {
        "type": "object",
        "required": ["id", "category_id", "name", "description", "price_minor", "is_available", "show_online", "dietary", "allergens", "sort_order", "variants", "modifier_groups", "updated_at"],
        "properties": {
          "id": { "type": "integer" },
          "category_id": { "type": "integer" },
          "name": { "$ref": "#/components/schemas/Translations" },
          "description": { "oneOf": [{ "$ref": "#/components/schemas/Translations" }, { "type": "null" }] },
          "price_minor": { "type": ["integer", "null"], "description": "Null for a dish priced per size (variants)." },
          "is_available": { "type": "boolean" },
          "show_online": { "type": "boolean" },
          "dietary": { "$ref": "#/components/schemas/Dietary" },
          "allergens": { "type": ["array", "null"], "items": { "$ref": "#/components/schemas/Allergen" } },
          "sort_order": { "type": "integer" },
          "variants": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["id", "name", "price_minor", "is_default"],
              "properties": { "id": { "type": "integer" }, "name": { "$ref": "#/components/schemas/Translations" }, "price_minor": { "type": "integer" }, "is_default": { "type": "boolean" } }
            }
          },
          "modifier_groups": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["id", "name", "min_select", "max_select", "options"],
              "properties": {
                "id": { "type": "integer" }, "name": { "$ref": "#/components/schemas/Translations" }, "min_select": { "type": "integer" }, "max_select": { "type": ["integer", "null"] },
                "options": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": ["id", "name", "price_minor", "is_available"],
                    "properties": { "id": { "type": "integer" }, "name": { "$ref": "#/components/schemas/Translations" }, "price_minor": { "type": "integer" }, "is_available": { "type": "boolean" } }
                  }
                }
              }
            }
          },
          "updated_at": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "Order": {
        "type": "object",
        "required": ["id", "status", "type", "channel", "branch_id", "table", "customer", "note", "delivery_address", "currency", "subtotal_minor", "discount_minor", "service_charge_minor", "tax_added_minor", "delivery_fee_minor", "total_minor", "tax_breakdown", "cancel_reason", "items", "placed_at", "scheduled_for", "paid_at", "updated_at"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "status": { "$ref": "#/components/schemas/OrderStatus" },
          "type": { "$ref": "#/components/schemas/OrderType" },
          "channel": { "type": "string", "description": "web, phone, whatsapp, qr, pos, kiosk, or a delivery marketplace." },
          "branch_id": { "type": ["integer", "null"] },
          "table": {
            "type": ["object", "null"],
            "required": ["id", "name", "code"],
            "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "code": { "type": ["string", "null"] } }
          },
          "customer": {
            "type": "object",
            "required": ["name", "phone", "email"],
            "properties": { "name": { "type": ["string", "null"] }, "phone": { "type": ["string", "null"] }, "email": { "type": ["string", "null"] } }
          },
          "note": { "type": ["string", "null"] },
          "delivery_address": { "type": ["object", "null"], "additionalProperties": true },
          "currency": { "$ref": "#/components/schemas/Currency" },
          "subtotal_minor": { "type": "integer" },
          "discount_minor": { "type": "integer" },
          "service_charge_minor": { "type": "integer" },
          "tax_added_minor": { "type": "integer" },
          "delivery_fee_minor": { "type": "integer" },
          "total_minor": { "type": "integer" },
          "tax_breakdown": { "description": "Tax per rate where the venue's tax mode records it.", "type": ["array", "object", "null"] },
          "cancel_reason": { "type": ["string", "null"] },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["id", "item_id", "name", "variant_name", "quantity", "unit_price_minor", "line_total_minor", "voided", "modifiers"],
              "properties": {
                "id": { "type": "integer" },
                "item_id": { "type": ["integer", "null"] },
                "name": { "$ref": "#/components/schemas/Translations" },
                "variant_name": { "oneOf": [{ "$ref": "#/components/schemas/Translations" }, { "type": "null" }] },
                "quantity": { "type": "integer" },
                "unit_price_minor": { "type": "integer" },
                "line_total_minor": { "type": "integer" },
                "voided": { "type": "boolean" },
                "modifiers": {
                  "type": "array",
                  "items": { "type": "object", "required": ["name", "price_minor"], "properties": { "name": { "$ref": "#/components/schemas/Translations" }, "price_minor": { "type": "integer" } } }
                }
              }
            }
          },
          "placed_at": { "type": ["string", "null"], "format": "date-time" },
          "scheduled_for": { "type": ["string", "null"], "format": "date-time" },
          "paid_at": { "type": ["string", "null"], "format": "date-time" },
          "updated_at": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "Reservation": {
        "type": "object",
        "required": ["id", "status", "name", "phone", "email", "party_size", "date", "time", "table_id", "note", "deposit_minor", "deposit_status", "created_at", "updated_at"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "status": { "$ref": "#/components/schemas/ReservationStatus" },
          "name": { "type": "string" },
          "phone": { "type": ["string", "null"] },
          "email": { "type": ["string", "null"] },
          "party_size": { "type": "integer" },
          "date": { "type": "string", "format": "date", "description": "The restaurant's own calendar, as the guest booked." },
          "time": { "type": "string", "description": "HH:MM on the restaurant's clock." },
          "table_id": { "type": ["integer", "null"] },
          "note": { "type": ["string", "null"] },
          "deposit_minor": { "type": ["integer", "null"] },
          "deposit_status": { "type": ["string", "null"], "enum": ["pending", "paid", "forfeited", "refunded", "waived", null] },
          "created_at": { "type": ["string", "null"], "format": "date-time" },
          "updated_at": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "Availability": {
        "type": "object",
        "required": ["date", "party_size", "engine", "slots", "guarantee", "notify"],
        "properties": {
          "date": { "type": "string", "format": "date" },
          "party_size": { "type": "integer" },
          "engine": { "type": "boolean", "description": "Whether the table availability engine answered (true), or the venue's fixed booking times did (false)." },
          "slots": {
            "type": "array",
            "items": { "type": "object", "required": ["time", "available", "guarantee"], "properties": { "time": { "type": "string" }, "available": { "type": "boolean" }, "guarantee": { "type": "boolean" } } }
          },
          "guarantee": {
            "type": ["object", "null"],
            "required": ["fee_minor", "cancel_hours"],
            "properties": { "fee_minor": { "type": "integer" }, "cancel_hours": { "type": ["integer", "null"] } }
          },
          "notify": { "type": "boolean", "description": "Whether a guest may ask to be told when a full time frees up." }
        }
      },
      "Guest": {
        "type": "object",
        "required": ["id", "name", "phone", "email", "contact_shared", "locale", "marketing_opted_in", "marketing_opted_in_at", "visits_count", "total_spend_minor", "last_visit_at", "created_at"],
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": ["string", "null"] },
          "phone": { "type": ["string", "null"], "description": "Only for a guest who agreed to share it." },
          "email": { "type": ["string", "null"], "description": "Only for a guest who agreed to share it." },
          "contact_shared": { "type": "boolean" },
          "locale": { "type": ["string", "null"] },
          "marketing_opted_in": { "type": "boolean" },
          "marketing_opted_in_at": { "type": ["string", "null"], "format": "date-time" },
          "visits_count": { "type": "integer" },
          "total_spend_minor": { "type": "integer" },
          "last_visit_at": { "type": ["string", "null"], "format": "date-time" },
          "created_at": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "SalesFigures": {
        "type": "object",
        "required": ["orders", "revenue_minor", "average_order_minor"],
        "properties": { "orders": { "type": "integer" }, "revenue_minor": { "type": "integer" }, "average_order_minor": { "type": "integer" } }
      },
      "SalesSummary": {
        "type": "object",
        "required": ["from", "to", "branch_id", "currency", "orders", "revenue_minor", "average_order_minor", "previous", "change"],
        "properties": {
          "from": { "type": "string", "format": "date" },
          "to": { "type": "string", "format": "date" },
          "branch_id": { "type": ["integer", "null"] },
          "currency": { "$ref": "#/components/schemas/Currency" },
          "orders": { "type": "integer" },
          "revenue_minor": { "type": "integer" },
          "average_order_minor": { "type": "integer" },
          "previous": { "$ref": "#/components/schemas/SalesFigures" },
          "unpaid_completed": {
            "description": "Completed orders in the range with no payment recorded. Null where the venue takes payments on its own register.",
            "type": ["object", "null"],
            "required": ["orders", "amount_minor"],
            "properties": { "orders": { "type": "integer" }, "amount_minor": { "type": "integer" } }
          },
          "change": {
            "type": "object",
            "required": ["revenue_pct", "orders_pct"],
            "properties": { "revenue_pct": { "type": ["number", "null"] }, "orders_pct": { "type": ["number", "null"] } }
          }
        }
      },
      "WebhookEventType": {
        "type": "string",
        "enum": ["order.created", "order.status_changed", "order.paid", "reservation.created", "reservation.updated", "reservation.cancelled", "menu.item_updated", "payment.refunded", "guest.created", "guest.updated", "giftcard.issued", "giftcard.redeemed", "review.created", "stock.below_par", "shift.published", "experience.booked", "ping"]
      },
      "WebhookEnvelope": {
        "type": "object",
        "required": ["id", "type", "created_at", "restaurant", "data"],
        "properties": {
          "id": { "type": "string", "format": "uuid", "description": "The event id, the same on every delivery of the event." },
          "type": { "$ref": "#/components/schemas/WebhookEventType" },
          "created_at": { "type": "string", "format": "date-time" },
          "restaurant": {
            "type": "object",
            "required": ["id", "slug", "currency"],
            "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "currency": { "$ref": "#/components/schemas/Currency" } }
          },
          "data": { "type": "object", "additionalProperties": true, "description": "The event's subject in the same shape as the API returns it: `order`, `reservation`, `item`, `guest`, `gift_card` with `transaction`, `review`, `stock`, `shifts`, `booking`." }
        }
      },
      "OAuthTokens": {
        "type": "object",
        "required": ["access_token", "token_type", "expires_in", "refresh_token", "scope"],
        "additionalProperties": false,
        "properties": { "access_token": { "type": "string", "description": "The bearer token for this API, `<id>|bnd_oat_...`." }, "token_type": { "type": "string", "enum": ["Bearer"] }, "expires_in": { "type": "integer", "description": "Seconds the access token lives: 3600." }, "refresh_token": { "type": "string", "description": "`bnd_ort_...`, valid 30 days, replaced on every use. A refresh token used twice revokes the whole grant." }, "scope": { "type": "string", "description": "The scopes granted, space-separated." } }
      },
      "OAuthError": {
        "type": "object",
        "required": ["error", "error_description"],
        "additionalProperties": false,
        "properties": { "error": { "type": "string", "enum": ["invalid_request", "invalid_client", "invalid_grant", "unsupported_grant_type"] }, "error_description": { "type": "string" } }
      },
      "OAuthTokenRequest": {
        "type": "object",
        "required": ["grant_type"],
        "properties": { "grant_type": { "type": "string", "enum": ["authorization_code", "refresh_token"] }, "code": { "type": "string", "description": "For `authorization_code`: the code from the redirect, single use, valid five minutes." }, "redirect_uri": { "type": "string", "description": "For `authorization_code`: the same address the code was sent to." }, "code_verifier": { "type": "string", "description": "For `authorization_code`: the PKCE verifier whose S256 hash was the `code_challenge`. Not sent for a code from the listing's Install button." }, "refresh_token": { "type": "string", "description": "For `refresh_token`." }, "client_id": { "type": "string", "description": "Unless sent as HTTP Basic." }, "client_secret": { "type": "string", "description": "Unless sent as HTTP Basic." } }
      },
      "OAuthRevokeRequest": {
        "type": "object",
        "required": ["token"],
        "properties": { "token": { "type": "string", "description": "A refresh token (its access token is revoked with it) or an access token." }, "client_id": { "type": "string" }, "client_secret": { "type": "string" } }
      }
    }
  }
}