{
  "openapi": "3.1.0",
  "info": {
    "title": "SodiumPOS API",
    "version": "1.0.0",
    "description": "The REST + WebSocket API behind SodiumPOS. Everything the terminal, owner dashboard and online store do goes through it, so you can build your own terminal, kiosk, kitchen display or storefront, or connect your back office.\n\n| Convention | |\n|---|---|\n| **Base URL** | `https://<your-host>/v1`; your SodiumPOS contact gives you the test and live hosts (a local server runs on `http://localhost:4000/v1`) |\n| **Format** | JSON request and response bodies. `Content-Type: application/json` is fine on requests without a body too. |\n| **Strict numbers** | Quantities (1–999), guests (1–500), seats, courses and money must be whole numbers in range, or you get `400` naming the field. Nothing is silently rounded or clamped. |\n| **CORS** | Any origin may call the API. Tokens are bearer tokens, never cookies. |\n| **Money** | Integer **cents** everywhere (`1250` = $12.50) |\n| **Percentages** | **Basis points** (`1000` = 10%, `887.5` = 8.875%) |\n| **Times** | ISO-8601 UTC |\n| **IDs** | Opaque strings with a type prefix (`ord_…`, `itm_…`). Don't parse them. |\n\nDownload the spec: [openapi.json](../openapi.json) (on an API server it's at `/site/openapi.json`). Import it into Postman, Insomnia or any OpenAPI code generator.\n\n# Authentication\n\nSend a token as `Authorization: Bearer <token>`. API keys can also be sent as `X-API-Key`.\n\n| Token | Prefix | From | Acts as |\n|---|---|---|---|\n| API key | `pk_live_` | Dashboard → API & white-label | Owner-level access to one restaurant for setup, menus, stock, reports, webhooks and reading orders. **Can't take orders or payments** (`403 terminal_required`). |\n| Partner key | `pk_live_` | Issued to a distributor | Any restaurant the partner owns; pick one with `X-Restaurant-Id`. Same prefix as an API key; `GET /v1/me` tells you which you hold. |\n| Portal session | `acc_` | Hosted sign-in (`audience` partner or platform); `POST /v1/accounts/login` on local-auth servers | A distributor, agent or platform admin in the partner or platform portal. 7 days. |\n| Dashboard session | `adm_` | Hosted sign-in (`audience=merchant`); `POST /v1/auth/login` on local-auth servers | An owner or manager in the admin portal. Like API keys, it can't take orders or payments. 7 days. |\n| Terminal token | `trm_` | `POST /v1/auth/terminals/pair` with a pairing code | A paired device with nobody signed in. Reads menu and floor; signs staff in. |\n| Staff session | `stf_` | `POST /v1/auth/pin` (terminal token) | The staff member who entered their PIN on that terminal. **Orders and payments are taken with this token.** 1 day. |\n\nEvery PIN typed on a terminal (sign-in, `verify-manager`, `manager_pin`) counts toward one limit: 8 wrong PINs lock that terminal for 5 minutes (`429`).\n\n**Sign-in.** `GET /v1/auth/config` says how the server signs people in. In production (`provider: cognito`) owners, managers, distributors and SodiumPOS staff sign in on a hosted page with a second factor, through `GET /v1/auth/oidc/authorize` and `POST /v1/auth/oidc/session`; there is no password endpoint. Each audience (platform, partner portal, and each merchant brand) is a separate login, so one email can be several. Integrations use API or partner keys and pair devices with `POST /v1/terminals/pairing-codes`. See docs/API.md §1.\n\n**Roles:** `owner` and `manager` can do everything. `server`, `bartender` and `cashier` handle orders, payments and 86. `kitchen` reads orders and manages stock.\n\n# Errors\n\nErrors use a non-2xx status and one body shape. `message` is written to be shown to staff as-is.\n\n```json\n{ \"error\": { \"code\": \"bad_request\", \"message\": \"Choose an option for \\\"Temperature\\\"\", \"details\": { \"group_id\": \"mgr_temp\", \"reason\": \"min\" } } }\n```\n\n| Status | `code` | Meaning |\n|---|---|---|\n| 400 | `bad_request`, `name_required`, `restaurant_required`, `card_required` | Validation failed (`details.field` names the field); a quick order needs a name, a tab needs a card |\n| 401 | `unauthorized` | Missing, invalid or expired token; wrong PIN; wrong `X-Webhook-Secret` |\n| 402 | `card_declined`, `insufficient_funds`, `capture_failed`, `refund_failed` | The processor said no |\n| 402 | `seat_limit`, `account_inactive`, `feature_required` | Billing: no free terminal seat, account suspended, add-on not bought |\n| 403 | `forbidden`, `manager_required`, `manager_pin_invalid` | Not allowed, or needs a manager |\n| 403 | `terminal_required`, `kitchen_display`, `web_only` | Selling needs a register; purchases are web-only |\n| 404 | `not_found` | Unknown id |\n| 409 | `conflict`, `version_conflict`, `idempotency_conflict`, `quote_changed` | State conflict (order closed, table occupied, overpaid, stale version, reused key) |\n| 423 | `order_locked` | Strict table locking: another server has the order |\n| 429 | `too_many_attempts` | Too many wrong PINs or passwords |\n| 500 | `internal` | A bug on our side |\n\n# Manager approval\n\nSensitive actions need a manager unless the signed-in user is one. Which actions is set in `settings.manager_required`: `refund` · `void_fired` · `comp` · `discount` · `reopen` · `tax_exempt` · `price_override`.\n\nMake the call normally. On `403 manager_required`, ask a manager for their PIN and repeat the **same request** with `\"manager_pin\"` added. The approver is recorded in the activity log and the exceptions report.\n\n```http\nPOST /v1/orders/ord_1/items/oli_9/void   { \"reason\": \"Changed mind\" }\n→ 403 { \"error\": { \"code\": \"manager_required\", \"details\": { \"action\": \"void_fired\" } } }\n\nPOST /v1/orders/ord_1/items/oli_9/void   { \"reason\": \"Changed mind\", \"manager_pin\": \"2222\" }\n→ 200 { …order… }\n```\n\n# Real-time stream\n\nConnect a WebSocket to `/v1/stream?token=<any token>`. Every client of a restaurant receives the same events, which is how terminals stay in sync. A bad token gets `401` before the upgrade; one that stops working later closes the socket with code 4001. Events are sent only once a change is saved.\n\n```json\n{ \"type\": \"order.updated\", \"data\": { \"order_id\": \"ord_…\", \"table_id\": \"tbl_…\", \"version\": 7 }, \"at\": \"2026-11-06T23:10:00.000Z\" }\n```\n\n| Event | When |\n|---|---|\n| `order.created` / `order.updated` / `order.closed` / `order.voided` | Any order change. Re-fetch the order. |\n| `order.locked` | A terminal opened or released an order |\n| `items.fired`, `item.voided` | Kitchen tickets |\n| `payment.created`, `payment.refunded` | |\n| `menu.updated`, `item.stock` | Menu change or 86. Re-fetch the menu. |\n| `floor.updated` | A table seated or freed, an order moved tables, joins, arrange moves, layout edits |\n| `print.job`, `online.order`, `delivery.updated`, `restaurant.updated` | |\n\nReconnect with backoff and re-fetch what you display.\n\n# Webhooks\n\nRegister a URL under **Webhooks** and events are `POST`ed to it with two headers:\n\n```http\nX-POS-Timestamp: 1762470600\nX-POS-Signature: sha256=<hex HMAC-SHA256 of \"<timestamp>.<raw body>\" with your secret>\n```\n\nVerify the signature in constant time and reject timestamps more than 5 minutes old (that stops replays). The secret is shown once, when the webhook is created. URLs must be public internet addresses on hosted servers. `events` defaults to all. Deliveries aren't retried yet: treat events as notifications and fetch the resource for current state.\n\n# Several terminals, one order\n\nEvery change is a small command applied atomically on the server (add item, fire, void, pay), so two terminals on the same table never overwrite each other. Payments, refunds and tips on one order run one at a time, so the same balance can't be charged twice. Each change bumps `version` and emits `order.updated`. `POST /orders/:id/lock` shows who has an order open; whole-object edits accept `expected_version`.\n\n# Close-out and tips\n\n1. Paying with `card` or `card_on_file` **authorizes** the card. The check is paid and the table frees up. Table service with no tip yet prints merchant and customer tip slips.\n2. Paid orders wait to be closed out: `GET /v1/orders?closeout=open`.\n3. Save tips any number of times with `POST /v1/payments/:id/tip`; nothing is charged yet. A discount, comp or void that would leave a paid order below $0 is refused: refund first.\n4. `POST /v1/orders/:id/close-out` captures the cards for amount + surcharge + tip. Managers can `close-out-all`, and `settings.auto_close` can do it at the end of the business day or after N days.\n\n# Offline mode\n\nTerminals keep working without the server: seat tables, ring items, fire (the terminal prints), void with a manager PIN, and take cash and cards up to `settings.offline` limits. When the connection returns, the terminal replays its actions with `POST /v1/sync/offline`. Each op runs exactly once, original times are kept, nothing reprints, and problems (a declined card, a table seated twice) are reported rather than dropped.\n\n# Order math\n\nAll amounts are integer cents, rounded per line, half-up.\n\n```\nline gross      = (unit_price + modifiers_total) × quantity\nsubtotal        = Σ gross of non-comped lines\norder discounts → spread across lines by net amount (largest remainder)\nservice charge  = auto_gratuity.rate × (subtotal − discounts)   if guests ≥ min_party_size\ntax             = Σ per line: net (+ service share if taxable) × rate[tax_category]\ntotal           = subtotal − discounts + service_charge + tax\ncard surcharge  = rate × amount, added to card payments only\n```\n\nEvery component is allocated per check too, so split checks always add up to the order exactly."
  },
  "servers": [
    {
      "url": "http://localhost:4000",
      "description": "Local development"
    }
  ],
  "security": [
    {
      "bearer": []
    },
    {
      "apiKey": []
    }
  ],
  "tags": [
    {
      "name": "Authentication",
      "description": "Dashboard logins, terminal pairing and staff PIN sign-in."
    },
    {
      "name": "Staff & terminals",
      "description": "Staff, PINs, paired devices and API keys."
    },
    {
      "name": "Restaurant & settings",
      "description": "Restaurant profile, branding and every setting (tax, gratuity, surcharge, tips, business day, close-out, offline limits…)."
    },
    {
      "name": "Menu",
      "description": "Menus → sections → items → modifier groups → options (with nested groups). See the item and group schemas for min/max, free quantities, prefixes and defaults."
    },
    {
      "name": "Stock (86)",
      "description": "Mark items or single options out of stock. It applies everywhere at once: terminals, online store and delivery marketplaces."
    },
    {
      "name": "Floor plan",
      "description": "Areas (with their room shape and landmarks like the bar and kitchen) and tables, the live floor with status and seat times, joining tables and tonight-only Arrange moves."
    },
    {
      "name": "Printers",
      "description": "Kitchen, bar, expo and receipt printers, routing, and ticket history."
    },
    {
      "name": "Discounts",
      "description": "Preset discounts, scheduled happy hours and promo codes."
    },
    {
      "name": "Orders",
      "description": "Every kind of order: quick service, dine-in, tabs, takeout, online and delivery."
    },
    {
      "name": "Kitchen & coursing",
      "description": "Items start `pending`; firing sends them to their printers, grouped by printer and course."
    },
    {
      "name": "Checks & splitting",
      "description": "Split by item or evenly. Discounts, gratuity and tax are allocated so checks add up exactly."
    },
    {
      "name": "Payments & tips",
      "description": "Card, cash, card on file and other tenders, refunds, tips and close-out."
    },
    {
      "name": "Tabs & card on file",
      "description": "Open a tab, hold a card, pay with it at the end."
    },
    {
      "name": "Receipts",
      "description": "Email, text or print."
    },
    {
      "name": "Online ordering",
      "description": "The public, unauthenticated API behind the hosted online store."
    },
    {
      "name": "Delivery & marketplaces",
      "description": "DoorDash, Uber Eats and Grubhub order intake; DoorDash Drive and Uber Direct couriers; fulfillment."
    },
    {
      "name": "Reports",
      "description": "Sales, inventory, exceptions, shift reports and the activity log."
    },
    {
      "name": "Webhooks",
      "description": "Signed event delivery to your own server."
    },
    {
      "name": "Real-time",
      "description": "WebSocket stream that keeps every terminal in sync."
    },
    {
      "name": "Kitchen display",
      "description": "Tickets for the kitchen screen: what was sent and not bumped yet, by station, with ready check-offs, bump and recall."
    },
    {
      "name": "Reservations & waitlist",
      "description": "The host stand: book reservations (optionally holding a table), keep a waitlist with quoted times, text parties when their table is ready, and seat them (which opens their check). Part of table service."
    },
    {
      "name": "Kiosk",
      "description": "Self-order kiosks: a register guests order and pay on themselves. In kiosk mode the terminal token can only read the menu, create quick-service orders, change its own unsent items, pay by card and send receipts (`403 kiosk_mode` for anything else). Paid orders go to the kitchen. Leaving kiosk mode needs a manager PIN."
    },
    {
      "name": "Accounts & sign-up",
      "description": "Self-serve sign-up for merchants and distributors, merchant invites, and partner / platform portal logins."
    },
    {
      "name": "Billing",
      "description": "The merchant's plan: terminal seats (register and kitchen display), the table service add-on, invoices and the card on file. Purchases are web-only and must be confirmed at the quoted amount."
    },
    {
      "name": "Partner (white-label)",
      "description": "For distributors and their agents: merchants, pricing, invites, agents, team, and white-label branding."
    },
    {
      "name": "Platform admin",
      "description": "For SodiumPOS staff: approve distributors, set SodiumPOS prices, and test billing with a movable clock."
    },
    {
      "name": "Offline sync",
      "description": "Replay what a terminal did while it was offline."
    },
    {
      "name": "Demos",
      "description": "Private demo links. Each link gets its own copy of the demo data; requests carrying `X-Demo: <token>` run against that copy."
    },
    {
      "name": "System",
      "description": ""
    }
  ],
  "x-tagGroups": [
    {
      "name": "Access",
      "tags": [
        "Authentication",
        "Staff & terminals"
      ]
    },
    {
      "name": "Setup",
      "tags": [
        "Restaurant & settings",
        "Menu",
        "Stock (86)",
        "Floor plan",
        "Printers",
        "Discounts"
      ]
    },
    {
      "name": "Service",
      "tags": [
        "Orders",
        "Kitchen & coursing",
        "Kitchen display",
        "Checks & splitting",
        "Payments & tips",
        "Tabs & card on file",
        "Receipts",
        "Reservations & waitlist"
      ]
    },
    {
      "name": "Channels",
      "tags": [
        "Online ordering",
        "Kiosk",
        "Delivery & marketplaces"
      ]
    },
    {
      "name": "Data & events",
      "tags": [
        "Reports",
        "Webhooks",
        "Real-time"
      ]
    },
    {
      "name": "Platform",
      "tags": [
        "Accounts & sign-up",
        "Billing",
        "Partner (white-label)",
        "Platform admin",
        "Demos",
        "Offline sync",
        "System"
      ]
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "Health check",
        "description": "*Auth:* No authentication.",
        "operationId": "get_health",
        "security": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "time": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/stream": {
      "get": {
        "tags": [
          "Real-time"
        ],
        "summary": "Event stream (WebSocket)",
        "description": "Upgrade to a WebSocket. Every client of a restaurant receives the same events; see **Real-time stream** in the guides for the event list. Send `ping` to receive `{\"type\":\"pong\"}`. A missing or invalid token gets `401` before the upgrade; a token that stops working later closes the socket with code 4001.\n\n*Auth:* Any token, including a terminal token.",
        "operationId": "get_v1_stream",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": false,
            "description": "Any token",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "101": {
            "description": "OK"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/auth/login": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Dashboard login (local-auth servers)",
        "description": "Only on servers running with local sign-in (development, tests, demos). A server with hosted sign-in answers `403 hosted_login_required`: owners sign in on the hosted page from our apps, integrations use an API key, and devices pair with a pairing code. Check `GET /v1/auth/config`.\n\n*Auth:* No authentication.",
        "operationId": "post_v1_auth_login",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string"
                  },
                  "password": {
                    "type": "string"
                  }
                },
                "required": [
                  "email",
                  "password"
                ]
              },
              "example": {
                "email": "owner@demo.pos",
                "password": "demo1234"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string",
                      "example": "adm_…"
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "user": {
                      "$ref": "#/components/schemas/UserRef"
                    },
                    "restaurant_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/auth/terminals/pair": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Pair a device as a terminal",
        "description": "Proof that an owner or manager allows it, one of: `pairing_code` (from `POST /v1/terminals/pairing-codes`; single use, 10 minutes, wrong codes are throttled per IP), an owner's or manager's dashboard session in the `Authorization` header, or (local-auth servers only) their `email` + `password`. Store the returned terminal token on the device. Uses a free seat of the right type (`kitchen` mode = kitchen display, any other mode = register). Pairing never charges: with no free seat it fails with `402 seat_limit`. An unknown `mode` is a `400`. Each pairing holds its seat until unpaired with `DELETE /v1/terminals/:id`. When no seat is free, the `402` lists the devices holding them (`details.terminals`) so this device can take one over with `replace_terminal_id`.\n\n*Auth:* No authentication.",
        "operationId": "post_v1_auth_terminals_pair",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pairing_code": {
                    "type": "string",
                    "example": "K7QM-4XZP"
                  },
                  "email": {
                    "type": "string",
                    "description": "Local-auth servers only"
                  },
                  "password": {
                    "type": "string",
                    "description": "Local-auth servers only"
                  },
                  "name": {
                    "type": "string",
                    "example": "Front register"
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "full",
                      "quick",
                      "table",
                      "kitchen",
                      "kiosk"
                    ]
                  },
                  "replace_terminal_id": {
                    "type": "string",
                    "description": "Take over this terminal's seat (a reset or replaced device). Its old token stops working."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "terminal_token": {
                      "type": "string",
                      "example": "trm_…"
                    },
                    "terminal": {
                      "$ref": "#/components/schemas/Terminal"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          }
        }
      }
    },
    "/v1/terminals/pairing-codes": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Create a device pairing code",
        "description": "Owners, managers, API keys and partner keys (with `X-Restaurant-Id`). Enter the code on the device (`POST /v1/auth/terminals/pair` with `pairing_code`) within 10 minutes; it works once. This is how integrations pair devices: nobody types a password on the device.\n\n*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "post_v1_terminals_pairing_codes",
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "example": "K7QM-4XZP"
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/auth/config": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "summary": "How this server signs people in",
        "description": "`provider: local` = email + password endpoints. `provider: cognito` = hosted sign-in: the apps send the browser to `GET /v1/auth/oidc/authorize`. `merchant` describes the brand of the calling host (or of `origin`): each distributor with hosted apps has its own sign-in, so the same email is a separate login per brand.\n\n*Auth:* No authentication.",
        "operationId": "get_v1_auth_config",
        "security": [],
        "parameters": [
          {
            "name": "origin",
            "in": "query",
            "required": false,
            "description": "The app origin to describe (default: the request host)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "provider": {
                      "type": "string",
                      "enum": [
                        "local",
                        "cognito"
                      ]
                    },
                    "merchant": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "properties": {
                        "brand": {
                          "type": "object",
                          "properties": {
                            "app_name": {
                              "type": "string"
                            },
                            "primary": {
                              "type": "string"
                            },
                            "logo_url": {
                              "type": [
                                "string",
                                "null"
                              ]
                            }
                          }
                        },
                        "ready": {
                          "type": "boolean"
                        },
                        "self_signup": {
                          "type": "boolean"
                        }
                      }
                    },
                    "partner": {
                      "type": "object",
                      "properties": {
                        "ready": {
                          "type": "boolean"
                        }
                      }
                    },
                    "platform": {
                      "type": "object",
                      "properties": {
                        "ready": {
                          "type": "boolean"
                        }
                      }
                    }
                  },
                  "required": [
                    "provider"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/auth/oidc/authorize": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "summary": "Start a hosted sign-in (browser navigation)",
        "description": "Navigate the browser here (not `fetch`). Redirects to the hosted sign-in page of the right pool (authorization code + PKCE). Afterwards the browser comes back to `origin` + `return` with `auth_code` (or `auth_error`) added to the route's query. Generate a random secret, keep it in `sessionStorage`, and pass `binding` = base64url(SHA-256(secret)); you need the secret to collect the result. Errors: `hosted_apps_disabled` (API-only distributor), `sign_in_unavailable` (pool still being set up).\n\n*Auth:* No authentication.",
        "operationId": "get_v1_auth_oidc_authorize",
        "security": [],
        "parameters": [
          {
            "name": "audience",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "merchant",
                "partner",
                "platform"
              ]
            }
          },
          {
            "name": "origin",
            "in": "query",
            "required": false,
            "description": "The app's origin; must be an allowed one",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "return",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "example": "#/admin"
            }
          },
          {
            "name": "binding",
            "in": "query",
            "required": false,
            "description": "base64url(SHA-256(secret)), 43 characters",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "intent",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "login",
                "signup"
              ]
            }
          },
          {
            "name": "invite",
            "in": "query",
            "required": false,
            "description": "Merchant invite token: signs in to that merchant's brand as the invited email",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "login_hint",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "OK"
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/auth/oidc/callback": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "summary": "Hosted sign-in callback",
        "description": "Where the hosted page returns. Not called by apps.\n\n*Auth:* No authentication.",
        "operationId": "get_v1_auth_oidc_callback",
        "security": [],
        "responses": {
          "302": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/auth/oidc/session": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Collect a hosted sign-in",
        "description": "Send the `auth_code` from the return URL and the secret behind `binding`. The code works once, for 2 minutes. `signed_in` returns a dashboard (`adm_`) or portal (`acc_`) session. `choose`: the person is an owner or manager at several of this brand's merchants; ask again with `restaurant_id` (same code). `needs_signup`: nobody uses this login yet (self-serve sign-up or an invite); send `identity_ticket` with `POST /v1/signup/merchant`, `/v1/signup/distributor` or `/v1/invites/:token/accept` within 30 minutes. `403 no_account`: the login works but has no access here.\n\n*Auth:* No authentication.",
        "operationId": "post_v1_auth_oidc_session",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "secret": {
                    "type": "string"
                  },
                  "restaurant_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "code",
                  "secret"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "signed_in",
                        "choose",
                        "needs_signup"
                      ]
                    },
                    "kind": {
                      "type": "string",
                      "enum": [
                        "admin",
                        "partner",
                        "platform"
                      ]
                    },
                    "token": {
                      "type": "string"
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "user": {
                      "$ref": "#/components/schemas/UserRef"
                    },
                    "restaurant_id": {
                      "type": "string"
                    },
                    "account": {
                      "$ref": "#/components/schemas/Account"
                    },
                    "restaurants": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "restaurant_id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "role": {
                            "$ref": "#/components/schemas/Role"
                          },
                          "status": {
                            "$ref": "#/components/schemas/MerchantStatus"
                          }
                        }
                      }
                    },
                    "identity_ticket": {
                      "type": "string",
                      "example": "idt_…"
                    },
                    "email": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "status"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/auth/oidc/logout": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "summary": "Sign out of the hosted page (browser navigation)",
        "description": "After ending your own session (`POST /v1/auth/logout` or `/v1/accounts/logout`), navigate here so the hosted page forgets the person too; the browser then returns to `origin` + `return`.\n\n*Auth:* No authentication.",
        "operationId": "get_v1_auth_oidc_logout",
        "security": [],
        "parameters": [
          {
            "name": "audience",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "merchant",
                "partner",
                "platform"
              ]
            }
          },
          {
            "name": "origin",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "return",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/auth/oidc/logged-out": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "summary": "Hosted sign-out return",
        "description": "Where the hosted page returns after signing out. Not called by apps.\n\n*Auth:* No authentication.",
        "operationId": "get_v1_auth_oidc_logged_out",
        "security": [],
        "responses": {
          "302": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/terminal": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "summary": "Terminal bootstrap",
        "description": "Data for the PIN screen, plus what this account has paid for. Hide table service when `features.table_service` is false; show a notice when `account.operational` is false.\n\n*Auth:* Terminal token (`trm_…`).",
        "operationId": "get_v1_terminal",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "terminal": {
                      "$ref": "#/components/schemas/Terminal"
                    },
                    "restaurant": {
                      "$ref": "#/components/schemas/Restaurant"
                    },
                    "branding": {
                      "$ref": "#/components/schemas/Branding"
                    },
                    "auto_lock_seconds": {
                      "type": "integer"
                    },
                    "pin_auto_length": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "description": "Every staff PIN has this many digits, so PIN pads can submit on their own. null: lengths differ, tap ✓."
                    },
                    "features": {
                      "type": "object",
                      "properties": {
                        "table_service": {
                          "type": "boolean"
                        }
                      }
                    },
                    "account": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "$ref": "#/components/schemas/MerchantStatus"
                        },
                        "operational": {
                          "type": "boolean"
                        },
                        "suspend_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/auth/pin": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Staff PIN sign-in",
        "description": "Needs the terminal token itself (a staff session gets 401). `pin` is a string of 4-8 digits. Every PIN typed on a terminal (sign-in, verify-manager, `manager_pin`) counts toward one limit: after 8 wrong PINs the terminal gets `429` for 5 minutes.\n\n*Auth:* Terminal token (`trm_…`).",
        "operationId": "post_v1_auth_pin",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pin": {
                    "type": "string",
                    "pattern": "^\\d{4,8}$",
                    "example": "3333"
                  }
                },
                "required": [
                  "pin"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string",
                      "example": "stf_…"
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "user": {
                      "$ref": "#/components/schemas/UserRef"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          }
        }
      }
    },
    "/v1/auth/verify-manager": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Check a manager PIN",
        "description": "Throttled with the terminal's other PIN attempts (see PIN sign-in).\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_auth_verify_manager",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pin": {
                    "type": "string"
                  }
                },
                "required": [
                  "pin"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "manager": {
                      "$ref": "#/components/schemas/UserRef"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          }
        }
      }
    },
    "/v1/kiosk/enter": {
      "post": {
        "tags": [
          "Kiosk"
        ],
        "summary": "Turn this register into a self-order kiosk",
        "description": "Called with a staff session on the terminal: a manager, or anyone with a manager's PIN (`manager_pin`). Every staff session on the terminal ends, and from then on its terminal token acts as a kiosk. Kitchen displays can't be kiosks. `menu_ids` picks the menus guests see (default: every menu); the kiosk shows each during its hours, and refuses items from other menus (`403 kiosk_mode`). Change them later with `PATCH /v1/terminals/:id` (`kiosk_menus`).\n\n**Manager approval:** `kiosk` (see *Manager approval*). Retry with `manager_pin` after a `403 manager_required`.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_kiosk_enter",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "manager_pin": {
                    "type": "string"
                  },
                  "menu_ids": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "terminal": {
                      "$ref": "#/components/schemas/Terminal"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/kiosk/exit": {
      "post": {
        "tags": [
          "Kiosk"
        ],
        "summary": "Leave kiosk mode with a manager PIN",
        "description": "From the kiosk itself (its terminal token). Wrong PINs count toward the terminal's PIN limit (`429` after 8). Unpaid orders the kiosk left open are cancelled. Returns a staff session for that manager, so the terminal opens signed in.\n\n*Auth:* Terminal token (`trm_…`).",
        "operationId": "post_v1_kiosk_exit",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pin": {
                    "type": "string"
                  }
                },
                "required": [
                  "pin"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "terminal": {
                      "$ref": "#/components/schemas/Terminal"
                    },
                    "token": {
                      "type": "string",
                      "example": "stf_…"
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "user": {
                      "$ref": "#/components/schemas/UserRef"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          }
        }
      }
    },
    "/v1/kds": {
      "get": {
        "tags": [
          "Kitchen display"
        ],
        "summary": "Tickets for a station",
        "description": "Orders with sent items the kitchen hasn't bumped yet (oldest first), tickets bumped in the last hour (for recall), and all-day counts. `station` is an active kitchen or bar printer id (unknown → 404); `all` (default) is the expo view. Works with a kitchen display's terminal token (no one signed in) or any staff session.\n\n*Auth:* Any token, including a terminal token.",
        "operationId": "get_v1_kds",
        "parameters": [
          {
            "name": "station",
            "in": "query",
            "required": false,
            "description": "Printer id, or all",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "stations": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "role": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "station": {
                      "type": "string"
                    },
                    "tickets": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/KdsTicket"
                      }
                    },
                    "recent": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/KdsTicket"
                      }
                    },
                    "all_day": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "quantity": {
                            "type": "integer"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/kds/bump": {
      "post": {
        "tags": [
          "Kitchen display"
        ],
        "summary": "Bump a ticket",
        "description": "Clears the order's items from that station (or everywhere).\n\n*Auth:* Any token, including a terminal token.",
        "operationId": "post_v1_kds_bump",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "order_id": {
                    "type": "string"
                  },
                  "station": {
                    "type": "string"
                  }
                },
                "required": [
                  "order_id"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "bumped": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/kds/recall": {
      "post": {
        "tags": [
          "Kitchen display"
        ],
        "summary": "Recall a bumped ticket",
        "description": "Brings back a ticket bumped in the last hour.\n\n*Auth:* Any token, including a terminal token.",
        "operationId": "post_v1_kds_recall",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "order_id": {
                    "type": "string"
                  },
                  "station": {
                    "type": "string"
                  }
                },
                "required": [
                  "order_id"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "recalled": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/kds/items/{id}/ready": {
      "post": {
        "tags": [
          "Kitchen display"
        ],
        "summary": "Check an item off",
        "description": "Marks a sent item ready (or not). The ticket stays until it's bumped.\n\n*Auth:* Any token, including a terminal token.",
        "operationId": "post_v1_kds_items_id_ready",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ready": {
                    "type": "boolean",
                    "default": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "ready": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/uploads/images": {
      "post": {
        "tags": [
          "Menu"
        ],
        "summary": "Upload a photo",
        "description": "For item photos. Send a JPEG, PNG or WebP as a data URL (max 3 MB; the admin portal shrinks photos to 1200 px first). Returns a URL to set as the item's `image_url`. Files are named by their content and cached forever.\n\n*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "post_v1_uploads_images",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "data_url": {
                    "type": "string",
                    "example": "data:image/jpeg;base64,/9j/4AAQ…"
                  }
                },
                "required": [
                  "data_url"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string",
                      "example": "/uploads/rst_8fJ2kq/0f3a…c9.jpg"
                    },
                    "bytes": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/reservations": {
      "get": {
        "tags": [
          "Reservations & waitlist"
        ],
        "summary": "A day's reservations",
        "description": "Part of table service. `date` is a local date in the restaurant's timezone (default today).\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "get_v1_reservations",
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "example": "2026-11-14"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "date_start": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "date_end": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Reservation"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      },
      "post": {
        "tags": [
          "Reservations & waitlist"
        ],
        "summary": "Book a reservation",
        "description": "From the POS host stand, or the admin portal / API (e.g. phone bookings). A held table can't be double-booked for overlapping times (`409`).\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_reservations",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReservationInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Reservation"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/reservations/{id}": {
      "patch": {
        "tags": [
          "Reservations & waitlist"
        ],
        "summary": "Edit, or mark arrived / cancelled / no-show",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "patch_v1_reservations_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/ReservationInput"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "status": {
                        "type": "string",
                        "enum": [
                          "booked",
                          "arrived",
                          "cancelled",
                          "no_show"
                        ]
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Reservation"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/reservations/{id}/seat": {
      "post": {
        "tags": [
          "Reservations & waitlist"
        ],
        "summary": "Seat the party",
        "description": "Opens their dine-in check on the table (default: the one held for them). On a register terminal.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_reservations_id_seat",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "table_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reservation": {
                      "$ref": "#/components/schemas/Reservation"
                    },
                    "order": {
                      "$ref": "#/components/schemas/Order"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/waitlist": {
      "get": {
        "tags": [
          "Reservations & waitlist"
        ],
        "summary": "Parties waiting",
        "description": "Oldest first. `all=1` adds today's seated and gone.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "get_v1_waitlist",
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WaitlistEntry"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      },
      "post": {
        "tags": [
          "Reservations & waitlist"
        ],
        "summary": "Add a party to the waitlist",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_waitlist",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "phone": {
                    "type": "string"
                  },
                  "party_size": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "quoted_min": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 240,
                    "default": 15
                  },
                  "notes": {
                    "type": "string"
                  }
                },
                "required": [
                  "name",
                  "party_size"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WaitlistEntry"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          }
        }
      }
    },
    "/v1/waitlist/{id}": {
      "patch": {
        "tags": [
          "Reservations & waitlist"
        ],
        "summary": "Edit, or mark as left",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "patch_v1_waitlist_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "phone": {
                    "type": "string"
                  },
                  "party_size": {
                    "type": "integer"
                  },
                  "quoted_min": {
                    "type": "integer"
                  },
                  "notes": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "waiting",
                      "left"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WaitlistEntry"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/waitlist/{id}/notify": {
      "post": {
        "tags": [
          "Reservations & waitlist"
        ],
        "summary": "Text the party their table is ready",
        "description": "Needs a phone number. SMS goes to the mock outbox until a provider is connected.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_waitlist_id_notify",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WaitlistEntry"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/waitlist/{id}/seat": {
      "post": {
        "tags": [
          "Reservations & waitlist"
        ],
        "summary": "Seat the party",
        "description": "Opens their dine-in check on the table. On a register terminal.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_waitlist_id_seat",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "table_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "table_id"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "entry": {
                      "$ref": "#/components/schemas/WaitlistEntry"
                    },
                    "order": {
                      "$ref": "#/components/schemas/Order"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/auth/logout": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "End this session",
        "description": "*Auth:* Any token, including a terminal token.",
        "operationId": "post_v1_auth_logout",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/me": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "summary": "Who am I",
        "description": "Works with every token. A restaurant API key and a partner key both report `kind: \"api\"`; the partner key also has `partner_id` and needs no `X-Restaurant-Id` here. Portal sessions report `partner` or `platform` with an empty `restaurant_id`.\n\n*Auth:* Any token, including a terminal token.",
        "operationId": "get_v1_me",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "admin",
                        "staff",
                        "terminal",
                        "kiosk",
                        "api",
                        "partner",
                        "platform"
                      ]
                    },
                    "user": {
                      "oneOf": [
                        {
                          "$ref": "#/components/schemas/UserRef"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "restaurant_id": {
                      "type": "string"
                    },
                    "terminal_id": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "partner_id": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "is_manager": {
                      "type": "boolean"
                    },
                    "account_status": {
                      "oneOf": [
                        {
                          "$ref": "#/components/schemas/MerchantStatus"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "features": {
                      "type": "object",
                      "properties": {
                        "table_service": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/users": {
      "get": {
        "tags": [
          "Staff & terminals"
        ],
        "summary": "List staff",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "get_v1_users",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/User"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      },
      "post": {
        "tags": [
          "Staff & terminals"
        ],
        "summary": "Add a staff member",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "post_v1_users",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/users/{id}": {
      "patch": {
        "tags": [
          "Staff & terminals"
        ],
        "summary": "Update a staff member",
        "description": "Omit `pin`/`password` to keep them.\n\n*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "patch_v1_users_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      },
      "delete": {
        "tags": [
          "Staff & terminals"
        ],
        "summary": "Deactivate a staff member",
        "description": "Keeps their history and ends their sessions.\n\n*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "delete_v1_users_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/staff": {
      "get": {
        "tags": [
          "Staff & terminals"
        ],
        "summary": "Active staff (names and roles)",
        "description": "For transfer pickers.\n\n*Auth:* Any token, including a terminal token.",
        "operationId": "get_v1_staff",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "role": {
                            "$ref": "#/components/schemas/Role"
                          }
                        }
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/terminals": {
      "get": {
        "tags": [
          "Staff & terminals"
        ],
        "summary": "Paired terminals",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "get_v1_terminals",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Terminal"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/terminals/{id}": {
      "patch": {
        "tags": [
          "Staff & terminals"
        ],
        "summary": "Rename a terminal, change its mode or its kiosk menus",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "patch_v1_terminals_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "mode": {
                    "type": "string"
                  },
                  "kiosk_menus": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "minItems": 1,
                    "items": {
                      "type": "string"
                    },
                    "description": "Menus shown in kiosk mode; null = every menu"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Terminal"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "delete": {
        "tags": [
          "Staff & terminals"
        ],
        "summary": "Unpair a terminal",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "delete_v1_terminals_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/api-keys": {
      "get": {
        "tags": [
          "Staff & terminals"
        ],
        "summary": "List API keys",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "get_v1_api_keys",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ApiKey"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      },
      "post": {
        "tags": [
          "Staff & terminals"
        ],
        "summary": "Create an API key",
        "description": "The raw key is returned **once**.\n\n*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "post_v1_api_keys",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ApiKey"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "key": {
                          "type": "string",
                          "example": "pk_live_…"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/api-keys/{id}": {
      "delete": {
        "tags": [
          "Staff & terminals"
        ],
        "summary": "Revoke an API key",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "delete_v1_api_keys_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/restaurant": {
      "get": {
        "tags": [
          "Restaurant & settings"
        ],
        "summary": "Restaurant, branding and settings",
        "description": "*Auth:* Any token, including a terminal token.",
        "operationId": "get_v1_restaurant",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Restaurant"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      },
      "patch": {
        "tags": [
          "Restaurant & settings"
        ],
        "summary": "Update the restaurant or settings",
        "description": "`settings` is deep-merged, so send only what changes.\n\n*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "patch_v1_restaurant",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RestaurantPatch"
              },
              "example": {
                "settings": {
                  "card_surcharge": {
                    "enabled": true,
                    "rate_bps": 300
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Restaurant"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/business-day": {
      "get": {
        "tags": [
          "Restaurant & settings"
        ],
        "summary": "Current business day",
        "description": "*Auth:* Any token, including a terminal token.",
        "operationId": "get_v1_business_day",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "start": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "end": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "auto_close_cutoff": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/menu": {
      "get": {
        "tags": [
          "Menu"
        ],
        "summary": "The whole menu (normalized tree)",
        "description": "Menus → sections → item ids, plus items and modifier groups keyed by id. Cache it and re-fetch on `menu.updated`.\n\n*Auth:* Any token, including a terminal token.",
        "operationId": "get_v1_menu",
        "parameters": [
          {
            "name": "channel",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pos",
                "online",
                "marketplace"
              ]
            }
          },
          {
            "name": "include_inactive",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MenuTree"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/menus": {
      "get": {
        "tags": [
          "Menu"
        ],
        "summary": "List menus",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "get_v1_menus",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Menu"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      },
      "post": {
        "tags": [
          "Menu"
        ],
        "summary": "Create a menu",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "post_v1_menus",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MenuInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Menu"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/menus/{id}": {
      "get": {
        "tags": [
          "Menu"
        ],
        "summary": "Get a menu",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "get_v1_menus_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Menu"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "patch": {
        "tags": [
          "Menu"
        ],
        "summary": "Update a menu",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "patch_v1_menus_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MenuInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Menu"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "delete": {
        "tags": [
          "Menu"
        ],
        "summary": "Delete a menu",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "delete_v1_menus_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/menus/{id}/sections/order": {
      "post": {
        "tags": [
          "Menu"
        ],
        "summary": "Reorder sections",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "post_v1_menus_id_sections_order",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [
                  "ids"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/sections": {
      "get": {
        "tags": [
          "Menu"
        ],
        "summary": "List sections",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "get_v1_sections",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Section"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      },
      "post": {
        "tags": [
          "Menu"
        ],
        "summary": "Create a section",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "post_v1_sections",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SectionInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Section"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/sections/{id}": {
      "get": {
        "tags": [
          "Menu"
        ],
        "summary": "Get a section",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "get_v1_sections_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Section"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "patch": {
        "tags": [
          "Menu"
        ],
        "summary": "Update a section",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "patch_v1_sections_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SectionInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Section"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "delete": {
        "tags": [
          "Menu"
        ],
        "summary": "Delete a section",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "delete_v1_sections_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/sections/{id}/items/order": {
      "post": {
        "tags": [
          "Menu"
        ],
        "summary": "Reorder items in a section",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "post_v1_sections_id_items_order",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [
                  "ids"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/items": {
      "get": {
        "tags": [
          "Menu"
        ],
        "summary": "List items",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "get_v1_items",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Item"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      },
      "post": {
        "tags": [
          "Menu"
        ],
        "summary": "Create an item",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "post_v1_items",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ItemInput"
              },
              "example": {
                "name": "Classic Burger",
                "pos_name": "Burger",
                "description": "8oz, brioche",
                "price": 1700,
                "tax_category": "food",
                "default_course": 2,
                "section_ids": [
                  "sec_burgers"
                ],
                "printer_ids": [
                  "ptr_kitchen"
                ],
                "modifier_groups": [
                  {
                    "group_id": "mgr_temp"
                  },
                  {
                    "group_id": "mgr_toppings",
                    "max_override": 5
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Item"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/items/{id}": {
      "get": {
        "tags": [
          "Menu"
        ],
        "summary": "Get an item",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "get_v1_items_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Item"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "patch": {
        "tags": [
          "Menu"
        ],
        "summary": "Update an item",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "patch_v1_items_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ItemInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Item"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "delete": {
        "tags": [
          "Menu"
        ],
        "summary": "Delete an item",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "delete_v1_items_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/modifier-groups": {
      "get": {
        "tags": [
          "Menu"
        ],
        "summary": "List modifier groups",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "get_v1_modifier_groups",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ModifierGroup"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      },
      "post": {
        "tags": [
          "Menu"
        ],
        "summary": "Create a modifier group",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "post_v1_modifier_groups",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ModifierGroupInput"
              },
              "example": {
                "name": "Add a side",
                "display_name": "Make it a meal",
                "min_select": 0,
                "max_select": 1,
                "modifiers": [
                  {
                    "name": "Add side",
                    "price": 400,
                    "child_group_ids": [
                      "mgr_which_side"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModifierGroup"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/modifier-groups/{id}": {
      "get": {
        "tags": [
          "Menu"
        ],
        "summary": "Get a modifier group",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "get_v1_modifier_groups_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModifierGroup"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "patch": {
        "tags": [
          "Menu"
        ],
        "summary": "Update a modifier group",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "patch_v1_modifier_groups_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ModifierGroupInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModifierGroup"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "delete": {
        "tags": [
          "Menu"
        ],
        "summary": "Delete a modifier group",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "delete_v1_modifier_groups_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/items/{id}/stock": {
      "post": {
        "tags": [
          "Stock (86)"
        ],
        "summary": "86 an item, or set or adjust its count",
        "description": "Takes effect everywhere at once: every terminal, the online store and each enabled delivery marketplace. Tracked items count down when fired, auto-86 at zero and come back when restocked.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_items_id_stock",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "out_of_stock": {
                    "type": "boolean"
                  },
                  "stock_qty": {
                    "type": "integer"
                  },
                  "adjust": {
                    "type": "integer",
                    "description": "+/- relative"
                  },
                  "track": {
                    "type": "boolean",
                    "description": "`false` stops counting the item (clears its count)"
                  },
                  "reason": {
                    "type": "string",
                    "example": "restock"
                  }
                }
              },
              "example": {
                "out_of_stock": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Item"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/modifiers/{id}/stock": {
      "post": {
        "tags": [
          "Stock (86)"
        ],
        "summary": "86 a single option",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_modifiers_id_stock",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "out_of_stock": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "out_of_stock"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Modifier"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/floor": {
      "get": {
        "tags": [
          "Floor plan"
        ],
        "summary": "Live floor",
        "description": "Areas → tables (in natural order), each with its status, seat time and open orders. Floor orders are short summaries with `totals` (total, paid, balance); fetch the order for its items.\n\n*Auth:* Any token, including a terminal token.",
        "operationId": "get_v1_floor",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Floor"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/floor/areas": {
      "get": {
        "tags": [
          "Floor plan"
        ],
        "summary": "List areas",
        "description": "*Auth:* Any token, including a terminal token.",
        "operationId": "get_v1_floor_areas",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/FloorArea"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      },
      "post": {
        "tags": [
          "Floor plan"
        ],
        "summary": "Create a area",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "post_v1_floor_areas",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FloorAreaInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FloorArea"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/floor/areas/{id}": {
      "get": {
        "tags": [
          "Floor plan"
        ],
        "summary": "Get a area",
        "description": "*Auth:* Any token, including a terminal token.",
        "operationId": "get_v1_floor_areas_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FloorArea"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "patch": {
        "tags": [
          "Floor plan"
        ],
        "summary": "Update a area",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "patch_v1_floor_areas_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FloorAreaInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FloorArea"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "delete": {
        "tags": [
          "Floor plan"
        ],
        "summary": "Delete a area",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "delete_v1_floor_areas_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/floor/tables": {
      "get": {
        "tags": [
          "Floor plan"
        ],
        "summary": "List tables",
        "description": "*Auth:* Any token, including a terminal token.",
        "operationId": "get_v1_floor_tables",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Table"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      },
      "post": {
        "tags": [
          "Floor plan"
        ],
        "summary": "Create a table",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "post_v1_floor_tables",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TableInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Table"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/floor/tables/{id}": {
      "get": {
        "tags": [
          "Floor plan"
        ],
        "summary": "Get a table",
        "description": "*Auth:* Any token, including a terminal token.",
        "operationId": "get_v1_floor_tables_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Table"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "patch": {
        "tags": [
          "Floor plan"
        ],
        "summary": "Update a table",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "patch_v1_floor_tables_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TableInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Table"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "delete": {
        "tags": [
          "Floor plan"
        ],
        "summary": "Delete a table",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "delete_v1_floor_tables_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/floor/areas/{id}/layout": {
      "put": {
        "tags": [
          "Floor plan"
        ],
        "summary": "Save a whole area layout",
        "description": "Tables without `id` are created; tables left out are removed (refused if they have an open order). Also clears temporary Arrange moves in that area.\n\n*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "put_v1_floor_areas_id_layout",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tables": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/TableInput"
                    }
                  },
                  "name": {
                    "type": "string"
                  },
                  "width": {
                    "type": "integer",
                    "description": "300-4000"
                  },
                  "height": {
                    "type": "integer",
                    "description": "200-4000"
                  },
                  "outline": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "$ref": "#/components/schemas/RoomCorner"
                    },
                    "description": "3-64 corners. null = plain rectangle. Omit to leave unchanged."
                  },
                  "fixtures": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "kind": {
                          "type": "string"
                        },
                        "label": {
                          "type": "string"
                        },
                        "x": {
                          "type": "integer"
                        },
                        "y": {
                          "type": "integer"
                        },
                        "w": {
                          "type": "integer"
                        },
                        "h": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "kind"
                      ]
                    },
                    "description": "Replaces every fixture in the area. Omit to leave unchanged."
                  }
                },
                "required": [
                  "tables"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Floor"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/floor/tables/{id}/position": {
      "post": {
        "tags": [
          "Floor plan"
        ],
        "summary": "Arrange: move a table for tonight",
        "description": "Doesn't change the saved layout. Clamped to the area.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_floor_tables_id_position",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "x": {
                    "type": "integer"
                  },
                  "y": {
                    "type": "integer"
                  }
                },
                "required": [
                  "x",
                  "y"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Floor"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/floor/reset-positions": {
      "post": {
        "tags": [
          "Floor plan"
        ],
        "summary": "Arrange: reset to the saved layout",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_floor_reset_positions",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "area_id": {
                    "type": "string",
                    "description": "Omit for every area"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Floor"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/floor/tables/{id}/merge": {
      "post": {
        "tags": [
          "Floor plan"
        ],
        "summary": "Join tables",
        "description": "Joins table `:id` and its whole group to the other table's group (any size). Open orders combine onto the group's main table; refused if the dragged table has a payment.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_floor_tables_id_merge",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "into_table_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "into_table_id"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "root_table_id": {
                      "type": "string"
                    },
                    "label": {
                      "type": "string",
                      "example": "10 + 11 + 12"
                    },
                    "floor": {
                      "$ref": "#/components/schemas/Floor"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/floor/tables/{id}/unmerge": {
      "post": {
        "tags": [
          "Floor plan"
        ],
        "summary": "Separate joined tables",
        "description": "On a member: separates that table. On the main (root) table: releases the whole group.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_floor_tables_id_unmerge",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Floor"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/printers": {
      "get": {
        "tags": [
          "Printers"
        ],
        "summary": "List printers",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "get_v1_printers",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Printer"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      },
      "post": {
        "tags": [
          "Printers"
        ],
        "summary": "Create a printer",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "post_v1_printers",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Printer"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Printer"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/printers/{id}": {
      "get": {
        "tags": [
          "Printers"
        ],
        "summary": "Get a printer",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "get_v1_printers_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Printer"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "patch": {
        "tags": [
          "Printers"
        ],
        "summary": "Update a printer",
        "description": "Routing: item → its `printer_ids` → else `settings.printing.default_kitchen_printer_id` → else the first kitchen/expo printer.\n\n*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "patch_v1_printers_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Printer"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Printer"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "delete": {
        "tags": [
          "Printers"
        ],
        "summary": "Delete a printer",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "delete_v1_printers_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/printers/{id}/test": {
      "post": {
        "tags": [
          "Printers"
        ],
        "summary": "Print a test page",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "post_v1_printers_id_test",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrintJob"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/print-jobs": {
      "get": {
        "tags": [
          "Printers"
        ],
        "summary": "Recent tickets",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "get_v1_print_jobs",
        "parameters": [
          {
            "name": "printer_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "order_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PrintJob"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/discounts": {
      "get": {
        "tags": [
          "Discounts"
        ],
        "summary": "List discounts",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "get_v1_discounts",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Discount"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      },
      "post": {
        "tags": [
          "Discounts"
        ],
        "summary": "Create a discount",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "post_v1_discounts",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Discount"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Discount"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/discounts/{id}": {
      "get": {
        "tags": [
          "Discounts"
        ],
        "summary": "Get a discount",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "get_v1_discounts_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Discount"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "patch": {
        "tags": [
          "Discounts"
        ],
        "summary": "Update a discount",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "patch_v1_discounts_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Discount"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Discount"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "delete": {
        "tags": [
          "Discounts"
        ],
        "summary": "Delete a discount",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "delete_v1_discounts_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/orders": {
      "get": {
        "tags": [
          "Orders"
        ],
        "summary": "List and search orders",
        "description": "Newest first (by close time for closed orders). When there are more, pass `next_cursor` back as `before`. To jump to a date, pass `before=<ISO time>|`.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "get_v1_orders",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "closed",
                "voided"
              ]
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/OrderType"
            }
          },
          {
            "name": "table_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "server_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "source",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fulfillment",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "active"
              ]
            }
          },
          {
            "name": "closeout",
            "in": "query",
            "required": false,
            "description": "Paid orders by close-out state",
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "closed",
                "all"
              ]
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Check #, table, tab, guest name/phone, server",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 500
            }
          },
          {
            "name": "before",
            "in": "query",
            "required": false,
            "description": "Cursor from `next_cursor`",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "count",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          },
          {
            "name": "full",
            "in": "query",
            "required": false,
            "description": "Complete order objects instead of summaries",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/OrderSummary"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "total": {
                      "type": "integer",
                      "description": "With `count=1`"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      },
      "post": {
        "tags": [
          "Orders"
        ],
        "summary": "Create an order",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_orders",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrderInput"
              },
              "example": {
                "type": "dine_in",
                "table_id": "tbl_8",
                "guests": 4,
                "items": [
                  {
                    "item_id": "itm_burger",
                    "modifiers": [
                      {
                        "group_id": "mgr_temp",
                        "modifier_id": "mod_medium_rare"
                      },
                      {
                        "group_id": "mgr_toppings",
                        "modifier_id": "mod_bacon",
                        "prefix": "extra"
                      }
                    ],
                    "seat": 2,
                    "notes": "no sesame"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/orders/{id}": {
      "get": {
        "tags": [
          "Orders"
        ],
        "summary": "Get an order",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "get_v1_orders_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "patch": {
        "tags": [
          "Orders"
        ],
        "summary": "Update an order",
        "description": "Guests, notes, tab name, customer, move tables, transfer server, tax exemption, waive auto gratuity.\n\n**Manager approval:** `tax_exempt (when setting tax_exempt)` (see *Manager approval*). Retry with `manager_pin` after a `403 manager_required`.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "patch_v1_orders_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrderPatch"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/orders/{id}/items": {
      "post": {
        "tags": [
          "Orders"
        ],
        "summary": "Add items",
        "description": "Every modifier rule is checked (required groups, min/max, nested groups, 86'd options, tracked stock). A `400` names the group to fix.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_orders_id_items",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/LineInput"
                    }
                  },
                  "fire": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "order": {
                      "$ref": "#/components/schemas/Order"
                    },
                    "created_item_ids": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/orders/{id}/items/{itemId}": {
      "patch": {
        "tags": [
          "Orders"
        ],
        "summary": "Edit an item",
        "description": "`quantity`, `modifiers`, `course` only while pending; `notes`, `seat`, `tax_exempt` any time.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "patch_v1_orders_id_items_itemId",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "itemId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "quantity": {
                    "type": "integer"
                  },
                  "modifiers": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ModifierSelection"
                    }
                  },
                  "course": {
                    "type": "integer"
                  },
                  "notes": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "seat": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "tax_exempt": {
                    "type": "boolean"
                  },
                  "manager_pin": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      },
      "delete": {
        "tags": [
          "Orders"
        ],
        "summary": "Remove an unsent item",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "delete_v1_orders_id_items_itemId",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "itemId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/orders/{id}/items/{itemId}/void": {
      "post": {
        "tags": [
          "Orders"
        ],
        "summary": "Void an item",
        "description": "Pending items are simply removed. Sent items print a **VOID** ticket to the same printers.\n\n**Manager approval:** `void_fired` (see *Manager approval*). Retry with `manager_pin` after a `403 manager_required`.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_orders_id_items_itemId_void",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "itemId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string"
                  },
                  "manager_pin": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/orders/{id}/items/{itemId}/comp": {
      "post": {
        "tags": [
          "Orders"
        ],
        "summary": "Comp an item",
        "description": "Still fires; charged $0 and reported as a comp.\n\n**Manager approval:** `comp` (see *Manager approval*). Retry with `manager_pin` after a `403 manager_required`.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_orders_id_items_itemId_comp",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "itemId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "comp": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string"
                  },
                  "manager_pin": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/orders/{id}/discounts": {
      "post": {
        "tags": [
          "Orders"
        ],
        "summary": "Apply a discount or promo",
        "description": "**Manager approval:** `discount (custom discounts and those marked requires_manager)` (see *Manager approval*). Retry with `manager_pin` after a `403 manager_required`.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_orders_id_discounts",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "discount_id": {
                    "type": "string"
                  },
                  "code": {
                    "type": "string"
                  },
                  "order_item_id": {
                    "type": "string"
                  },
                  "custom": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "kind": {
                        "type": "string",
                        "enum": [
                          "percent",
                          "amount"
                        ]
                      },
                      "value": {
                        "type": "number"
                      }
                    }
                  },
                  "manager_pin": {
                    "type": "string"
                  }
                }
              },
              "example": {
                "code": "WELCOME10"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/orders/{id}/discounts/{discountId}": {
      "delete": {
        "tags": [
          "Orders"
        ],
        "summary": "Remove a discount",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "delete_v1_orders_id_discounts_discountId",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "discountId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/orders/{id}/close": {
      "post": {
        "tags": [
          "Orders"
        ],
        "summary": "Close a $0 order",
        "description": "For fully comped or discounted orders.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_orders_id_close",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/orders/{id}/reopen": {
      "post": {
        "tags": [
          "Orders"
        ],
        "summary": "Reopen a closed order",
        "description": "**Manager approval:** `reopen` (see *Manager approval*). Retry with `manager_pin` after a `403 manager_required`.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_orders_id_reopen",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "manager_pin": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/orders/{id}/void": {
      "post": {
        "tags": [
          "Orders"
        ],
        "summary": "Void an unpaid order",
        "description": "**Manager approval:** `void_fired (if anything was sent)` (see *Manager approval*). Retry with `manager_pin` after a `403 manager_required`.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_orders_id_void",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string"
                  },
                  "manager_pin": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/orders/{id}/lock": {
      "post": {
        "tags": [
          "Orders"
        ],
        "summary": "Mark the order as open on this terminal",
        "description": "Re-send every ~60 s while open; locks go stale after 3 minutes. With strict table locking, others get `423` until released.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_orders_id_lock",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "force": {
                    "type": "boolean",
                    "description": "Managers: take over"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "order": {
                      "$ref": "#/components/schemas/Order"
                    },
                    "previous_holder": {
                      "oneOf": [
                        {
                          "$ref": "#/components/schemas/UserRef"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "423": {
            "$ref": "#/components/responses/E423"
          }
        }
      }
    },
    "/v1/orders/{id}/unlock": {
      "post": {
        "tags": [
          "Orders"
        ],
        "summary": "Release the order",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_orders_id_unlock",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/tabs": {
      "get": {
        "tags": [
          "Tabs & card on file"
        ],
        "summary": "Open tabs",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "get_v1_tabs",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/OrderSummary"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/orders/{id}/fire": {
      "post": {
        "tags": [
          "Kitchen & coursing"
        ],
        "summary": "Fire items to the kitchen",
        "description": "One ticket per printer, split by course, with seats, modifiers (NO/LIGHT/EXTRA), notes and comp markers. Omit `item_ids` to fire everything pending.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_orders_id_fire",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "item_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "order": {
                      "$ref": "#/components/schemas/Order"
                    },
                    "print_jobs": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PrintJob"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/orders/{id}/checks/split-items": {
      "post": {
        "tags": [
          "Checks & splitting"
        ],
        "summary": "Split by item",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_orders_id_checks_split_items",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "item_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [
                  "item_ids"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "order": {
                      "$ref": "#/components/schemas/Order"
                    },
                    "check_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/orders/{id}/checks/split-even": {
      "post": {
        "tags": [
          "Checks & splitting"
        ],
        "summary": "Split evenly",
        "description": "The check is paid in N equal shares; the last absorbs rounding. `ways: 1` undoes it.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_orders_id_checks_split_even",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "check_id": {
                    "type": "string"
                  },
                  "ways": {
                    "type": "integer",
                    "minimum": 1
                  }
                },
                "required": [
                  "ways"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/orders/{id}/checks/{checkId}/items": {
      "post": {
        "tags": [
          "Checks & splitting"
        ],
        "summary": "Move items to a check",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_orders_id_checks_checkId_items",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "checkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "item_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [
                  "item_ids"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/orders/{id}/checks/merge": {
      "post": {
        "tags": [
          "Checks & splitting"
        ],
        "summary": "Merge checks back into one",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_orders_id_checks_merge",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/orders/{id}/payments": {
      "post": {
        "tags": [
          "Payments & tips"
        ],
        "summary": "Take a payment",
        "description": "`amount` is applied to the bill; `tip` and any card surcharge go on top. Cards are **authorized** and captured at close-out. When every check is paid, the order closes (and anything unsent fires). Quick-service orders need `customer.name` first (`400 name_required`).\n\nPayments on one order are processed one at a time: two terminals paying the same balance at once can't both charge it (the second gets `409`). Unknown `check_id` → `404`; nothing left to pay → `409`.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_orders_id_payments",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PayInput"
              },
              "example": {
                "method": "card",
                "tip": 500,
                "source": {
                  "type": "card_present"
                },
                "idempotency_key": "chk_1-1731000000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "order": {
                      "$ref": "#/components/schemas/Order"
                    },
                    "payment_id": {
                      "type": "string"
                    },
                    "change_due": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "duplicate": {
                      "type": "boolean",
                      "description": "true when an idempotency_key retry returned the original payment"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/payments/{id}/refund": {
      "post": {
        "tags": [
          "Payments & tips"
        ],
        "summary": "Refund a payment",
        "description": "Partial refunds allowed; `amount` defaults to everything left on the payment. `reason` is required. A fully refunded payment gets `409`.\n\n**Manager approval:** `refund` (see *Manager approval*). Retry with `manager_pin` after a `403 manager_required`.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_payments_id_refund",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "amount": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "reason": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "manager_pin": {
                    "type": "string"
                  }
                },
                "required": [
                  "reason"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "order": {
                      "$ref": "#/components/schemas/Order"
                    },
                    "refund_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/payments/{id}/tip": {
      "post": {
        "tags": [
          "Payments & tips"
        ],
        "summary": "Save or adjust a tip",
        "description": "Before close-out this only saves the tip (nothing is charged yet). After close-out it's a tip adjust. Whole cents, up to 3× the payment amount or $100, whichever is more. Allowed after a partial refund as long as the payment still covers what was refunded.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_payments_id_tip",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tip": {
                    "type": "integer",
                    "minimum": 0
                  }
                },
                "required": [
                  "tip"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/orders/{id}/close-out": {
      "post": {
        "tags": [
          "Payments & tips"
        ],
        "summary": "Close out an order",
        "description": "Sets any tips and captures the order's authorized cards for amount + surcharge + tip.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_orders_id_close_out",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tips": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "payment_id": {
                          "type": "string"
                        },
                        "tip": {
                          "type": "integer",
                          "description": "Amount in cents"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/orders/close-out-all": {
      "post": {
        "tags": [
          "Payments & tips"
        ],
        "summary": "Close out everything still open",
        "description": "With or without tips. **Owners and managers only.**\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_orders_close_out_all",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "closed": {
                      "type": "integer"
                    },
                    "failed": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "order_id": {
                            "type": "string"
                          },
                          "error": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/orders/{id}/card-on-file": {
      "post": {
        "tags": [
          "Tabs & card on file"
        ],
        "summary": "Put a card on file",
        "description": "Tokenizes the card and places a pre-auth hold (`settings.tabs.preauth_amount`). The token never leaves the server.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_orders_id_card_on_file",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "source": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "card_present",
                          "token"
                        ]
                      },
                      "token": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          }
        }
      },
      "delete": {
        "tags": [
          "Tabs & card on file"
        ],
        "summary": "Release the hold and remove the card",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "delete_v1_orders_id_card_on_file",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/orders/{id}/receipt": {
      "post": {
        "tags": [
          "Receipts"
        ],
        "summary": "Email, text or print a receipt",
        "description": "Prints the bill for open orders, the receipt for closed ones. Scope: `payment_id` = that guest's receipt (their share of an even split, or their check); `check_id` = one check; neither = the whole order, and printing a split order then prints one ticket per check. Email/SMS go to a mock outbox until a provider is connected.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_orders_id_receipt",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "channel": {
                    "type": "string",
                    "enum": [
                      "email",
                      "sms",
                      "print"
                    ]
                  },
                  "to": {
                    "type": "string"
                  },
                  "check_id": {
                    "type": "string"
                  },
                  "payment_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "channel"
                ]
              },
              "example": {
                "channel": "print",
                "payment_id": "pay_8fJ2kq"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "print_job_id": {
                      "type": "string"
                    },
                    "print_job_ids": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "notification_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/notifications": {
      "get": {
        "tags": [
          "Receipts"
        ],
        "summary": "Mock email/SMS outbox",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "get_v1_notifications",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "channel": {
                            "type": "string"
                          },
                          "to": {
                            "type": "string"
                          },
                          "subject": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Email only"
                          },
                          "body": {
                            "type": "string"
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/public/{slug}": {
      "get": {
        "tags": [
          "Online ordering"
        ],
        "summary": "Store info",
        "description": "*Auth:* No authentication.",
        "operationId": "get_v1_public_slug",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "address": {
                      "$ref": "#/components/schemas/Address"
                    },
                    "branding": {
                      "$ref": "#/components/schemas/Branding"
                    },
                    "online": {
                      "type": "object"
                    },
                    "tips": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/public/{slug}/menu": {
      "get": {
        "tags": [
          "Online ordering"
        ],
        "summary": "Online menu",
        "description": "Online channel only, with live `out_of_stock`.\n\n*Auth:* No authentication.",
        "operationId": "get_v1_public_slug_menu",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MenuTree"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/public/{slug}/quote": {
      "post": {
        "tags": [
          "Online ordering"
        ],
        "summary": "Price a cart",
        "description": "*Auth:* No authentication.",
        "operationId": "post_v1_public_slug_quote",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/LineInput"
                    }
                  },
                  "promo_code": {
                    "type": "string"
                  }
                },
                "required": [
                  "items"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "totals": {
                      "$ref": "#/components/schemas/Totals"
                    },
                    "out_of_stock": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "promo": {
                      "type": [
                        "object",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          }
        }
      }
    },
    "/v1/public/{slug}/orders": {
      "post": {
        "tags": [
          "Online ordering"
        ],
        "summary": "Place and pay an order",
        "description": "Validated like a POS order (86'd items are rejected) and paid. Fires right away with `accept_automatically`, prints a bag ticket labeled `ONLINE ORDER - <name>`, and requests a courier for delivery.\n\n*Auth:* No authentication.",
        "operationId": "post_v1_public_slug_orders",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicOrderInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Also the access token for the status page"
                    },
                    "number": {
                      "type": "integer"
                    },
                    "status": {
                      "type": "string"
                    },
                    "totals": {
                      "$ref": "#/components/schemas/Totals"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          }
        }
      }
    },
    "/v1/public/{slug}/orders/{id}": {
      "get": {
        "tags": [
          "Online ordering"
        ],
        "summary": "Order status page data",
        "description": "*Auth:* No authentication.",
        "operationId": "get_v1_public_slug_orders_id",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/webhooks/marketplace/{platform}/{restaurantId}": {
      "post": {
        "tags": [
          "Delivery & marketplaces"
        ],
        "summary": "Inbound marketplace order",
        "description": "Accepts DoorDash / Uber Eats / Grubhub order payloads. Items match by id or `sku`. Recorded as paid, fired and printed with the platform banner. Duplicates are ignored. If a `webhook_secret` is configured, send `X-Webhook-Secret` (else `401`).\n\nDoorDash and Grubhub: `{ id, consumer: { first_name, last_name, phone }, is_pickup, delivery_instructions, categories: [{ items: [{ merchant_supplied_id, name, quantity, price, special_instructions, options: [{ name, price, extra_name }] }] }], subtotal, tax }`. Uber Eats: `{ id, eater: { first_name, last_initial, phone }, type: \"DELIVERY_BY_UBER\" | \"PICK_UP\", special_instructions, cart: { items: [{ external_data, title, quantity, price: { unit_price: { amount } }, special_instructions, selected_modifier_groups: [{ title, selected_items: [{ title, price: { unit_price: { amount } } }] }] }] } }`. `merchant_supplied_id` / `external_data` is our item id or `sku`; prices are cents.\n\n*Auth:* No authentication.",
        "operationId": "post_v1_webhooks_marketplace_platform_restaurantId",
        "security": [],
        "parameters": [
          {
            "name": "platform",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "restaurantId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/integrations/{platform}/simulate-order": {
      "post": {
        "tags": [
          "Delivery & marketplaces"
        ],
        "summary": "Simulate a marketplace order",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_integrations_platform_simulate_order",
        "parameters": [
          {
            "name": "platform",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/integrations/{platform}/sync-menu": {
      "post": {
        "tags": [
          "Delivery & marketplaces"
        ],
        "summary": "Push the menu to a marketplace",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "post_v1_integrations_platform_sync_menu",
        "parameters": [
          {
            "name": "platform",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "items": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/integrations": {
      "get": {
        "tags": [
          "Delivery & marketplaces"
        ],
        "summary": "Integration catalog",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "get_v1_integrations",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Integration"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/integrations/{kind}/{provider}": {
      "put": {
        "tags": [
          "Delivery & marketplaces"
        ],
        "summary": "Enable or configure an integration",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "put_v1_integrations_kind_provider",
        "parameters": [
          {
            "name": "kind",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "provider",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  },
                  "config": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Integration"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/integrations/log": {
      "get": {
        "tags": [
          "Delivery & marketplaces"
        ],
        "summary": "Outbound integration log",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "get_v1_integrations_log",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/orders/{id}/delivery/quotes": {
      "get": {
        "tags": [
          "Delivery & marketplaces"
        ],
        "summary": "Courier quotes",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "get_v1_orders_id_delivery_quotes",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "provider": {
                            "type": "string"
                          },
                          "fee": {
                            "type": "integer",
                            "description": "Amount in cents"
                          },
                          "eta_minutes": {
                            "type": "integer"
                          }
                        }
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/orders/{id}/delivery": {
      "post": {
        "tags": [
          "Delivery & marketplaces"
        ],
        "summary": "Request a courier",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_orders_id_delivery",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "provider": {
                    "type": "string",
                    "enum": [
                      "doordash_drive",
                      "uber_direct",
                      "mock_courier"
                    ]
                  }
                },
                "required": [
                  "provider"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      },
      "delete": {
        "tags": [
          "Delivery & marketplaces"
        ],
        "summary": "Cancel the courier",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "delete_v1_orders_id_delivery",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/orders/{id}/fulfillment": {
      "post": {
        "tags": [
          "Delivery & marketplaces"
        ],
        "summary": "Advance fulfillment",
        "description": "Accepting a `received` order fires it.\n\n*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "post_v1_orders_id_fulfillment",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "accepted",
                      "ready",
                      "picked_up",
                      "completed",
                      "cancelled"
                    ]
                  }
                },
                "required": [
                  "status"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/reports/sales": {
      "get": {
        "tags": [
          "Reports"
        ],
        "summary": "Sales report",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "get_v1_reports_sales",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Default: start of today (restaurant timezone)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Max range 400 days",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "csv"
              ]
            }
          },
          {
            "name": "breakdown",
            "in": "query",
            "required": false,
            "description": "With format=csv",
            "schema": {
              "type": "string",
              "example": "by_item"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SalesReport"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/reports/inventory": {
      "get": {
        "tags": [
          "Reports"
        ],
        "summary": "Inventory report",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "get_v1_reports_inventory",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Default: start of today (restaurant timezone)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Max range 400 days",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/reports/exceptions": {
      "get": {
        "tags": [
          "Reports"
        ],
        "summary": "Voids, comps, discounts, refunds, reopens, tax exemptions",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "get_v1_reports_exceptions",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Default: start of today (restaurant timezone)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Max range 400 days",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/reports/my-shift": {
      "get": {
        "tags": [
          "Reports"
        ],
        "summary": "Signed-in staff member's shift",
        "description": "*Auth:* A staff session (`stf_…`): a PIN sign-in on a paired register. Dashboard sessions and API keys can read these resources but get `403 terminal_required` on anything that takes an order or payment.",
        "operationId": "get_v1_reports_my_shift",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Default: start of today (restaurant timezone)",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Max range 400 days",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/audit-log": {
      "get": {
        "tags": [
          "Reports"
        ],
        "summary": "Activity log",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "get_v1_audit_log",
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "example": "item.void"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AuditEntry"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/webhooks": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "List webhooks",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "get_v1_webhooks",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Webhook"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      },
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Create a webhook",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "post_v1_webhooks",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Webhook"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/webhooks/{id}": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Get a webhook",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "get_v1_webhooks_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Webhook"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "patch": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Update a webhook",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "patch_v1_webhooks_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Webhook"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "delete": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Delete a webhook",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "delete_v1_webhooks_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/webhooks-events": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Subscribable events",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "get_v1_webhooks_events",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/webhooks/{id}/deliveries": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Recent deliveries",
        "description": "The last 30 days, newest first. Failed deliveries are retried after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h, then marked `failed`.\n\n*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "get_v1_webhooks_id_deliveries",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WebhookDelivery"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/webhook-deliveries/{id}/retry": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Send a delivery again now",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "post_v1_webhook_deliveries_id_retry",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDelivery"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/accounts/login": {
      "post": {
        "tags": [
          "Accounts & sign-up"
        ],
        "summary": "Partner or platform portal login (local-auth servers)",
        "description": "Hosted-sign-in servers answer `403 hosted_login_required`; the portals use `GET /v1/auth/oidc/authorize` with `audience` `partner` or `platform`.\n\n*Auth:* No authentication.",
        "operationId": "post_v1_accounts_login",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string"
                  },
                  "password": {
                    "type": "string"
                  }
                },
                "required": [
                  "email",
                  "password"
                ]
              },
              "example": {
                "email": "dist@demo.pos",
                "password": "demo1234"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string",
                      "example": "acc_…"
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "account": {
                      "$ref": "#/components/schemas/Account"
                    },
                    "kind": {
                      "type": "string",
                      "enum": [
                        "partner",
                        "platform"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          }
        }
      }
    },
    "/v1/accounts/logout": {
      "post": {
        "tags": [
          "Accounts & sign-up"
        ],
        "summary": "End a portal session",
        "description": "*Auth:* Any token, including a terminal token.",
        "operationId": "post_v1_accounts_logout",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/accounts/me": {
      "get": {
        "tags": [
          "Accounts & sign-up"
        ],
        "summary": "Who am I (portal)",
        "description": "*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "get_v1_accounts_me",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "account": {
                      "$ref": "#/components/schemas/Account"
                    },
                    "kind": {
                      "type": "string"
                    },
                    "partner": {
                      "oneOf": [
                        {
                          "$ref": "#/components/schemas/Partner"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/account-invites/{token}": {
      "get": {
        "tags": [
          "Accounts & sign-up"
        ],
        "summary": "Look up a portal invite",
        "description": "*Auth:* No authentication.",
        "operationId": "get_v1_account_invites_token",
        "security": [],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "account": {
                      "$ref": "#/components/schemas/Account"
                    },
                    "partner": {
                      "oneOf": [
                        {
                          "$ref": "#/components/schemas/Partner"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/account-invites/{token}/accept": {
      "post": {
        "tags": [
          "Accounts & sign-up"
        ],
        "summary": "Accept a portal invite (set a password; local-auth servers)",
        "description": "With hosted sign-in the invitee gets an emailed temporary password instead, signs in on the hosted page and is matched to the invite by email; this endpoint answers `403 hosted_login_required`.\n\n*Auth:* No authentication.",
        "operationId": "post_v1_account_invites_token_accept",
        "security": [],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "password": {
                    "type": "string"
                  }
                },
                "required": [
                  "password"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string"
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "account": {
                      "$ref": "#/components/schemas/Account"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/signup/distributor": {
      "post": {
        "tags": [
          "Accounts & sign-up"
        ],
        "summary": "Distributor sign-up",
        "description": "The distributor can sign in right away but can only add merchants once SodiumPOS approves it. With hosted sign-in, send `identity_ticket` (from a partner sign-up, see `POST /v1/auth/oidc/session`) instead of `email` and `password`.\n\n*Auth:* No authentication.",
        "operationId": "post_v1_signup_distributor",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "company": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string"
                  },
                  "password": {
                    "type": "string"
                  },
                  "identity_ticket": {
                    "type": "string"
                  },
                  "phone": {
                    "type": "string"
                  }
                },
                "required": [
                  "company",
                  "name"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string"
                    },
                    "partner": {
                      "$ref": "#/components/schemas/Partner"
                    },
                    "account": {
                      "$ref": "#/components/schemas/Account"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/signup/merchant": {
      "post": {
        "tags": [
          "Accounts & sign-up"
        ],
        "summary": "Merchant self-serve sign-up",
        "description": "Creates the merchant under SodiumPOS directly (the house distributor), in `onboarding`. Returns a dashboard session; the owner then activates with `POST /v1/billing/activate`. With hosted sign-in, send `identity_ticket` (from a sign-up on the SodiumPOS merchant sign-in) instead of `email` and `password`.\n\n*Auth:* No authentication.",
        "operationId": "post_v1_signup_merchant",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "business_name": {
                    "type": "string"
                  },
                  "owner_name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string"
                  },
                  "password": {
                    "type": "string"
                  },
                  "identity_ticket": {
                    "type": "string"
                  },
                  "pin": {
                    "type": "string"
                  },
                  "phone": {
                    "type": "string"
                  },
                  "timezone": {
                    "type": "string"
                  },
                  "address": {
                    "$ref": "#/components/schemas/Address"
                  }
                },
                "required": [
                  "business_name",
                  "owner_name",
                  "pin"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string",
                      "example": "adm_…"
                    },
                    "restaurant_id": {
                      "type": "string"
                    },
                    "user": {
                      "$ref": "#/components/schemas/UserRef"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/signup/prices": {
      "get": {
        "tags": [
          "Accounts & sign-up"
        ],
        "summary": "Self-serve prices",
        "description": "*Auth:* No authentication.",
        "operationId": "get_v1_signup_prices",
        "security": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "unit": {
                      "$ref": "#/components/schemas/Prices"
                    },
                    "fees": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Fee"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/invites/{token}": {
      "get": {
        "tags": [
          "Accounts & sign-up"
        ],
        "summary": "Look up a merchant invite",
        "description": "What the merchant sees before accepting, including the price sheet the distributor set (read-only).\n\n*Auth:* No authentication.",
        "operationId": "get_v1_invites_token",
        "security": [],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "email": {
                      "type": "string"
                    },
                    "partner": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        }
                      }
                    },
                    "merchant": {
                      "type": "object"
                    },
                    "pricing": {
                      "type": "object",
                      "properties": {
                        "unit": {
                          "$ref": "#/components/schemas/Prices"
                        },
                        "fees": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Fee"
                          }
                        }
                      }
                    },
                    "branding": {
                      "$ref": "#/components/schemas/Branding"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/invites/{token}/accept": {
      "post": {
        "tags": [
          "Accounts & sign-up"
        ],
        "summary": "Accept a merchant invite",
        "description": "Creates the owner login. The merchant can fill in details the distributor left blank, never the pricing. Moves the merchant to `onboarding`. With hosted sign-in, first sign in with `GET /v1/auth/oidc/authorize?audience=merchant&invite=<token>` (as the invited email, in the distributor's brand) and send the `identity_ticket` instead of `password`; another email is `403 invite_email_mismatch`.\n\n*Auth:* No authentication.",
        "operationId": "post_v1_invites_token_accept",
        "security": [],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "password": {
                    "type": "string"
                  },
                  "identity_ticket": {
                    "type": "string"
                  },
                  "pin": {
                    "type": "string"
                  },
                  "legal_name": {
                    "type": "string"
                  },
                  "address": {
                    "$ref": "#/components/schemas/Address"
                  }
                },
                "required": [
                  "name",
                  "pin"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string",
                      "example": "adm_…"
                    },
                    "restaurant_id": {
                      "type": "string"
                    },
                    "user": {
                      "$ref": "#/components/schemas/UserRef"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/billing": {
      "get": {
        "tags": [
          "Billing"
        ],
        "summary": "Plan, seats and balance",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "get_v1_billing",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Billing"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/billing/invoices": {
      "get": {
        "tags": [
          "Billing"
        ],
        "summary": "Invoices",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "get_v1_billing_invoices",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Invoice"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/billing/invoices/{id}": {
      "get": {
        "tags": [
          "Billing"
        ],
        "summary": "An invoice",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "get_v1_billing_invoices_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invoice"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/billing/activation-quote": {
      "post": {
        "tags": [
          "Billing"
        ],
        "summary": "Price of going live",
        "description": "*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "post_v1_billing_activation_quote",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "register": {
                    "type": "integer"
                  },
                  "kds": {
                    "type": "integer"
                  },
                  "table_service": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": {
                      "type": "integer",
                      "description": "Charged today: a full first month"
                    },
                    "lines": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/InvoiceLine"
                      }
                    },
                    "period_start": {
                      "type": "string"
                    },
                    "period_end": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/billing/activate": {
      "post": {
        "tags": [
          "Billing"
        ],
        "summary": "Go live (first payment)",
        "description": "Charges the first month and starts monthly billing on today's date.\n\n*Auth:* The owner, signed in to the admin portal on the web (`adm_`). Refused from the Android app (`X-Client: native-app`).",
        "operationId": "post_v1_billing_activate",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "register": {
                    "type": "integer"
                  },
                  "kds": {
                    "type": "integer"
                  },
                  "table_service": {
                    "type": "boolean"
                  },
                  "card": {
                    "$ref": "#/components/schemas/Card"
                  },
                  "accept_terms": {
                    "type": "boolean",
                    "const": true
                  },
                  "expected_total": {
                    "type": "integer",
                    "description": "The total you showed; refused with 409 quote_changed if it differs"
                  }
                },
                "required": [
                  "card",
                  "accept_terms"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "invoice": {
                      "$ref": "#/components/schemas/Invoice"
                    },
                    "billing": {
                      "$ref": "#/components/schemas/Billing"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/billing/quote": {
      "post": {
        "tags": [
          "Billing"
        ],
        "summary": "Price of adding a terminal or table service now",
        "description": "Charged now: round(unit × quantity × days_left ÷ period_days) per share. Re-adding something scheduled for removal is free.\n\n*Auth:* Owner or manager (dashboard session, API key or partner key).",
        "operationId": "post_v1_billing_quote",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "line": {
                    "type": "string",
                    "enum": [
                      "register",
                      "kds",
                      "table_service"
                    ]
                  },
                  "quantity": {
                    "type": "integer",
                    "default": 1
                  }
                },
                "required": [
                  "line"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "charge_now": {
                      "type": "integer",
                      "description": "Amount in cents"
                    },
                    "days_left": {
                      "type": "integer"
                    },
                    "period_days": {
                      "type": "integer"
                    },
                    "reinstated": {
                      "type": "integer"
                    },
                    "added": {
                      "type": "integer"
                    },
                    "unit_price": {
                      "type": "integer",
                      "description": "Amount in cents"
                    },
                    "next_monthly": {
                      "type": "integer",
                      "description": "Amount in cents"
                    },
                    "lines": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/InvoiceLine"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/billing/purchase": {
      "post": {
        "tags": [
          "Billing"
        ],
        "summary": "Buy a terminal seat or table service",
        "description": "Send back the `charge_now` you showed as `expected_charge`. Anything else is refused, so a merchant is never charged an amount they didn't see.\n\n*Auth:* The owner, signed in to the admin portal on the web (`adm_`). Refused from the Android app (`X-Client: native-app`).",
        "operationId": "post_v1_billing_purchase",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "line": {
                    "type": "string",
                    "enum": [
                      "register",
                      "kds",
                      "table_service"
                    ]
                  },
                  "quantity": {
                    "type": "integer"
                  },
                  "expected_charge": {
                    "type": "integer",
                    "description": "Amount in cents"
                  }
                },
                "required": [
                  "line",
                  "expected_charge"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "charged": {
                      "type": "integer",
                      "description": "Amount in cents"
                    },
                    "invoice": {
                      "oneOf": [
                        {
                          "$ref": "#/components/schemas/Invoice"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "billing": {
                      "$ref": "#/components/schemas/Billing"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/billing/remove": {
      "post": {
        "tags": [
          "Billing"
        ],
        "summary": "Remove at the next renewal",
        "description": "No refund. Seats must be unpaired first.\n\n*Auth:* The owner, signed in to the admin portal on the web (`adm_`). Refused from the Android app (`X-Client: native-app`).",
        "operationId": "post_v1_billing_remove",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "line": {
                    "type": "string",
                    "enum": [
                      "register",
                      "kds",
                      "table_service"
                    ]
                  },
                  "quantity": {
                    "type": "integer"
                  }
                },
                "required": [
                  "line"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Billing"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/billing/card": {
      "put": {
        "tags": [
          "Billing"
        ],
        "summary": "Replace the card on file",
        "description": "*Auth:* The owner, signed in to the admin portal on the web (`adm_`). Refused from the Android app (`X-Client: native-app`).",
        "operationId": "put_v1_billing_card",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Card"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "card": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          }
        }
      }
    },
    "/v1/billing/pay": {
      "post": {
        "tags": [
          "Billing"
        ],
        "summary": "Pay the balance",
        "description": "Pays every open invoice in one charge. A past-due or suspended account goes live again.\n\n*Auth:* The owner, signed in to the admin portal on the web (`adm_`). Refused from the Android app (`X-Client: native-app`).",
        "operationId": "post_v1_billing_pay",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "card": {
                    "$ref": "#/components/schemas/Card"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "paid": {
                      "type": "integer",
                      "description": "Amount in cents"
                    },
                    "invoices": {
                      "type": "integer"
                    },
                    "billing": {
                      "$ref": "#/components/schemas/Billing"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "402": {
            "$ref": "#/components/responses/E402"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/partner": {
      "get": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Partner profile",
        "description": "*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "get_v1_partner",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Partner"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      },
      "patch": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Update name, contact, branding or hosted apps",
        "description": "Branding applies to all your merchants (agents use their distributor's); each merchant can override. With hosted sign-in it also brands your merchants' sign-in page. `hosted_apps` (distributors only): `false` makes you API-only, so your merchants can't sign in to our admin portal; `true` gives them their own sign-in, separate from every other brand's.\n\n*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "patch_v1_partner",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "contact": {
                    "type": "object"
                  },
                  "branding": {
                    "$ref": "#/components/schemas/Branding"
                  },
                  "hosted_apps": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Partner"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/partner/stats": {
      "get": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Home page numbers and map",
        "description": "Payments are collected amounts (amount + tip + surcharge − refunds) over each merchant's own business days: today, the last 7 and the last 30.\n\n*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "get_v1_partner_stats",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "merchants": {
                      "type": "object",
                      "properties": {
                        "live": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "by_status": {
                          "type": "object"
                        }
                      }
                    },
                    "terminals": {
                      "type": "object",
                      "properties": {
                        "register": {
                          "type": "integer"
                        },
                        "kds": {
                          "type": "integer"
                        },
                        "seen_7d": {
                          "type": "integer"
                        }
                      }
                    },
                    "payments": {
                      "type": "object",
                      "properties": {
                        "today": {
                          "type": "integer",
                          "description": "Amount in cents"
                        },
                        "week": {
                          "type": "integer",
                          "description": "Amount in cents"
                        },
                        "month": {
                          "type": "integer",
                          "description": "Amount in cents"
                        }
                      }
                    },
                    "recurring": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "integer",
                          "description": "Next month, all live merchants"
                        },
                        "sodium": {
                          "type": "integer",
                          "description": "Amount in cents"
                        },
                        "partner": {
                          "type": "integer",
                          "description": "Amount in cents"
                        }
                      }
                    },
                    "map": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string"
                          },
                          "lat": {
                            "type": "number"
                          },
                          "lng": {
                            "type": "number"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/partner/prices": {
      "get": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "SodiumPOS prices",
        "description": "*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "get_v1_partner_prices",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sodium": {
                      "$ref": "#/components/schemas/Prices"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/partner/merchants": {
      "get": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Your merchants",
        "description": "*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "get_v1_partner_merchants",
        "parameters": [
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "name",
                "created"
              ]
            }
          },
          {
            "name": "dir",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "`active`, `inactive` or a status",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "agent_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Merchant"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      },
      "post": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Add a merchant",
        "description": "Created as a draft. `send_invite` emails the owner a sign-up link and needs `pricing`.\n\n*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "post_v1_partner_merchants",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "legal_name": {
                    "type": "string"
                  },
                  "owner_email": {
                    "type": "string"
                  },
                  "address": {
                    "$ref": "#/components/schemas/Address"
                  },
                  "contact": {
                    "type": "object"
                  },
                  "timezone": {
                    "type": "string"
                  },
                  "agent_id": {
                    "type": "string"
                  },
                  "pricing": {
                    "$ref": "#/components/schemas/PricingInput"
                  },
                  "starter_menu": {
                    "type": "boolean",
                    "default": true
                  },
                  "send_invite": {
                    "type": "boolean"
                  },
                  "prospect_id": {
                    "type": "string",
                    "description": "Marks that prospect as converted to this merchant"
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Merchant"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/partner/merchants/{id}": {
      "get": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Merchant detail",
        "description": "Profile, billing (with the SodiumPOS / partner split), terminals and the last invite.\n\n*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "get_v1_partner_merchants_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Merchant"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "patch": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Update a merchant",
        "description": "`agent_id` moves it to another agent of the same distributor.\n\n*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "patch_v1_partner_merchants_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "legal_name": {
                    "type": "string"
                  },
                  "address": {
                    "$ref": "#/components/schemas/Address"
                  },
                  "contact": {
                    "type": "object"
                  },
                  "owner_email": {
                    "type": "string"
                  },
                  "timezone": {
                    "type": "string"
                  },
                  "agent_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Merchant"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/partner/merchants/{id}/pricing": {
      "put": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Set the price sheet",
        "description": "Before go-live it replaces the sheet the merchant will accept. After, it starts at the next renewal.\n\n*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "put_v1_partner_merchants_id_pricing",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PricingInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Merchant"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/partner/merchants/{id}/invite": {
      "post": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Send or resend the invite",
        "description": "*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "post_v1_partner_merchants_id_invite",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "invite_url": {
                      "type": "string"
                    },
                    "expires_in_days": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/partner/merchants/{id}/terminate": {
      "post": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Terminate a merchant",
        "description": "Unpairs its terminals and stops billing. The owner keeps read-only access to the admin portal.\n\n*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "post_v1_partner_merchants_id_terminate",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string"
                  }
                },
                "required": [
                  "reason"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Merchant"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/partner/merchants/{id}/transactions": {
      "get": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Payments",
        "description": "*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "get_v1_partner_merchants_id_transactions",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "before",
            "in": "query",
            "required": false,
            "description": "Next page: pass next_before",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "next_before": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/partner/merchants/{id}/volume": {
      "get": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Payment volume between two times",
        "description": "*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "get_v1_partner_merchants_id_volume",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "collected": {
                      "type": "integer",
                      "description": "Amount in cents"
                    },
                    "tips": {
                      "type": "integer",
                      "description": "Amount in cents"
                    },
                    "refunds": {
                      "type": "integer",
                      "description": "Amount in cents"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "by_day": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/partner/merchants/{id}/invoices": {
      "get": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Merchant invoices with the split",
        "description": "*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "get_v1_partner_merchants_id_invoices",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Invoice"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/partner/agents": {
      "get": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Agents directly below you",
        "description": "*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "get_v1_partner_agents",
        "parameters": [
          {
            "name": "parent_id",
            "in": "query",
            "required": false,
            "description": "List below one of your agents instead",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "all",
            "in": "query",
            "required": false,
            "description": "Every agent in your tree, without stats (for pickers)",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Partner"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      },
      "post": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Add an agent",
        "description": "Emails the agent's contact an invite to the portal.\n\n*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "post_v1_partner_agents",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "contact_name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string"
                  },
                  "phone": {
                    "type": "string"
                  },
                  "parent_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "name",
                  "email"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Partner"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/partner/agents/{id}": {
      "get": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "An agent",
        "description": "*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "get_v1_partner_agents_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Partner"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "patch": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Rename, suspend or reactivate an agent",
        "description": "*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "patch_v1_partner_agents_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "active",
                      "suspended"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Partner"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/partner/pricing-templates": {
      "get": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Pricing templates",
        "description": "Yours and those of partners above you.\n\n*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "get_v1_partner_pricing_templates",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PricingTemplate"
                      }
                    },
                    "sodium": {
                      "$ref": "#/components/schemas/Prices"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      },
      "post": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Create a template",
        "description": "*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "post_v1_partner_pricing_templates",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "markup": {
                    "$ref": "#/components/schemas/Prices"
                  },
                  "fees": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/Fee"
                    }
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PricingTemplate"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/partner/pricing-templates/{id}": {
      "patch": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Update a template",
        "description": "Affects merchants added from now on only.\n\n*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "patch_v1_partner_pricing_templates_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "markup": {
                    "$ref": "#/components/schemas/Prices"
                  },
                  "fees": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/Fee"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PricingTemplate"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "delete": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Archive a template",
        "description": "*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "delete_v1_partner_pricing_templates_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/partner/team": {
      "get": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Your portal logins",
        "description": "*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "get_v1_partner_team",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Account"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      },
      "post": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Invite a teammate",
        "description": "*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "post_v1_partner_team",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string"
                  },
                  "role": {
                    "type": "string",
                    "enum": [
                      "partner_admin",
                      "partner_viewer"
                    ]
                  }
                },
                "required": [
                  "email"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "account": {
                      "$ref": "#/components/schemas/Account"
                    },
                    "invite_url": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/partner/team/{id}": {
      "delete": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Remove a teammate",
        "description": "*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "delete_v1_partner_team_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/partner/prospects": {
      "get": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "List prospects",
        "description": "Businesses you are selling to, newest activity first.\n\n*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "get_v1_partner_prospects",
        "parameters": [
          {
            "name": "stage",
            "in": "query",
            "required": false,
            "description": "A stage, or `open` for new + contacted + demo_sent",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Search name and contact",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "agent_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Prospect"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      },
      "post": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Add a prospect",
        "description": "*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "post_v1_partner_prospects",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProspectInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Prospect"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/partner/prospects/{id}": {
      "get": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Get a prospect",
        "description": "*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "get_v1_partner_prospects_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Prospect"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "patch": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Update a prospect",
        "description": "*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "patch_v1_partner_prospects_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProspectInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Prospect"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "delete": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Delete a prospect",
        "description": "*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "delete_v1_partner_prospects_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/partner/demos": {
      "post": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Send someone a demo",
        "description": "Emails a link to a private demo of the POS and merchant portal (sample data, SodiumPOS branding). Works for 14 days. Email is mocked: `demo_url` is returned so you can share it yourself. Sending to a prospect in `new` or `contacted` moves it to `demo_sent`.\n\n*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "post_v1_partner_demos",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string"
                  },
                  "prospect_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "name",
                  "email"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/DemoLink"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "demo_url": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "email_mocked": {
                          "type": "boolean"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      },
      "get": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Demos you have sent",
        "description": "*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "get_v1_partner_demos",
        "parameters": [
          {
            "name": "prospect_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DemoLink"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/partner/api-keys": {
      "get": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Your partner API keys",
        "description": "*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "get_v1_partner_api_keys",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "prefix": {
                            "type": "string"
                          },
                          "last_used_at": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      },
      "post": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Create a partner API key",
        "description": "Portal admins only (not from a key). The key is returned once. It works on any merchant you or your agents own; pick one with `X-Restaurant-Id`.\n\n*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "post_v1_partner_api_keys",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "prefix": {
                      "type": "string"
                    },
                    "key": {
                      "type": "string",
                      "example": "pk_live_…"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/partner/api-keys/{id}": {
      "delete": {
        "tags": [
          "Partner (white-label)"
        ],
        "summary": "Revoke a partner API key",
        "description": "*Auth:* Distributor or agent portal session (`acc_`) or partner key. Results cover your merchants and your agents' merchants.",
        "operationId": "delete_v1_partner_api_keys_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/demo/requests": {
      "post": {
        "tags": [
          "Demos"
        ],
        "summary": "Request a demo (marketing site)",
        "description": "Emails (mocked) a link to a private demo with the POS, merchant portal and distributor portal. At most 5 an hour per address.\n\n*Auth:* No authentication.",
        "operationId": "post_v1_demo_requests",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string"
                  },
                  "company": {
                    "type": "string"
                  }
                },
                "required": [
                  "name",
                  "email"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sent_to": {
                      "type": "string"
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "demo_url": {
                      "type": "string"
                    },
                    "email_mocked": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          }
        }
      }
    },
    "/v1/demo/start": {
      "post": {
        "tags": [
          "Demos"
        ],
        "summary": "Open a demo",
        "description": "Called by the demo page. Makes the link's private copy of the demo data if needed (`reset: true` starts it over) and signs in to each app it includes. Send the token as `X-Demo` on every later request (or `?demo=` on the stream) to work in that copy.\n\n*Auth:* No authentication.",
        "operationId": "post_v1_demo_start",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "reset": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "token"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "distributor",
                        "merchant"
                      ]
                    },
                    "name": {
                      "type": "string"
                    },
                    "tabs": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "enum": [
                          "pos",
                          "admin",
                          "partner"
                        ]
                      }
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "restaurant": {
                      "type": "string"
                    },
                    "tokens": {
                      "type": "object",
                      "properties": {
                        "terminal": {
                          "type": "string"
                        },
                        "admin": {
                          "type": "string"
                        },
                        "account": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    },
                    "pins": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/platform/overview": {
      "get": {
        "tags": [
          "Platform admin"
        ],
        "summary": "Platform numbers",
        "description": "*Auth:* SodiumPOS platform admin (`acc_`).",
        "operationId": "get_v1_platform_overview",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/platform/partners": {
      "get": {
        "tags": [
          "Platform admin"
        ],
        "summary": "Distributors",
        "description": "*Auth:* SodiumPOS platform admin (`acc_`).",
        "operationId": "get_v1_platform_partners",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "active",
                "suspended"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Partner"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/platform/auth-pools": {
      "get": {
        "tags": [
          "Platform admin"
        ],
        "summary": "Sign-in pools",
        "description": "One per audience (platform, partner) and per merchant brand, with its hosted sign-in domain and whether it is ready.\n\n*Auth:* SodiumPOS platform admin (`acc_`).",
        "operationId": "get_v1_platform_auth_pools",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "provider": {
                      "type": "string",
                      "enum": [
                        "local",
                        "cognito"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "platform",
                              "partner",
                              "merchant"
                            ]
                          },
                          "partner_id": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "slug": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string"
                          },
                          "error": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "sign_in_domain": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "hosts": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "updated_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/platform/partners/{id}/approve": {
      "post": {
        "tags": [
          "Platform admin"
        ],
        "summary": "Approve a distributor",
        "description": "*Auth:* SodiumPOS platform admin (`acc_`).",
        "operationId": "post_v1_platform_partners_id_approve",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Partner"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/platform/partners/{id}/suspend": {
      "post": {
        "tags": [
          "Platform admin"
        ],
        "summary": "Suspend a distributor",
        "description": "Its portal logins stop working. Its merchants keep running.\n\n*Auth:* SodiumPOS platform admin (`acc_`).",
        "operationId": "post_v1_platform_partners_id_suspend",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Partner"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/platform/partners/{id}/reactivate": {
      "post": {
        "tags": [
          "Platform admin"
        ],
        "summary": "Reactivate a distributor",
        "description": "*Auth:* SodiumPOS platform admin (`acc_`).",
        "operationId": "post_v1_platform_partners_id_reactivate",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Partner"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          }
        }
      }
    },
    "/v1/platform/prices": {
      "get": {
        "tags": [
          "Platform admin"
        ],
        "summary": "SodiumPOS prices",
        "description": "*Auth:* SodiumPOS platform admin (`acc_`).",
        "operationId": "get_v1_platform_prices",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "prices": {
                      "$ref": "#/components/schemas/Prices"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      },
      "put": {
        "tags": [
          "Platform admin"
        ],
        "summary": "Set SodiumPOS prices",
        "description": "For merchants priced from now on. Existing merchants keep the prices they signed up with.\n\n*Auth:* SodiumPOS platform admin (`acc_`).",
        "operationId": "put_v1_platform_prices",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "prices": {
                    "$ref": "#/components/schemas/Prices"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "prices": {
                      "$ref": "#/components/schemas/Prices"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/platform/merchants": {
      "get": {
        "tags": [
          "Platform admin"
        ],
        "summary": "Every merchant",
        "description": "*Auth:* SodiumPOS platform admin (`acc_`).",
        "operationId": "get_v1_platform_merchants",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Merchant"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/platform/merchants/{id}": {
      "get": {
        "tags": [
          "Platform admin"
        ],
        "summary": "Merchant detail",
        "description": "*Auth:* SodiumPOS platform admin (`acc_`).",
        "operationId": "get_v1_platform_merchants_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Merchant"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          }
        }
      }
    },
    "/v1/platform/clock": {
      "get": {
        "tags": [
          "Platform admin"
        ],
        "summary": "Billing clock",
        "description": "*Auth:* SodiumPOS platform admin (`acc_`).",
        "operationId": "get_v1_platform_clock",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "adjustable": {
                      "type": "boolean"
                    },
                    "offset_days": {
                      "type": "integer"
                    },
                    "now": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      },
      "post": {
        "tags": [
          "Platform admin"
        ],
        "summary": "Move the billing clock (testing)",
        "description": "Not available in production. Runs billing right after, so renewals, failed payments and suspensions happen as if that time had passed.\n\n*Auth:* SodiumPOS platform admin (`acc_`).",
        "operationId": "post_v1_platform_clock",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "advance_days": {
                    "type": "integer"
                  },
                  "reset": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          }
        }
      }
    },
    "/v1/platform/billing/run": {
      "post": {
        "tags": [
          "Platform admin"
        ],
        "summary": "Run billing now",
        "description": "Renewals and suspensions also run every minute on their own.\n\n*Auth:* SodiumPOS platform admin (`acc_`).",
        "operationId": "post_v1_platform_billing_run",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "merchants": {
                      "type": "integer"
                    },
                    "renewed": {
                      "type": "integer"
                    },
                    "failed": {
                      "type": "integer"
                    },
                    "suspended": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    },
    "/v1/sync/offline": {
      "post": {
        "tags": [
          "Offline sync"
        ],
        "summary": "Replay actions recorded offline",
        "description": "Each `op_id` runs once, so an interrupted sync can be resent. `loc_…` ids are mapped to real ids. Original times are kept, nothing reprints, and failures are reported per op.\n\n*Auth:* Any token, including a terminal token.",
        "operationId": "post_v1_sync_offline",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ops": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/SyncOp"
                    }
                  },
                  "print_jobs": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/PrintJob"
                    }
                  }
                },
                "required": [
                  "ops"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "op_id": {
                            "type": "string"
                          },
                          "ok": {
                            "type": "boolean"
                          },
                          "error": {
                            "type": "string"
                          },
                          "code": {
                            "type": "string"
                          },
                          "note": {
                            "type": "string"
                          },
                          "map": {
                            "type": "object"
                          }
                        }
                      }
                    },
                    "map": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    },
                    "failed": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Dashboard session (`adm_`), staff session (`stf_`), terminal token (`trm_`), API key or partner key (`pk_live_`)."
      },
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "example": "bad_request"
              },
              "message": {
                "type": "string",
                "description": "Written to be shown to staff as-is.",
                "example": "Choose an option for \"Temperature\""
              },
              "details": {
                "type": [
                  "object",
                  "null"
                ],
                "additionalProperties": true
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "Role": {
        "type": "string",
        "enum": [
          "owner",
          "manager",
          "server",
          "bartender",
          "cashier",
          "kitchen"
        ]
      },
      "UserRef": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "usr_8fJ2kq"
          },
          "name": {
            "type": "string",
            "example": "Sam Server"
          }
        }
      },
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "usr_8fJ2kq"
          },
          "name": {
            "type": "string"
          },
          "role": {
            "$ref": "#/components/schemas/Role"
          },
          "email": {
            "type": [
              "string",
              "null"
            ]
          },
          "active": {
            "type": "boolean"
          },
          "has_pin": {
            "type": "boolean"
          },
          "has_login": {
            "type": "boolean",
            "description": "Can sign in to the admin portal (owners and managers with a linked or local login)"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "UserInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "role": {
            "$ref": "#/components/schemas/Role"
          },
          "pin": {
            "type": "string",
            "pattern": "^\\d{4,8}$",
            "description": "4–8 digits, unique per restaurant. Omit on update to keep it."
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Owners and managers sign in to the dashboard with this email. With hosted sign-in they get an emailed invitation; on local-auth servers also send `password`."
          },
          "password": {
            "type": "string",
            "writeOnly": true,
            "description": "Local-auth servers only; a hosted-sign-in server answers `400`."
          },
          "active": {
            "type": "boolean"
          }
        }
      },
      "Terminal": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "trm_8fJ2kq"
          },
          "name": {
            "type": "string",
            "example": "Front register"
          },
          "mode": {
            "type": "string",
            "enum": [
              "full",
              "quick",
              "table",
              "kitchen",
              "kiosk"
            ],
            "description": "`kitchen` = a kitchen display (KDS seat): shows orders, can 86 items, cannot take orders or payments. `kiosk` = a self-order kiosk (see Kiosk). Any mode but `kitchen` uses a register seat."
          },
          "last_seen": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "kiosk_menus": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Menus it shows in kiosk mode; null = every menu"
          }
        }
      },
      "ApiKey": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "key_8fJ2kq"
          },
          "name": {
            "type": "string"
          },
          "prefix": {
            "type": "string",
            "example": "pk_live_a1b2"
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "last_used_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Address": {
        "type": "object",
        "properties": {
          "line1": {
            "type": "string",
            "example": "120 Water St"
          },
          "line2": {
            "type": "string"
          },
          "city": {
            "type": "string",
            "example": "Brooklyn"
          },
          "state": {
            "type": "string",
            "example": "NY"
          },
          "zip": {
            "type": "string",
            "example": "11201"
          }
        }
      },
      "Branding": {
        "type": "object",
        "properties": {
          "app_name": {
            "type": "string",
            "example": "SodiumPOS"
          },
          "primary": {
            "type": "string",
            "example": "#2f6df6"
          },
          "accent": {
            "type": "string",
            "example": "#14b8a6"
          },
          "logo_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "radius": {
            "type": "integer",
            "example": 14
          }
        }
      },
      "Settings": {
        "type": "object",
        "properties": {
          "tax": {
            "type": "object",
            "properties": {
              "rates": {
                "type": "object",
                "additionalProperties": {
                  "type": "number",
                  "description": "Basis points (1000 = 10%)"
                },
                "example": {
                  "food": 887.5,
                  "alcohol": 887.5,
                  "beverage": 887.5,
                  "retail": 887.5,
                  "non_taxable": 0
                },
                "description": "Basis points per item `tax_category`. Fractions allowed."
              }
            }
          },
          "auto_gratuity": {
            "type": "object",
            "properties": {
              "enabled": {
                "type": "boolean",
                "default": true
              },
              "min_party_size": {
                "type": "integer",
                "default": 6
              },
              "rate_bps": {
                "type": "number",
                "description": "Basis points (1000 = 10%)"
              },
              "taxable": {
                "type": "boolean",
                "default": false
              }
            }
          },
          "card_surcharge": {
            "type": "object",
            "properties": {
              "enabled": {
                "type": "boolean",
                "default": false
              },
              "rate_bps": {
                "type": "integer",
                "maximum": 400,
                "default": 300
              },
              "label": {
                "type": "string",
                "default": "Card surcharge"
              }
            }
          },
          "tips": {
            "type": "object",
            "properties": {
              "suggestions_pct": {
                "type": "array",
                "items": {
                  "type": "number"
                },
                "default": [
                  18,
                  20,
                  22
                ]
              },
              "allow_custom": {
                "type": "boolean"
              }
            }
          },
          "business_day": {
            "type": "object",
            "properties": {
              "start": {
                "type": "string",
                "example": "10:00"
              },
              "end": {
                "type": "string",
                "example": "02:00",
                "description": "At or before `start` = ends the next morning."
              }
            }
          },
          "auto_close": {
            "type": "object",
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "off",
                  "end_of_day",
                  "after_days"
                ],
                "default": "off"
              },
              "days": {
                "type": "integer",
                "default": 1
              },
              "tabs": {
                "type": "boolean",
                "default": false,
                "description": "Also charge and close open tabs that have a card on file."
              }
            }
          },
          "manager_required": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "refund",
                "void_fired",
                "comp",
                "discount",
                "reopen",
                "tax_exempt",
                "price_override"
              ]
            }
          },
          "tabs": {
            "type": "object",
            "properties": {
              "preauth_amount": {
                "type": "integer",
                "description": "Hold placed when a card is put on file"
              },
              "require_card": {
                "type": "boolean"
              }
            }
          },
          "offline": {
            "type": "object",
            "properties": {
              "cards_enabled": {
                "type": "boolean"
              },
              "card_limit": {
                "type": "integer",
                "description": "Per offline card payment"
              },
              "total_card_limit": {
                "type": "integer",
                "description": "Per terminal, until it syncs"
              }
            }
          },
          "online": {
            "type": "object",
            "properties": {
              "enabled": {
                "type": "boolean"
              },
              "prep_minutes": {
                "type": "integer"
              },
              "accept_automatically": {
                "type": "boolean"
              },
              "delivery_enabled": {
                "type": "boolean"
              },
              "pickup_enabled": {
                "type": "boolean"
              }
            }
          },
          "receipts": {
            "type": "object",
            "properties": {
              "footer": {
                "type": "string"
              }
            }
          },
          "printing": {
            "type": "object",
            "properties": {
              "receipt_printer_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "online_printer_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "default_kitchen_printer_id": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "terminal": {
            "type": "object",
            "properties": {
              "auto_lock_seconds": {
                "type": "integer",
                "default": 120
              },
              "table_lock": {
                "type": "string",
                "enum": [
                  "soft",
                  "strict",
                  "off"
                ],
                "default": "soft"
              }
            }
          }
        }
      },
      "Restaurant": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "rst_8fJ2kq"
          },
          "slug": {
            "type": "string",
            "example": "harbor-vine"
          },
          "name": {
            "type": "string",
            "example": "Harbor & Vine"
          },
          "timezone": {
            "type": "string",
            "example": "America/New_York"
          },
          "currency": {
            "type": "string",
            "example": "USD"
          },
          "address": {
            "$ref": "#/components/schemas/Address"
          },
          "branding": {
            "$ref": "#/components/schemas/Branding"
          },
          "settings": {
            "$ref": "#/components/schemas/Settings"
          }
        }
      },
      "RestaurantPatch": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "timezone": {
            "type": "string"
          },
          "address": {
            "$ref": "#/components/schemas/Address"
          },
          "branding": {
            "$ref": "#/components/schemas/Branding"
          },
          "settings": {
            "$ref": "#/components/schemas/Settings",
            "description": "Deep-merged: send only what changes."
          }
        }
      },
      "Availability": {
        "type": [
          "object",
          "null"
        ],
        "properties": {
          "days": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "integer",
              "minimum": 0,
              "maximum": 6
            },
            "description": "0 = Sunday. Omitted = every day."
          },
          "start": {
            "type": "string",
            "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
            "example": "09:00"
          },
          "end": {
            "type": "string",
            "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
            "example": "15:00"
          }
        },
        "required": [
          "start",
          "end"
        ],
        "description": "When it can be ordered, in the restaurant's timezone. An end at or before the start runs past midnight (22:00–02:00 on Friday includes 1am Saturday). null = always."
      },
      "Channel": {
        "type": "string",
        "enum": [
          "pos",
          "online",
          "marketplace"
        ]
      },
      "Menu": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "mnu_8fJ2kq"
          },
          "name": {
            "type": "string",
            "example": "All Day"
          },
          "channels": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Channel"
            }
          },
          "availability": {
            "$ref": "#/components/schemas/Availability"
          },
          "active": {
            "type": "boolean"
          },
          "sort": {
            "type": "integer"
          }
        }
      },
      "MenuInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "channels": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Channel"
            }
          },
          "availability": {
            "$ref": "#/components/schemas/Availability"
          },
          "active": {
            "type": "boolean"
          },
          "sort": {
            "type": "integer"
          }
        },
        "required": [
          "name"
        ]
      },
      "Section": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "sec_8fJ2kq"
          },
          "menu_id": {
            "type": "string",
            "example": "mnu_8fJ2kq"
          },
          "name": {
            "type": "string",
            "example": "Burgers"
          },
          "color": {
            "type": [
              "string",
              "null"
            ],
            "example": "#ef4444"
          },
          "sort": {
            "type": "integer"
          }
        }
      },
      "SectionInput": {
        "type": "object",
        "properties": {
          "menu_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "color": {
            "type": [
              "string",
              "null"
            ]
          },
          "sort": {
            "type": "integer"
          }
        },
        "required": [
          "menu_id",
          "name"
        ]
      },
      "ItemGroupLink": {
        "type": "object",
        "properties": {
          "group_id": {
            "type": "string",
            "example": "mgr_8fJ2kq"
          },
          "min_override": {
            "type": [
              "integer",
              "null"
            ]
          },
          "max_override": {
            "type": [
              "integer",
              "null"
            ]
          }
        }
      },
      "Item": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "itm_8fJ2kq"
          },
          "name": {
            "type": "string",
            "example": "Classic Burger"
          },
          "pos_name": {
            "type": [
              "string",
              "null"
            ],
            "example": "Burger"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "price": {
            "type": "integer",
            "description": "Amount in cents"
          },
          "tax_category": {
            "type": "string",
            "enum": [
              "food",
              "alcohol",
              "beverage",
              "retail",
              "non_taxable"
            ]
          },
          "tax_exempt": {
            "type": "boolean"
          },
          "active": {
            "type": "boolean"
          },
          "online_visible": {
            "type": "boolean"
          },
          "default_course": {
            "type": "integer",
            "description": "1 apps/drinks · 2 mains · 3 dessert"
          },
          "track_inventory": {
            "type": "boolean"
          },
          "stock_qty": {
            "type": [
              "integer",
              "null"
            ]
          },
          "low_stock_threshold": {
            "type": [
              "integer",
              "null"
            ]
          },
          "sku": {
            "type": [
              "string",
              "null"
            ]
          },
          "out_of_stock": {
            "type": "boolean",
            "description": "86'd"
          },
          "modifier_groups": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ItemGroupLink"
            }
          },
          "printer_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "section_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "image_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Photo: an upload (POST /v1/uploads/images) or an https URL"
          },
          "availability": {
            "$ref": "#/components/schemas/Availability"
          },
          "available_now": {
            "type": "boolean",
            "description": "Within its own schedule right now (menu schedules are separate)"
          }
        }
      },
      "ItemInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "pos_name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "price": {
            "type": "integer",
            "description": "Amount in cents"
          },
          "tax_category": {
            "type": "string"
          },
          "tax_exempt": {
            "type": "boolean"
          },
          "active": {
            "type": "boolean"
          },
          "online_visible": {
            "type": "boolean"
          },
          "default_course": {
            "type": "integer"
          },
          "track_inventory": {
            "type": "boolean"
          },
          "stock_qty": {
            "type": "integer"
          },
          "low_stock_threshold": {
            "type": "integer"
          },
          "sku": {
            "type": "string"
          },
          "section_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "printer_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "modifier_groups": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ItemGroupLink"
            }
          },
          "image_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "availability": {
            "$ref": "#/components/schemas/Availability",
            "description": "Only orderable at these times, everywhere (a register shows it greyed out). Outside them, adding it is `409 item_unavailable`."
          }
        },
        "required": [
          "name",
          "price"
        ]
      },
      "Modifier": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "mod_8fJ2kq"
          },
          "name": {
            "type": "string",
            "example": "Bacon"
          },
          "price": {
            "type": "integer",
            "description": "Added per selection"
          },
          "is_default": {
            "type": "boolean"
          },
          "out_of_stock": {
            "type": "boolean"
          },
          "child_group_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Nested groups asked when this option is chosen"
          }
        }
      },
      "ModifierGroup": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "mgr_8fJ2kq"
          },
          "name": {
            "type": "string",
            "example": "Meat temperature"
          },
          "display_name": {
            "type": [
              "string",
              "null"
            ],
            "example": "Temperature"
          },
          "min_select": {
            "type": "integer",
            "description": "0 = optional, ≥1 = required"
          },
          "max_select": {
            "type": [
              "integer",
              "null"
            ],
            "description": "null = unlimited"
          },
          "free_quantity": {
            "type": "integer",
            "description": "The first N selections are free"
          },
          "max_per_option": {
            "type": "integer",
            "description": ">1 allows repeats (\"3 extra shots\")"
          },
          "allow_prefixes": {
            "type": "boolean",
            "description": "Enables no / light / extra / side"
          },
          "modifiers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Modifier"
            }
          }
        }
      },
      "ModifierGroupInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "min_select": {
            "type": "integer"
          },
          "max_select": {
            "type": [
              "integer",
              "null"
            ]
          },
          "free_quantity": {
            "type": "integer"
          },
          "max_per_option": {
            "type": "integer"
          },
          "allow_prefixes": {
            "type": "boolean"
          },
          "modifiers": {
            "type": "array",
            "description": "Replaces the option list. Send `id` to keep an existing option.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "price": {
                  "type": "integer",
                  "description": "Amount in cents"
                },
                "is_default": {
                  "type": "boolean"
                },
                "child_group_ids": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "required": [
          "name"
        ]
      },
      "MenuTree": {
        "type": "object",
        "properties": {
          "menus": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "example": "mnu_8fJ2kq"
                },
                "name": {
                  "type": "string"
                },
                "channels": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Channel"
                  }
                },
                "availability": {
                  "$ref": "#/components/schemas/Availability"
                },
                "available_now": {
                  "type": "boolean"
                },
                "sections": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "example": "sec_8fJ2kq"
                      },
                      "name": {
                        "type": "string"
                      },
                      "color": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "item_ids": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "items": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/Item"
            },
            "description": "Keyed by item id"
          },
          "modifier_groups": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/ModifierGroup"
            },
            "description": "Keyed by group id"
          }
        }
      },
      "TableShape": {
        "type": "string",
        "enum": [
          "rect",
          "circle",
          "booth",
          "bar"
        ]
      },
      "Table": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "tbl_8fJ2kq"
          },
          "area_id": {
            "type": "string",
            "example": "are_8fJ2kq"
          },
          "label": {
            "type": "string",
            "example": "8"
          },
          "shape": {
            "$ref": "#/components/schemas/TableShape"
          },
          "seats": {
            "type": "integer"
          },
          "x": {
            "type": "integer",
            "description": "Tonight's position (a temporary Arrange move if there is one)"
          },
          "y": {
            "type": "integer"
          },
          "w": {
            "type": "integer"
          },
          "h": {
            "type": "integer"
          },
          "layout_x": {
            "type": "integer",
            "description": "Saved admin layout position"
          },
          "layout_y": {
            "type": "integer"
          },
          "moved": {
            "type": "boolean"
          },
          "status": {
            "type": "string",
            "enum": [
              "available",
              "open",
              "seated",
              "paying"
            ]
          },
          "seated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "merged_into": {
            "type": [
              "string",
              "null"
            ]
          },
          "root_id": {
            "type": "string"
          },
          "merged_labels": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "example": [
              "11",
              "10"
            ]
          },
          "orders": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FloorOrder"
            }
          }
        }
      },
      "FloorOrder": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "ord_8fJ2kq"
          },
          "number": {
            "type": "integer"
          },
          "type": {
            "$ref": "#/components/schemas/OrderType"
          },
          "guests": {
            "type": "integer"
          },
          "server_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "server_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "pending_items": {
            "type": "integer",
            "description": "Lines not sent to the kitchen yet"
          },
          "fired_items": {
            "type": "integer"
          },
          "totals": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer",
                "description": "Amount in cents"
              },
              "paid": {
                "type": "integer",
                "description": "Amount in cents"
              },
              "balance": {
                "type": "integer",
                "description": "Amount in cents"
              }
            }
          },
          "locked_by": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "user_id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          }
        },
        "required": [
          "id",
          "number",
          "type",
          "guests",
          "totals"
        ]
      },
      "TableInput": {
        "type": "object",
        "properties": {
          "area_id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "shape": {
            "$ref": "#/components/schemas/TableShape"
          },
          "x": {
            "type": "integer"
          },
          "y": {
            "type": "integer"
          },
          "w": {
            "type": "integer"
          },
          "h": {
            "type": "integer"
          },
          "seats": {
            "type": "integer"
          }
        },
        "required": [
          "area_id",
          "label"
        ]
      },
      "FloorArea": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "are_8fJ2kq"
          },
          "name": {
            "type": "string",
            "example": "Main Dining"
          },
          "width": {
            "type": "integer"
          },
          "height": {
            "type": "integer"
          },
          "sort": {
            "type": "integer"
          },
          "outline": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/RoomCorner"
            },
            "description": "Room shape as corners (clockwise). null = the whole width × height rectangle."
          },
          "fixtures": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Fixture"
            },
            "description": "Bars, kitchen, entrance and labels. Never seat guests."
          }
        }
      },
      "RoomCorner": {
        "type": "object",
        "properties": {
          "x": {
            "type": "integer"
          },
          "y": {
            "type": "integer"
          },
          "bend": {
            "type": "integer",
            "description": "Curves the wall to the next corner: its midpoint moves this far outward (negative = inward). Omitted = straight."
          }
        },
        "required": [
          "x",
          "y"
        ]
      },
      "Fixture": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "fix_8fJ2kq"
          },
          "kind": {
            "type": "string",
            "enum": [
              "bar",
              "kitchen",
              "entrance",
              "restroom",
              "host",
              "wall",
              "label"
            ]
          },
          "label": {
            "type": [
              "string",
              "null"
            ],
            "example": "Kitchen"
          },
          "x": {
            "type": "integer"
          },
          "y": {
            "type": "integer"
          },
          "w": {
            "type": "integer"
          },
          "h": {
            "type": "integer"
          }
        }
      },
      "Prospect": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "prs_8fJ2kq"
          },
          "name": {
            "type": "string",
            "example": "Rosa's Trattoria"
          },
          "legal_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "contact": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "email": {
                "type": "string"
              },
              "phone": {
                "type": "string"
              }
            }
          },
          "address": {
            "$ref": "#/components/schemas/Address"
          },
          "timezone": {
            "type": [
              "string",
              "null"
            ]
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          },
          "stage": {
            "type": "string",
            "enum": [
              "new",
              "contacted",
              "demo_sent",
              "converted",
              "lost"
            ]
          },
          "merchant": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "status": {
                "type": "string"
              }
            }
          },
          "partner": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "kind": {
                "type": "string",
                "enum": [
                  "distributor",
                  "agent"
                ]
              }
            }
          },
          "demos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DemoLink"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ProspectInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "legal_name": {
            "type": "string"
          },
          "contact": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "email": {
                "type": "string"
              },
              "phone": {
                "type": "string"
              }
            }
          },
          "address": {
            "$ref": "#/components/schemas/Address"
          },
          "timezone": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "stage": {
            "type": "string",
            "enum": [
              "new",
              "contacted",
              "demo_sent",
              "converted",
              "lost"
            ]
          },
          "agent_id": {
            "type": "string",
            "description": "Assign to one of your agents"
          }
        }
      },
      "DemoLink": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "dml_8fJ2kq"
          },
          "kind": {
            "type": "string",
            "enum": [
              "distributor",
              "merchant"
            ],
            "description": "`merchant`: POS and merchant portal. `distributor`: also the distributor portal."
          },
          "name": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "company": {
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "site",
              "partner"
            ]
          },
          "prospect_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "opened_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "last_used_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "expired": {
            "type": "boolean"
          }
        }
      },
      "FloorAreaInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "width": {
            "type": "integer",
            "default": 1000
          },
          "height": {
            "type": "integer",
            "default": 700
          },
          "sort": {
            "type": "integer"
          }
        },
        "required": [
          "name"
        ]
      },
      "Floor": {
        "type": "object",
        "properties": {
          "areas": {
            "type": "array",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/FloorArea"
                },
                {
                  "type": "object",
                  "properties": {
                    "tables": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Table"
                      }
                    }
                  }
                }
              ]
            }
          }
        }
      },
      "OrderType": {
        "type": "string",
        "enum": [
          "quick",
          "dine_in",
          "tab",
          "takeout",
          "online",
          "delivery"
        ]
      },
      "Customer": {
        "type": [
          "object",
          "null"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "Riley"
          },
          "phone": {
            "type": "string"
          },
          "email": {
            "type": "string"
          }
        }
      },
      "ModifierSelection": {
        "type": "object",
        "properties": {
          "group_id": {
            "type": "string"
          },
          "modifier_id": {
            "type": "string"
          },
          "prefix": {
            "type": "string",
            "enum": [
              "no",
              "light",
              "extra",
              "side"
            ]
          },
          "quantity": {
            "type": "integer",
            "default": 1
          },
          "children": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ModifierSelection"
            },
            "description": "Selections for nested groups"
          }
        },
        "required": [
          "group_id",
          "modifier_id"
        ]
      },
      "LineInput": {
        "type": "object",
        "properties": {
          "item_id": {
            "type": "string"
          },
          "quantity": {
            "type": "integer",
            "default": 1,
            "minimum": 1,
            "maximum": 999
          },
          "seat": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "maximum": 99
          },
          "course": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "maximum": 9
          },
          "notes": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 500,
            "example": "no sesame"
          },
          "modifiers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ModifierSelection"
            }
          }
        },
        "required": [
          "item_id"
        ]
      },
      "ModifierSnapshot": {
        "type": "object",
        "properties": {
          "group_id": {
            "type": "string"
          },
          "group_name": {
            "type": "string"
          },
          "modifier_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "prefix": {
            "type": [
              "string",
              "null"
            ]
          },
          "quantity": {
            "type": "integer"
          },
          "unit_price": {
            "type": "integer",
            "description": "Amount in cents"
          },
          "charged": {
            "type": "integer",
            "description": "Amount in cents"
          },
          "hidden": {
            "type": "boolean",
            "description": "Unchanged default; not printed"
          },
          "children": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ModifierSnapshot"
            }
          }
        }
      },
      "OrderItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "oli_8fJ2kq"
          },
          "check_id": {
            "type": "string",
            "example": "chk_8fJ2kq"
          },
          "item_id": {
            "type": "string",
            "example": "itm_8fJ2kq"
          },
          "name": {
            "type": "string"
          },
          "unit_price": {
            "type": "integer",
            "description": "Amount in cents"
          },
          "quantity": {
            "type": "integer"
          },
          "modifiers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ModifierSnapshot"
            }
          },
          "modifiers_total": {
            "type": "integer",
            "description": "Amount in cents"
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          },
          "seat": {
            "type": [
              "integer",
              "null"
            ]
          },
          "course": {
            "type": [
              "integer",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "fired",
              "voided"
            ]
          },
          "comped": {
            "type": "boolean"
          },
          "tax_exempt": {
            "type": "boolean"
          },
          "fired_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "line": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "gross": {
                "type": "integer",
                "description": "Amount in cents"
              },
              "comp": {
                "type": "integer",
                "description": "Amount in cents"
              },
              "discount": {
                "type": "integer",
                "description": "Amount in cents"
              },
              "net": {
                "type": "integer",
                "description": "Amount in cents"
              },
              "tax": {
                "type": "integer",
                "description": "Amount in cents"
              },
              "service": {
                "type": "integer",
                "description": "Amount in cents"
              }
            },
            "required": [
              "gross",
              "net",
              "tax"
            ]
          }
        }
      },
      "Totals": {
        "type": "object",
        "properties": {
          "subtotal": {
            "type": "integer",
            "description": "Amount in cents"
          },
          "comps": {
            "type": "integer",
            "description": "Amount in cents"
          },
          "discounts": {
            "type": "integer",
            "description": "Amount in cents"
          },
          "service_charge": {
            "type": "integer",
            "description": "Auto gratuity"
          },
          "tax": {
            "type": "integer",
            "description": "Amount in cents"
          },
          "total": {
            "type": "integer",
            "description": "Amount in cents"
          },
          "tips": {
            "type": "integer",
            "description": "Amount in cents"
          },
          "surcharges": {
            "type": "integer",
            "description": "Amount in cents"
          },
          "paid": {
            "type": "integer",
            "description": "Amount in cents"
          },
          "refunded": {
            "type": "integer",
            "description": "Amount in cents"
          },
          "balance": {
            "type": "integer",
            "description": "Amount in cents"
          }
        }
      },
      "Check": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "chk_8fJ2kq"
          },
          "label": {
            "type": "string",
            "example": "Check 1"
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "paid"
            ]
          },
          "split_ways": {
            "type": [
              "integer",
              "null"
            ]
          },
          "totals": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Totals"
              },
              {
                "type": "null"
              }
            ]
          },
          "next_share": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "amount": {
                "type": "integer",
                "description": "Amount in cents"
              },
              "share": {
                "type": "integer"
              },
              "of": {
                "type": "integer"
              }
            }
          }
        }
      },
      "Payment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "pay_8fJ2kq"
          },
          "check_id": {
            "type": "string",
            "example": "chk_8fJ2kq"
          },
          "method": {
            "type": "string",
            "enum": [
              "card",
              "cash",
              "card_on_file",
              "external",
              "online"
            ]
          },
          "amount": {
            "type": "integer",
            "description": "Applied to the bill"
          },
          "tip": {
            "type": "integer",
            "description": "Amount in cents"
          },
          "surcharge": {
            "type": "integer",
            "description": "Amount in cents"
          },
          "status": {
            "type": "string",
            "enum": [
              "authorized",
              "captured",
              "refunded",
              "partially_refunded",
              "voided",
              "failed"
            ],
            "description": "`authorized` until the order is closed out"
          },
          "card_brand": {
            "type": [
              "string",
              "null"
            ]
          },
          "card_last4": {
            "type": [
              "string",
              "null"
            ]
          },
          "refunded_amount": {
            "type": "integer",
            "description": "Amount in cents"
          },
          "cash_tendered": {
            "type": [
              "integer",
              "null"
            ]
          },
          "change_due": {
            "type": [
              "integer",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Delivery": {
        "type": [
          "object",
          "null"
        ],
        "properties": {
          "provider": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "requested",
              "assigned",
              "picked_up",
              "delivered",
              "cancelled"
            ]
          },
          "fee": {
            "type": "integer",
            "description": "Amount in cents"
          },
          "eta": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "tracking_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "courier": {
            "type": [
              "object",
              "null"
            ]
          }
        }
      },
      "Order": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "ord_8fJ2kq"
          },
          "number": {
            "type": "integer",
            "example": 12
          },
          "type": {
            "$ref": "#/components/schemas/OrderType"
          },
          "source": {
            "type": "string",
            "enum": [
              "pos",
              "kiosk",
              "online",
              "doordash",
              "ubereats",
              "grubhub",
              "api"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "closed",
              "voided"
            ]
          },
          "fulfillment": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              null,
              "received",
              "accepted",
              "ready",
              "picked_up",
              "completed",
              "cancelled"
            ]
          },
          "table": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "label": {
                "type": "string",
                "example": "11 + 10"
              }
            }
          },
          "server": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/UserRef"
              },
              {
                "type": "null"
              }
            ]
          },
          "guests": {
            "type": "integer"
          },
          "tab_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "customer": {
            "$ref": "#/components/schemas/Customer"
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          },
          "tax_exempt": {
            "type": "boolean"
          },
          "auto_gratuity_waived": {
            "type": "boolean"
          },
          "service_charge_applies": {
            "type": "boolean"
          },
          "card_on_file": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "brand": {
                "type": "string"
              },
              "last4": {
                "type": "string"
              },
              "hold_amount": {
                "type": "integer",
                "description": "The pre-auth hold; 0 once it's released"
              }
            }
          },
          "locked_by": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "user_id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "terminal_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "version": {
            "type": "integer",
            "description": "Bumped on every change"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "closed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "closed_out_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "closed_out_by": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/UserRef"
              },
              {
                "type": "null"
              }
            ]
          },
          "pickup_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "delivery": {
            "$ref": "#/components/schemas/Delivery"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderItem"
            }
          },
          "checks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Check"
            }
          },
          "discounts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "order_item_id": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "discount_id": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "name": {
                  "type": "string"
                },
                "kind": {
                  "type": "string"
                },
                "value": {
                  "type": "number"
                }
              }
            }
          },
          "payments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Payment"
            }
          },
          "totals": {
            "$ref": "#/components/schemas/Totals"
          }
        }
      },
      "OrderSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "ord_8fJ2kq"
          },
          "number": {
            "type": "integer"
          },
          "type": {
            "$ref": "#/components/schemas/OrderType"
          },
          "source": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "fulfillment": {
            "type": [
              "string",
              "null"
            ]
          },
          "table": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "label": {
                "type": "string"
              }
            }
          },
          "server": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/UserRef"
              },
              {
                "type": "null"
              }
            ]
          },
          "guests": {
            "type": "integer"
          },
          "tab_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "customer": {
            "$ref": "#/components/schemas/Customer"
          },
          "item_count": {
            "type": "integer"
          },
          "pending_count": {
            "type": "integer"
          },
          "totals": {
            "$ref": "#/components/schemas/Totals"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "closed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "closed_out_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "payments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Payment"
            }
          }
        }
      },
      "OrderInput": {
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/OrderType"
          },
          "table_id": {
            "type": "string",
            "description": "dine_in: one party per table (409 if occupied)"
          },
          "guests": {
            "type": "integer",
            "minimum": 1,
            "maximum": 500,
            "default": 1
          },
          "tab_name": {
            "type": "string",
            "maxLength": 100
          },
          "customer": {
            "$ref": "#/components/schemas/Customer"
          },
          "notes": {
            "type": "string",
            "maxLength": 1000
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LineInput"
            }
          },
          "fire": {
            "type": "boolean",
            "description": "Send the items to the kitchen right away"
          }
        },
        "required": [
          "type"
        ]
      },
      "OrderPatch": {
        "type": "object",
        "properties": {
          "guests": {
            "type": "integer"
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          },
          "tab_name": {
            "type": "string"
          },
          "customer": {
            "$ref": "#/components/schemas/Customer"
          },
          "table_id": {
            "type": "string",
            "description": "Move the party"
          },
          "server_id": {
            "type": "string",
            "description": "Transfer (own orders, or any as a manager)"
          },
          "tax_exempt": {
            "type": "boolean"
          },
          "tax_exempt_id": {
            "type": "string"
          },
          "auto_gratuity_waived": {
            "type": "boolean"
          },
          "expected_version": {
            "type": "integer",
            "description": "Optimistic concurrency: 409 version_conflict if stale"
          },
          "manager_pin": {
            "type": "string"
          }
        }
      },
      "PayInput": {
        "type": "object",
        "properties": {
          "check_id": {
            "type": "string",
            "description": "Default: first open check with a balance"
          },
          "method": {
            "type": "string",
            "enum": [
              "card",
              "cash",
              "card_on_file",
              "external"
            ]
          },
          "amount": {
            "type": "integer",
            "minimum": 1,
            "description": "Cents applied to the bill, up to the check balance. Default: the balance, or the next even-split share"
          },
          "tip": {
            "type": "integer",
            "minimum": 0,
            "description": "Cents, up to 3× amount or $100 (10000), whichever is more"
          },
          "source": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "card_present",
                  "token"
                ]
              },
              "token": {
                "type": "string"
              },
              "test_card": {
                "type": "string",
                "example": "4242424242424242"
              }
            }
          },
          "cash_tendered": {
            "type": "integer",
            "description": "Cash only"
          },
          "external_label": {
            "type": "string",
            "example": "Gift card"
          },
          "idempotency_key": {
            "type": "string",
            "maxLength": 200,
            "description": "A fresh key per payment; resend it only to retry that payment. Retries (even concurrent) return the original payment; a key reused with a different method, amount or tip gets 409 idempotency_conflict."
          }
        },
        "required": [
          "method"
        ]
      },
      "Discount": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "dsc_8fJ2kq"
          },
          "name": {
            "type": "string",
            "example": "Happy hour"
          },
          "kind": {
            "type": "string",
            "enum": [
              "percent",
              "amount"
            ]
          },
          "value": {
            "type": "number",
            "description": "bps for percent, cents for amount"
          },
          "scope": {
            "type": "string",
            "enum": [
              "order",
              "item"
            ]
          },
          "code": {
            "type": [
              "string",
              "null"
            ],
            "example": "WELCOME10"
          },
          "schedule": {
            "$ref": "#/components/schemas/Availability"
          },
          "channels": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Channel"
            }
          },
          "min_subtotal": {
            "type": [
              "integer",
              "null"
            ]
          },
          "max_uses": {
            "type": [
              "integer",
              "null"
            ]
          },
          "requires_manager": {
            "type": "boolean"
          },
          "active": {
            "type": "boolean"
          }
        }
      },
      "Printer": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "ptr_8fJ2kq"
          },
          "name": {
            "type": "string",
            "example": "Kitchen"
          },
          "role": {
            "type": "string",
            "enum": [
              "kitchen",
              "bar",
              "expo",
              "receipt"
            ]
          },
          "connection": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "example": "mock"
              }
            }
          },
          "active": {
            "type": "boolean"
          }
        }
      },
      "PrintJob": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "prt_8fJ2kq"
          },
          "printer_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "order_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "kind": {
            "type": "string",
            "enum": [
              "fire",
              "void",
              "receipt",
              "online",
              "test"
            ]
          },
          "title": {
            "type": "string"
          },
          "content": {
            "type": "object",
            "properties": {
              "text": {
                "type": "string",
                "description": "42-column rendering"
              }
            }
          },
          "status": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "KdsTicket": {
        "type": "object",
        "properties": {
          "order_id": {
            "type": "string"
          },
          "number": {
            "type": "integer"
          },
          "type": {
            "$ref": "#/components/schemas/OrderType"
          },
          "source": {
            "type": "string"
          },
          "source_label": {
            "type": [
              "string",
              "null"
            ]
          },
          "table": {
            "type": [
              "string",
              "null"
            ],
            "example": "8"
          },
          "guests": {
            "type": "integer"
          },
          "server": {
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Guest or tab name"
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          },
          "voided": {
            "type": "boolean"
          },
          "fired_at": {
            "type": "string",
            "format": "date-time"
          },
          "bumped_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "quantity": {
                  "type": "integer"
                },
                "modifiers": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "notes": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "seat": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "course": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "fired",
                    "voided"
                  ]
                },
                "ready": {
                  "type": "boolean"
                }
              }
            }
          }
        }
      },
      "Reservation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "rsv_8fJ2kq"
          },
          "name": {
            "type": "string",
            "example": "Smith"
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "email": {
            "type": [
              "string",
              "null"
            ]
          },
          "party_size": {
            "type": "integer",
            "example": 4
          },
          "starts_at": {
            "type": "string",
            "format": "date-time"
          },
          "duration_min": {
            "type": "integer",
            "example": 90
          },
          "ends_at": {
            "type": "string",
            "format": "date-time"
          },
          "table": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "label": {
                "type": "string"
              }
            }
          },
          "status": {
            "type": "string",
            "enum": [
              "booked",
              "arrived",
              "seated",
              "completed",
              "cancelled",
              "no_show"
            ]
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "pos",
              "phone",
              "online",
              "api"
            ]
          },
          "order_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "seated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "ReservationInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 80
          },
          "phone": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "party_size": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100
          },
          "starts_at": {
            "type": "string",
            "format": "date-time"
          },
          "duration_min": {
            "type": "integer",
            "minimum": 15,
            "maximum": 480,
            "default": 90
          },
          "table_id": {
            "type": "string",
            "description": "Hold a table (refused if another booking overlaps)"
          },
          "notes": {
            "type": "string",
            "maxLength": 500
          },
          "source": {
            "type": "string",
            "enum": [
              "pos",
              "phone",
              "online",
              "api"
            ]
          }
        },
        "required": [
          "name",
          "party_size",
          "starts_at"
        ]
      },
      "WaitlistEntry": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "wlt_8fJ2kq"
          },
          "name": {
            "type": "string"
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "party_size": {
            "type": "integer"
          },
          "quoted_min": {
            "type": "integer",
            "example": 15
          },
          "status": {
            "type": "string",
            "enum": [
              "waiting",
              "notified",
              "seated",
              "left"
            ]
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          },
          "table": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "label": {
                "type": "string"
              }
            }
          },
          "order_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "quoted_until": {
            "type": "string",
            "format": "date-time"
          },
          "notified_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "seated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "left_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "WebhookDelivery": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "whd_8fJ2kq"
          },
          "webhook_id": {
            "type": "string"
          },
          "event_id": {
            "type": "string",
            "description": "Same on every attempt; use it to ignore duplicates"
          },
          "type": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "delivered",
              "failed"
            ]
          },
          "attempts": {
            "type": "integer"
          },
          "last_status": {
            "type": [
              "integer",
              "null"
            ]
          },
          "last_error": {
            "type": [
              "string",
              "null"
            ]
          },
          "next_attempt_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "delivered_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "Webhook": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "whk_8fJ2kq"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "order.closed",
              "payment.created"
            ]
          },
          "active": {
            "type": "boolean"
          },
          "secret": {
            "type": "string",
            "example": "whsec_…a1b2",
            "description": "The full signing secret is returned only when the webhook is created; afterwards only its last 4 characters."
          }
        }
      },
      "WebhookInput": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "default": [
              "*"
            ]
          },
          "active": {
            "type": "boolean"
          }
        },
        "required": [
          "url"
        ]
      },
      "AuditEntry": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "user_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "approved_by": {
            "type": [
              "string",
              "null"
            ]
          },
          "action": {
            "type": "string",
            "example": "item.void"
          },
          "entity": {
            "type": "string"
          },
          "entity_id": {
            "type": "string"
          },
          "data": {
            "type": [
              "object",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SalesReport": {
        "type": "object",
        "properties": {
          "totals": {
            "type": "object",
            "properties": {
              "gross_sales": {
                "type": "integer"
              },
              "comps": {
                "type": "integer"
              },
              "discounts": {
                "type": "integer"
              },
              "net_sales": {
                "type": "integer"
              },
              "service_charges": {
                "type": "integer"
              },
              "tax": {
                "type": "integer"
              },
              "tips": {
                "type": "integer"
              },
              "surcharges": {
                "type": "integer"
              },
              "refunds": {
                "type": "integer"
              },
              "total_collected": {
                "type": "integer"
              },
              "orders": {
                "type": "integer"
              },
              "guests": {
                "type": "integer"
              },
              "average_check": {
                "type": "integer"
              },
              "voids": {
                "type": "integer"
              },
              "void_count": {
                "type": "integer"
              },
              "open_orders": {
                "type": "integer"
              },
              "open_balance": {
                "type": "integer"
              }
            }
          },
          "by_hour": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "hour": {
                  "type": "string",
                  "example": "17"
                },
                "net_sales": {
                  "type": "integer",
                  "description": "Amount in cents"
                },
                "orders": {
                  "type": "integer"
                }
              }
            }
          },
          "by_day": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "day": {
                  "type": "string",
                  "example": "2026-11-06"
                },
                "net_sales": {
                  "type": "integer",
                  "description": "Amount in cents"
                },
                "orders": {
                  "type": "integer"
                },
                "tips": {
                  "type": "integer",
                  "description": "Amount in cents"
                }
              }
            }
          },
          "by_item": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "item_id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "quantity": {
                  "type": "integer"
                },
                "gross": {
                  "type": "integer",
                  "description": "Amount in cents"
                },
                "net_sales": {
                  "type": "integer",
                  "description": "Amount in cents"
                },
                "comps": {
                  "type": "integer",
                  "description": "Amount in cents"
                },
                "discounts": {
                  "type": "integer",
                  "description": "Amount in cents"
                }
              }
            }
          },
          "by_section": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "by_server": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "server_id": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "null for orders with no server (kiosk, online, delivery apps)"
                },
                "name": {
                  "type": "string"
                },
                "net_sales": {
                  "type": "integer",
                  "description": "Amount in cents"
                },
                "orders": {
                  "type": "integer"
                },
                "guests": {
                  "type": "integer"
                },
                "tips": {
                  "type": "integer",
                  "description": "Amount in cents"
                },
                "service_charges": {
                  "type": "integer",
                  "description": "Amount in cents"
                }
              }
            }
          },
          "by_source": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "by_type": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "by_payment_method": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "method": {
                  "type": "string"
                },
                "amount": {
                  "type": "integer",
                  "description": "Amount in cents"
                },
                "tips": {
                  "type": "integer",
                  "description": "Amount in cents"
                },
                "count": {
                  "type": "integer"
                },
                "refunds": {
                  "type": "integer",
                  "description": "Amount in cents"
                }
              }
            }
          }
        }
      },
      "PublicOrderInput": {
        "type": "object",
        "properties": {
          "customer": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "phone": {
                "type": "string"
              },
              "email": {
                "type": "string"
              }
            },
            "required": [
              "name"
            ]
          },
          "fulfillment_type": {
            "type": "string",
            "enum": [
              "pickup",
              "delivery"
            ]
          },
          "delivery_address": {
            "$ref": "#/components/schemas/Address"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LineInput"
            }
          },
          "tip": {
            "type": "integer",
            "description": "Amount in cents"
          },
          "promo_code": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "payment_token": {
            "type": "string",
            "description": "From your card form (mock: tok_mock_<last4>_<firstDigit>_x)"
          }
        },
        "required": [
          "customer",
          "fulfillment_type",
          "items",
          "payment_token"
        ]
      },
      "SyncOp": {
        "type": "object",
        "properties": {
          "op_id": {
            "type": "string",
            "description": "Idempotency key: each op runs once"
          },
          "ts": {
            "type": "string",
            "format": "date-time",
            "description": "When it happened (kept as the record time)"
          },
          "user_id": {
            "type": "string"
          },
          "approved_by": {
            "type": [
              "string",
              "null"
            ],
            "description": "Manager whose PIN the terminal verified"
          },
          "type": {
            "type": "string",
            "enum": [
              "create_order",
              "add_lines",
              "update_line",
              "void_line",
              "fire",
              "update_order",
              "pay"
            ]
          },
          "local_id": {
            "type": "string",
            "example": "loc_o1"
          },
          "order": {
            "description": "Order fields (create_order) or an order id / loc_ id"
          },
          "lines": {
            "type": "array",
            "items": {}
          },
          "line": {
            "type": "string"
          },
          "patch": {
            "type": "object"
          },
          "reason": {
            "type": "string"
          },
          "payment": {
            "type": "object"
          }
        },
        "required": [
          "op_id",
          "ts",
          "user_id",
          "type"
        ]
      },
      "Partner": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "ptn_8fJ2kq"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "active",
              "suspended"
            ]
          },
          "is_house": {
            "type": "boolean"
          },
          "kind": {
            "type": "string",
            "enum": [
              "distributor",
              "agent"
            ]
          },
          "parent": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "distributor_id": {
            "type": "string"
          },
          "depth": {
            "type": "integer",
            "description": "0 = distributor, 1 = its agent, …"
          },
          "contact": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "email": {
                "type": "string"
              },
              "phone": {
                "type": "string"
              }
            }
          },
          "branding": {
            "$ref": "#/components/schemas/Branding"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "approved_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "hosted_apps": {
            "type": "boolean",
            "description": "false = API-only distributor: its merchants use the distributor's own apps (partner key), never our hosted admin portal. Agents report their distributor's setting."
          },
          "sign_in": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "pending",
                  "ready",
                  "error"
                ]
              },
              "sign_in_domain": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "admin_url": {
                "type": "string",
                "description": "Where this brand's merchants sign in to the admin portal"
              }
            }
          }
        }
      },
      "Account": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "acc_8fJ2kq"
          },
          "name": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "role": {
            "type": "string",
            "enum": [
              "platform_admin",
              "partner_admin",
              "partner_viewer"
            ]
          },
          "partner_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "active": {
            "type": "boolean"
          },
          "invited": {
            "type": "boolean",
            "description": "Invite not accepted yet"
          },
          "last_login_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Prices": {
        "type": "object",
        "properties": {
          "base": {
            "type": "integer",
            "description": "Monthly plan"
          },
          "register": {
            "type": "integer",
            "description": "Per register terminal per month"
          },
          "kds": {
            "type": "integer",
            "description": "Per kitchen display terminal per month"
          },
          "table_service": {
            "type": "integer",
            "description": "Table service add-on per month"
          }
        }
      },
      "Fee": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "Support plan"
          },
          "amount": {
            "type": "integer",
            "description": "Per month"
          }
        },
        "required": [
          "name",
          "amount"
        ]
      },
      "PricingInput": {
        "type": "object",
        "properties": {
          "template_id": {
            "type": "string",
            "description": "Start from a template (yours or an ancestor's)"
          },
          "markup": {
            "$ref": "#/components/schemas/Prices"
          },
          "fees": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Fee"
            }
          }
        }
      },
      "PricingTemplate": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "tpl_8fJ2kq"
          },
          "name": {
            "type": "string"
          },
          "markup": {
            "$ref": "#/components/schemas/Prices"
          },
          "fees": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Fee"
            }
          },
          "partner_id": {
            "type": "string"
          },
          "inherited": {
            "type": "boolean",
            "description": "Belongs to a partner above you"
          },
          "archived": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "MerchantStatus": {
        "type": "string",
        "enum": [
          "draft",
          "invited",
          "onboarding",
          "live",
          "past_due",
          "suspended",
          "terminated"
        ],
        "description": "`live` and `past_due` can run the store; the rest are read-only."
      },
      "Merchant": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "rst_8fJ2kq"
          },
          "name": {
            "type": "string"
          },
          "legal_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "slug": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/MerchantStatus"
          },
          "active": {
            "type": "boolean"
          },
          "operational": {
            "type": "boolean"
          },
          "timezone": {
            "type": "string"
          },
          "address": {
            "$ref": "#/components/schemas/Address"
          },
          "contact": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "email": {
                "type": "string"
              },
              "phone": {
                "type": "string"
              }
            }
          },
          "owner_email": {
            "type": [
              "string",
              "null"
            ]
          },
          "lat": {
            "type": [
              "number",
              "null"
            ]
          },
          "lng": {
            "type": [
              "number",
              "null"
            ]
          },
          "partner": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "kind": {
                "type": "string"
              }
            }
          },
          "distributor_id": {
            "type": "string"
          },
          "terminals": {
            "type": "object",
            "properties": {
              "register": {
                "type": "integer"
              },
              "kds": {
                "type": "integer"
              }
            }
          },
          "seats": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "register": {
                "type": "integer"
              },
              "kds": {
                "type": "integer"
              }
            }
          },
          "table_service": {
            "type": "boolean"
          },
          "next_renewal": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "volume_30d": {
            "type": "integer",
            "description": "Collected in the last 30 days"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "terminated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "terminated_reason": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "InvoiceLine": {
        "type": "object",
        "properties": {
          "line": {
            "type": "string",
            "enum": [
              "base",
              "register",
              "kds",
              "table_service",
              "fee"
            ]
          },
          "description": {
            "type": "string"
          },
          "quantity": {
            "type": "integer"
          },
          "unit_price": {
            "type": "integer",
            "description": "Per month"
          },
          "days": {
            "type": "integer"
          },
          "period_days": {
            "type": "integer"
          },
          "amount": {
            "type": "integer",
            "description": "round(unit × quantity × days ÷ period_days); partner views also show `sodium_amount` and `partner_amount`, each rounded on its own"
          }
        }
      },
      "Invoice": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "inv_8fJ2kq"
          },
          "number": {
            "type": "integer"
          },
          "kind": {
            "type": "string",
            "enum": [
              "activation",
              "renewal",
              "purchase"
            ]
          },
          "period_start": {
            "type": "string",
            "format": "date"
          },
          "period_end": {
            "type": "string",
            "format": "date"
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "paid",
              "void"
            ]
          },
          "total": {
            "type": "integer",
            "description": "Amount in cents"
          },
          "sodium_amount": {
            "type": "integer",
            "description": "Partner and platform views only"
          },
          "partner_amount": {
            "type": "integer",
            "description": "Partner and platform views only"
          },
          "card": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "brand": {
                "type": "string"
              },
              "last4": {
                "type": "string"
              }
            }
          },
          "failure": {
            "type": [
              "string",
              "null"
            ]
          },
          "lines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InvoiceLine"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "paid_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "Billing": {
        "type": "object",
        "properties": {
          "status": {
            "$ref": "#/components/schemas/MerchantStatus"
          },
          "period_start": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "period_end": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Next renewal"
          },
          "days_left": {
            "type": [
              "integer",
              "null"
            ]
          },
          "today": {
            "type": "string",
            "format": "date"
          },
          "card": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "brand": {
                "type": "string"
              },
              "last4": {
                "type": "string"
              },
              "exp_month": {
                "type": "integer"
              },
              "exp_year": {
                "type": "integer"
              }
            }
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "line": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "quantity": {
                  "type": "integer"
                },
                "next_quantity": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "Scheduled change at renewal"
                },
                "unit_price": {
                  "type": "integer",
                  "description": "Amount in cents"
                },
                "monthly": {
                  "type": "integer",
                  "description": "Amount in cents"
                }
              }
            }
          },
          "fees": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Fee"
            }
          },
          "monthly": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer",
                "description": "Amount in cents"
              }
            }
          },
          "next_monthly": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer",
                "description": "Amount in cents"
              }
            }
          },
          "seats": {
            "type": "object",
            "properties": {
              "register": {
                "type": "object",
                "properties": {
                  "paid": {
                    "type": "integer"
                  },
                  "usable": {
                    "type": "integer"
                  },
                  "used": {
                    "type": "integer"
                  }
                }
              },
              "kds": {
                "type": "object",
                "properties": {
                  "paid": {
                    "type": "integer"
                  },
                  "usable": {
                    "type": "integer"
                  },
                  "used": {
                    "type": "integer"
                  }
                }
              }
            }
          },
          "table_service": {
            "type": "boolean"
          },
          "open_balance": {
            "type": "integer",
            "description": "Amount in cents"
          },
          "past_due_since": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "suspend_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "grace_days": {
            "type": "integer",
            "example": 5
          },
          "pricing": {
            "type": "object",
            "properties": {
              "version": {
                "type": "integer"
              },
              "unit": {
                "$ref": "#/components/schemas/Prices"
              },
              "fees": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Fee"
                }
              },
              "effective_from": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "scheduled_pricing": {
            "type": [
              "object",
              "null"
            ]
          }
        }
      },
      "Card": {
        "type": "object",
        "properties": {
          "number": {
            "type": "string",
            "example": "4242424242424242"
          },
          "exp_month": {
            "type": "integer",
            "example": 12
          },
          "exp_year": {
            "type": "integer",
            "example": 2030
          },
          "cvc": {
            "type": "string",
            "example": "123"
          }
        },
        "required": [
          "number",
          "exp_month",
          "exp_year",
          "cvc"
        ]
      },
      "Integration": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "marketplace",
              "courier",
              "payments",
              "tax",
              "email",
              "sms"
            ]
          },
          "provider": {
            "type": "string",
            "example": "doordash"
          },
          "name": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "mock": {
            "type": "boolean"
          },
          "config": {
            "type": "object"
          }
        }
      }
    },
    "responses": {
      "E400": {
        "description": "Validation failed",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E401": {
        "description": "Missing or invalid token",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E402": {
        "description": "Payment declined, `seat_limit`, `feature_required` or `account_inactive`",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E403": {
        "description": "Not allowed (`manager_required`, `terminal_required`, `kitchen_display`, `web_only`, …)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E404": {
        "description": "Not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E409": {
        "description": "Conflict with the current state (e.g. `item_unavailable`: outside the item's or menu's hours)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E423": {
        "description": "Locked by another server (strict table lock)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E429": {
        "description": "Too many attempts",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}
