openapi: 3.0.3 info: title: Karma Common API description: |- # Introduction The Karma Common API is a centralized REST API for the Karma restaurant platform, providing secure access to core resources including inventory, orders, schedules, webhooks, and more. ## Features - **API Key Authentication**: Simple, long-lived access with bcrypt-hashed keys - **Comprehensive Access Control**: Fine-grained permissions for all resources - **Rate Limiting**: Automatic rate limiting based on your API key tier - **Webhook Support**: Real-time event notifications via webhooks - **TypeScript SDK**: Official SDK for JavaScript/TypeScript applications ## Get Started ### Installation Install the official TypeScript/JavaScript SDK: ```bash npm install @karmalicious/karma-api-js ``` ### Quick Start ```typescript import { createKarmaClient } from '@karmalicious/karma-api-js' const client = createKarmaClient({ apiKey: 'karma_live_your_api_key_here', baseUrl: 'https://common-api.karma.life' // optional, defaults to production }) // Fetch inventory items const inventory = await client.inventory.getInventoryItems({ locationId: 100, limit: 50 }) // Create an order const order = await client.orders.createOrder({ locationId: 100, orderChannel: 'POS', orderType: 'DINE_IN', orderDestination: 'KITCHEN', items: [ { itemId: 123, quantity: 2 } ] }) ``` ### NPM Package View the package on npm: [@karmalicious/karma-api-js](https://www.npmjs.com/package/@karmalicious/karma-api-js) ## Authentication All endpoints require an API key in the `X-API-Key` header: ``` X-API-Key: karma_live_your_api_key_here ``` API keys can be managed through the Karma Merchant Dashboard. ## Rate Limiting Rate limits are applied per API key based on your subscription tier: - **Standard**: 1,000 requests/hour - **Premium**: 10,000 requests/hour - **Unlimited**: 100,000 requests/hour Rate limit headers are included in all responses: - `X-RateLimit-Limit`: Total requests allowed - `X-RateLimit-Remaining`: Requests remaining - `X-RateLimit-Reset`: Unix timestamp when limit resets ## Support For questions or issues, contact the Karma team at hello@karma.life version: 20260131-1317-1 contact: name: Karma Team email: hello@karma.life components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: "API key authentication. Format: `karma_live_*` or `karma_dev_*`" BearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT bearer token authentication for user-specific endpoints schemas: {} paths: /api/v1/booking-waitlist/by-code/{code}: get: parameters: - schema: type: string in: path name: code required: true responses: "200": description: Default Response /api/v1/booking-waitlist/by-code/{code}/accept: post: parameters: - schema: type: string in: path name: code required: true responses: "200": description: Default Response /api/v1/booking-waitlist/by-code/{code}/decline: post: parameters: - schema: type: string in: path name: code required: true responses: "200": description: Default Response /api/v1/booking-waitlist/by-code/{code}/leave: delete: parameters: - schema: type: string in: path name: code required: true responses: "200": description: Default Response /api/v1/bookings/{id}/pre-order: post: parameters: - schema: type: string in: path name: id required: true responses: "200": description: Default Response get: parameters: - schema: type: string in: path name: id required: true responses: "200": description: Default Response /api/v1/bookings/by-code/{code}/members: get: parameters: - schema: type: string in: path name: code required: true responses: "200": description: Default Response post: parameters: - schema: type: string in: path name: code required: true responses: "200": description: Default Response /api/v1/locations/{locationId}/report-emails: get: parameters: - schema: type: string in: path name: locationId required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string data: type: object properties: emails: type: array items: type: string meta: type: object patch: requestBody: content: application/json: schema: type: object required: - emails properties: emails: type: array items: type: string required: true parameters: - schema: type: string in: path name: locationId required: true responses: "200": description: Default Response /api/v1/print-jobs/terminal-pre-check: post: requestBody: content: application/json: schema: type: object required: - locationId - tabId - terminalId - content properties: locationId: type: number tabId: type: string format: uuid terminalId: type: string format: uuid content: type: object required: - tableName - totalAmount - lineItems properties: tableName: type: string totalAmount: type: number lineItems: type: array items: type: object required: - name - price - modifications properties: name: type: string price: type: number modifications: type: array items: type: object properties: name: type: string price: type: number required: true responses: "200": description: Default Response /api/v1/printer-groups/{printerGroupId}/jobs/{jobId}/preview: get: parameters: - schema: type: string in: path name: printerGroupId required: true - schema: type: string in: path name: jobId required: true responses: "200": description: Default Response /api/v1/purchases/{purchaseIntentId}/picked-up: post: parameters: - schema: type: string in: path name: purchaseIntentId required: true responses: "200": description: Default Response /api/v1/purchases/refund-reasons: get: parameters: - schema: type: number in: query name: locationId required: true responses: "200": description: Default Response /api/v1/tabs/{id}/anonymous-members: post: parameters: - schema: type: string in: path name: id required: true responses: "200": description: Default Response /api/v1/tabs/{tabId}/recent-purchase-intent: get: parameters: - schema: type: string in: path name: tabId required: true responses: "200": description: Default Response /api/v1/tabs/close-all: post: responses: "200": description: Default Response /api/v1/terminals/{id}: put: parameters: - schema: type: string in: path name: id required: true responses: "200": description: Default Response delete: parameters: - schema: type: string in: path name: id required: true responses: "200": description: Default Response /api/v1/alerts: get: summary: List alerts tags: - Alerts description: |- List alerts with optional filtering **Permissions:** 🔵 `alerts.read` parameters: - schema: type: number in: query name: locationId required: false description: Filter by location ID - schema: type: string enum: - info - warning - error - critical in: query name: severity required: false description: Filter by severity - schema: type: string enum: - active - acknowledged - resolved in: query name: status required: false description: Filter by status - schema: type: string in: query name: alertType required: false description: Filter by alert type - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: number minimum: 1 maximum: 100 default: 20 in: query name: limit required: false description: Items per page responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: alerts: type: array items: type: object properties: id: type: string description: Unique alert ID (UUID) locationId: type: number description: Location ID where alert occurred alertType: type: string description: Type of alert (e.g., "printer_offline", "payment_failed") severity: type: string enum: - info - warning - error - critical description: Alert severity level title: type: string description: Alert title message: type: string nullable: true description: Detailed alert message details: type: object nullable: true description: Additional alert details stackTrace: type: string nullable: true description: Stack trace (for errors) context: type: object nullable: true description: Contextual information latestStatus: type: string enum: - active - acknowledged - resolved description: Current alert status resolvedAt: type: string format: date-time nullable: true description: Resolution timestamp resolvedBy: type: number nullable: true description: User ID who resolved alert acknowledgedAt: type: string format: date-time nullable: true description: Acknowledgement timestamp acknowledgedBy: type: number nullable: true description: User ID who acknowledged alert createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - id - locationId - alertType - severity - title - latestStatus - createdAt - updatedAt pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages required: - alerts - pagination meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/alerts/{id}: get: summary: Get alert tags: - Alerts description: |- Get a single alert by ID **Permissions:** 🔵 `alerts.read` parameters: - schema: type: string format: uuid in: path name: id required: true description: Alert ID (UUID) responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string description: Unique alert ID (UUID) locationId: type: number description: Location ID where alert occurred alertType: type: string description: Type of alert (e.g., "printer_offline", "payment_failed") severity: type: string enum: - info - warning - error - critical description: Alert severity level title: type: string description: Alert title message: type: string nullable: true description: Detailed alert message details: type: object nullable: true description: Additional alert details stackTrace: type: string nullable: true description: Stack trace (for errors) context: type: object nullable: true description: Contextual information latestStatus: type: string enum: - active - acknowledged - resolved description: Current alert status resolvedAt: type: string format: date-time nullable: true description: Resolution timestamp resolvedBy: type: number nullable: true description: User ID who resolved alert acknowledgedAt: type: string format: date-time nullable: true description: Acknowledgement timestamp acknowledgedBy: type: number nullable: true description: User ID who acknowledged alert createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - id - locationId - alertType - severity - title - latestStatus - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 patch: summary: Update alert status tags: - Alerts description: |- Update alert status (acknowledge or resolve) **Permissions:** 🟠 `alerts.update` requestBody: content: application/json: schema: type: object properties: status: type: string enum: - acknowledged - resolved description: New status (cannot reopen once resolved) required: - status required: true parameters: - schema: type: string format: uuid in: path name: id required: true description: Alert ID (UUID) responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string description: Unique alert ID (UUID) locationId: type: number description: Location ID where alert occurred alertType: type: string description: Type of alert (e.g., "printer_offline", "payment_failed") severity: type: string enum: - info - warning - error - critical description: Alert severity level title: type: string description: Alert title message: type: string nullable: true description: Detailed alert message details: type: object nullable: true description: Additional alert details stackTrace: type: string nullable: true description: Stack trace (for errors) context: type: object nullable: true description: Contextual information latestStatus: type: string enum: - active - acknowledged - resolved description: Current alert status resolvedAt: type: string format: date-time nullable: true description: Resolution timestamp resolvedBy: type: number nullable: true description: User ID who resolved alert acknowledgedAt: type: string format: date-time nullable: true description: Acknowledgement timestamp acknowledgedBy: type: number nullable: true description: User ID who acknowledged alert createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - id - locationId - alertType - severity - title - latestStatus - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /internal/alerts/{id}/emit: post: summary: Emit alert.created event tags: - Alerts description: Emit alert.created Ably event for an existing alert (internal use only — called by printer-service) parameters: - schema: type: string format: uuid in: path name: id required: true description: Alert ID (UUID) responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: emitted: type: boolean required: - emitted required: - status - data "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/analytics/batch: post: tags: - Analytics description: Execute multiple analytics queries in parallel requestBody: content: application/json: schema: type: object properties: queries: type: array items: type: object properties: queryType: type: string enum: - sales_hourly - channels - top_items - location_performance description: Query type locationId: type: number description: Location ID startDate: type: string format: date-time description: Start date endDate: type: string format: date-time description: End date granularity: type: string enum: - hour - day - week description: Time granularity includeChildren: type: boolean description: Include child locations filters: type: object description: Additional filters required: - queryType - locationId required: - queries required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: charts: type: array items: type: object properties: id: type: string description: Unique chart ID title: type: string description: Chart title type: type: string enum: - line - bar - area - pie - metric - table description: Chart visualization type data: type: array items: type: object properties: label: type: string description: Data point label value: type: number description: Numeric value (prices in cents) timestamp: type: string format: date-time description: Optional timestamp metadata: type: object additionalProperties: true properties: orderCount: type: number description: Number of orders orders: type: number description: Number of orders (alias) itemId: type: number description: Item ID unitsSold: type: number description: Units sold description: Additional metadata required: - label - value description: Chart data points metadata: type: object properties: total: type: number description: Total value (cents) change: type: number description: Change from previous period changePercent: type: number description: Percentage change unit: type: string description: Unit of measurement currency: type: string description: Currency code (e.g., SEK) lastUpdated: type: string format: date-time description: Last update timestamp required: - id - title - type - data description: Successful query results errors: type: array items: type: object properties: queryIndex: type: number queryType: type: string error: type: string description: Failed queries (if any) meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number totalQueries: type: number description: Total queries requested successfulQueries: type: number description: Successful queries failedQueries: type: number description: Failed queries "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/analytics/channels: get: tags: - Analytics description: Get channel behavior metrics (POS, App, Kiosk, Delivery, QR) parameters: - schema: type: number in: query name: locationId required: true description: Location ID - schema: type: string format: date-time in: query name: startDate required: false description: Start date (ISO 8601) - schema: type: string format: date-time in: query name: endDate required: false description: End date (ISO 8601) - schema: type: boolean default: false in: query name: includeChildren required: false description: Include child locations responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: array items: type: object properties: orderChannel: type: string description: Channel name (POS, App, QR, etc.) orderCount: type: number description: Number of orders revenue: type: number description: Total revenue in cents averageOrderValue: type: number description: Average order value in cents uniqueCustomers: type: number description: Unique customer count conversionRate: type: number nullable: true description: Conversion rate (null if unavailable) meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number cacheHit: type: boolean bytesProcessed: type: number "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/analytics/dashboard: get: tags: - Analytics description: Get comprehensive dashboard metrics in a single call. Returns sales inc/ex VAT, orders, products, tips, refunds, discounts, AOV, VAT breakdown, time series, top products, top categories, and channel breakdown. parameters: - schema: type: number in: query name: locationId required: true description: Location ID - schema: type: string format: date-time in: query name: startDate required: false description: Start date (ISO 8601) - schema: type: string format: date-time in: query name: endDate required: false description: End date (ISO 8601) - schema: type: boolean default: false in: query name: includeChildren required: false description: Include child locations - schema: type: string enum: - hour - day - week default: hour in: query name: granularity required: false description: Time series granularity - schema: type: string in: query name: productSearch required: false description: Search filter for product titles - schema: type: number default: 10 in: query name: productLimit required: false description: Max products to return (default 10, max 500) - schema: type: string in: query name: tableGroupIds required: false description: Comma-separated list of table group IDs (storefront_qr_code_groups.id) to restrict results to. When set, excludes orders without a QR code (e.g. pickup, delivery). - schema: type: string in: query name: costCenterIds required: false description: Comma-separated list of cost center IDs (cost_centers.id) to restrict results to. Matches on COALESCE(tabs.cost_center_id, storefront_qr_codes.cost_center_id) — tab override beats table default. Orders without a cost center are excluded when this filter is active. responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: metrics: type: object properties: salesIncVat: type: number description: Gross sales including VAT (cents) — pre-discount salesExVat: type: number description: Gross sales excluding VAT (cents) — pre-discount totalVat: type: number description: Total VAT amount (cents) netSalesIncVat: type: number description: Net sales including VAT (cents) — post-discount, post-refund, matches SIE netSalesExVat: type: number description: Net sales excluding VAT (cents) — post-discount, post-refund, matches SIE netTotalVat: type: number description: Net VAT amount (cents) orderCount: type: number description: Total number of orders productCount: type: number description: Total products sold tipsTotal: type: number description: Total tips (cents) refundCount: type: number description: Number of refunds refundTotal: type: number description: Total refunded amount (cents) discountCount: type: number description: Number of discounted line items discountTotal: type: number description: Total discounts applied (cents) aov: type: number description: Average order value (cents) vatBreakdown: type: array items: type: object properties: vatRateBasisPoints: type: number description: VAT rate in basis points (e.g. 2500 = 25%) salesIncVat: type: number description: Sales including VAT for this rate (cents) vatAmount: type: number description: VAT amount for this rate (cents) salesExVat: type: number description: Sales excluding VAT for this rate (cents) orderCount: type: number description: Orders with items at this rate timeSeries: type: array description: "Time-series buckets with two parallel axes: payment time (bucketed on purchases.purchased_at — matches SIE/accounting) and kitchen time (bucketed on kitchen_dispatch_items.created_at with fallback to purchased_at — when items were sent to the kitchen). Both series cover the same set of confirmed purchases, rebucketed on different timestamps. The kitchen series filters on kitchen-time too, so late payments can retroactively shift it." items: type: object properties: label: type: string description: Time label (e.g. "14:00" or "2025-03-25") paymentSalesIncVat: type: number description: "Payment-time axis: sales inc VAT (cents)" paymentSalesExVat: type: number description: "Payment-time axis: sales ex VAT (cents)" paymentOrders: type: number description: "Payment-time axis: number of orders" kitchenSalesIncVat: type: number description: "Kitchen-time axis: sales inc VAT (cents)" kitchenSalesExVat: type: number description: "Kitchen-time axis: sales ex VAT (cents)" kitchenOrders: type: number description: "Kitchen-time axis: number of orders" topProducts: type: array items: type: object properties: title: type: string description: Product title originItemId: type: number nullable: true description: Inventory item ID unitsSold: type: number description: Total units sold revenue: type: number description: Total revenue inc VAT (cents) revenueExVat: type: number description: Total revenue ex VAT (cents) topCategories: type: array items: type: object properties: categoryKey: type: string description: Category tag key categoryName: type: string description: Human-readable category name unitsSold: type: number description: Total units sold revenue: type: number description: Total revenue inc VAT (cents) revenueExVat: type: number description: Total revenue ex VAT (cents) channels: type: array items: type: object properties: channel: type: string description: Channel name (POS, ONLINE, KIOSK, etc.) orderCount: type: number description: Orders via this channel revenue: type: number description: Revenue inc VAT (cents) revenueExVat: type: number description: Revenue ex VAT (cents) aov: type: number description: Average order value (cents) uniqueCustomers: type: number description: Unique customer count topStaff: type: array items: type: object properties: retailUserId: type: number description: Staff user ID name: type: string description: Staff user name orderCount: type: number description: Orders handled revenue: type: number description: Revenue inc VAT (cents) revenueExVat: type: number description: Revenue ex VAT (cents) topProductsByCategory: type: array description: Top products grouped by primary category (CATEGORY_PRIMARY tag). Returns up to 5 products per category, sorted by revenue. items: type: object properties: categoryKey: type: string description: Category tag key categoryName: type: string description: Human-readable category name products: type: array items: type: object properties: title: type: string description: Product title originItemId: type: number nullable: true description: Inventory item ID unitsSold: type: number description: Total units sold revenue: type: number description: Total revenue inc VAT (cents) revenueExVat: type: number description: Total revenue ex VAT (cents) costCenters: type: array description: Revenue grouped by COALESCE(tab.cost_center_id, qr_code.cost_center_id). Rows with no cost center are returned with costCenterId=null. items: type: object properties: costCenterId: type: number nullable: true description: Cost center ID (null when no cost center is associated) name: type: string nullable: true description: Cost center display name (null when costCenterId is null) orderCount: type: number description: Orders attributed to this cost center unitsSold: type: number description: Total units sold revenue: type: number description: Revenue inc VAT (cents) revenueExVat: type: number description: Revenue ex VAT (cents) tableGroups: type: array description: Revenue grouped by storefront_qr_codes.group_id. Orders without a QR code (pickup, delivery, etc.) are returned with tableGroupId=null. items: type: object properties: tableGroupId: type: number nullable: true description: Table group ID (null for orders without a QR code) name: type: string nullable: true description: Table group display name (null when tableGroupId is null) orderCount: type: number description: Orders attributed to this table group unitsSold: type: number description: Total units sold revenue: type: number description: Revenue inc VAT (cents) revenueExVat: type: number description: Revenue ex VAT (cents) meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/analytics/datastream-latency: get: tags: - Analytics description: Get DataStream latency metrics parameters: - schema: type: number in: query name: locationId required: true description: Location ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: avgLatencyMs: type: number description: Average latency in milliseconds p50LatencyMs: type: number description: P50 latency in milliseconds p95LatencyMs: type: number description: P95 latency in milliseconds p99LatencyMs: type: number description: P99 latency in milliseconds lastOrderLatencyMs: type: number nullable: true description: Last order latency in milliseconds meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number cacheHit: type: boolean bytesProcessed: type: number "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/analytics/drilldown: get: tags: - Analytics description: Get drill-down analytics (Location → Hour → Item) parameters: - schema: type: number in: query name: locationId required: true description: Location ID - schema: type: string format: date-time in: query name: startDate required: false description: Start date (ISO 8601) - schema: type: string format: date-time in: query name: endDate required: false description: End date (ISO 8601) - schema: type: number minimum: 0 maximum: 23 in: query name: hour required: false description: Hour of day (0-23) - schema: type: number in: query name: itemId required: false description: Item ID for detailed orders responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: level: type: string enum: - location - hour - item description: Current drill-down level data: type: array items: type: object properties: label: type: string description: Data point label value: type: number description: Numeric value (prices in cents) timestamp: type: string format: date-time description: Optional timestamp metadata: type: object additionalProperties: true properties: orderCount: type: number description: Number of orders orders: type: number description: Number of orders (alias) itemId: type: number description: Item ID unitsSold: type: number description: Units sold description: Additional metadata required: - label - value description: Drill-down data points metadata: type: object properties: parentLocationId: type: number description: Parent location ID parentLocationName: type: string description: Parent location name hour: type: number description: Hour of day (if drilling into hour) itemId: type: number description: Item ID (if drilling into item) required: - level - data - metadata meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/analytics/locations: get: tags: - Analytics description: Get location performance with hierarchy parameters: - schema: type: number in: query name: locationId required: true description: Parent location ID - schema: type: string format: date-time in: query name: startDate required: false description: Start date (ISO 8601) - schema: type: string format: date-time in: query name: endDate required: false description: End date (ISO 8601) - schema: type: boolean default: false in: query name: includeChildren required: false description: Include child locations responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: array items: type: object properties: locationId: type: number description: Location ID locationName: type: string description: Location name totalSales: type: number description: Total sales in cents totalOrders: type: number description: Total orders averageOrderValue: type: number description: Average order value in cents hourlyBreakdown: type: array items: type: object properties: label: type: string description: Data point label value: type: number description: Numeric value (prices in cents) timestamp: type: string format: date-time description: Optional timestamp metadata: type: object additionalProperties: true properties: orderCount: type: number description: Number of orders orders: type: number description: Number of orders (alias) itemId: type: number description: Item ID unitsSold: type: number description: Units sold description: Additional metadata required: - label - value description: Hourly sales breakdown alerts: type: array items: type: string description: Performance alerts meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number cacheHit: type: boolean bytesProcessed: type: number "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/analytics/overview: get: tags: - Analytics description: Get overview dashboard with summary and charts parameters: - schema: type: number in: query name: locationId required: true description: Location ID - schema: type: string format: date-time in: query name: startDate required: false description: Start date (ISO 8601) - schema: type: string format: date-time in: query name: endDate required: false description: End date (ISO 8601) - schema: type: boolean default: false in: query name: includeChildren required: false description: Include child locations responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: summary: type: object properties: totalSales: type: number description: Total sales in cents totalOrders: type: number description: Total orders averageOrderValue: type: number description: Average order value in cents topChannel: type: string description: Top performing channel lastUpdated: type: string format: date-time description: Last update charts: type: array items: type: object properties: id: type: string description: Unique chart ID title: type: string description: Chart title type: type: string enum: - line - bar - area - pie - metric - table description: Chart visualization type data: type: array items: type: object properties: label: type: string description: Data point label value: type: number description: Numeric value (prices in cents) timestamp: type: string format: date-time description: Optional timestamp metadata: type: object additionalProperties: true properties: orderCount: type: number description: Number of orders orders: type: number description: Number of orders (alias) itemId: type: number description: Item ID unitsSold: type: number description: Units sold description: Additional metadata required: - label - value description: Chart data points metadata: type: object properties: total: type: number description: Total value (cents) change: type: number description: Change from previous period changePercent: type: number description: Percentage change unit: type: string description: Unit of measurement currency: type: string description: Currency code (e.g., SEK) lastUpdated: type: string format: date-time description: Last update timestamp required: - id - title - type - data description: Dashboard charts dataStreamLatency: type: number nullable: true description: DataStream latency in milliseconds meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/analytics/sales: get: tags: - Analytics description: Get sales metrics with hourly breakdown parameters: - schema: type: number in: query name: locationId required: true description: Location ID - schema: type: string format: date-time in: query name: startDate required: false description: Start date (ISO 8601) - schema: type: string format: date-time in: query name: endDate required: false description: End date (ISO 8601) - schema: type: boolean default: false in: query name: includeChildren required: false description: Include child locations - schema: type: string enum: - hour - day - week default: hour in: query name: granularity required: false description: Time granularity responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: totalSales: type: number description: Total sales in cents totalOrders: type: number description: Total order count totalItemsSold: type: number description: Total items sold count averageOrderValue: type: number description: Average order value in cents hourlySales: type: array items: type: object properties: label: type: string description: Data point label value: type: number description: Numeric value (prices in cents) timestamp: type: string format: date-time description: Optional timestamp metadata: type: object additionalProperties: true properties: orderCount: type: number description: Number of orders orders: type: number description: Number of orders (alias) itemId: type: number description: Item ID unitsSold: type: number description: Units sold description: Additional metadata required: - label - value description: Hourly/daily sales breakdown topItems: type: array items: type: object properties: label: type: string description: Data point label value: type: number description: Numeric value (prices in cents) timestamp: type: string format: date-time description: Optional timestamp metadata: type: object additionalProperties: true properties: orderCount: type: number description: Number of orders orders: type: number description: Number of orders (alias) itemId: type: number description: Item ID unitsSold: type: number description: Units sold description: Additional metadata required: - label - value description: Top selling items channelBreakdown: type: array items: type: object properties: label: type: string description: Data point label value: type: number description: Numeric value (prices in cents) timestamp: type: string format: date-time description: Optional timestamp metadata: type: object additionalProperties: true properties: orderCount: type: number description: Number of orders orders: type: number description: Number of orders (alias) itemId: type: number description: Item ID unitsSold: type: number description: Units sold description: Additional metadata required: - label - value description: Sales breakdown by channel required: - totalSales - totalOrders - totalItemsSold - averageOrderValue - hourlySales - topItems - channelBreakdown meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number cacheHit: type: boolean description: Whether result was cached bytesProcessed: type: number description: BigQuery bytes processed "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/analytics/tips-by-staff: get: tags: - Analytics description: Get tips totals per staff for the period. Tips are split proportionally across staff based on each staff member's share of committed-item revenue on the same tab. Unattributed share (no staff on tab) is returned with retailUserId = null. parameters: - schema: type: number in: query name: locationId required: true description: Location ID - schema: type: string format: date-time in: query name: startDate required: false description: Start date (ISO 8601) - schema: type: string format: date-time in: query name: endDate required: false description: End date (ISO 8601) - schema: type: boolean default: false in: query name: includeChildren required: false description: Include child locations - schema: type: string in: query name: tableGroupIds required: false description: Comma-separated list of table group IDs to restrict to. responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: summary: type: object properties: tipsTotal: type: number description: Total tips across all purchases (cents) tippedOrderCount: type: number description: Number of purchases that included a tip orderCount: type: number description: Total confirmed purchases in range averageTip: type: number description: Average tip per tipped purchase (cents) staff: type: array items: type: object properties: retailUserId: type: - "null" - number description: Staff user ID, null = unattributed/self-service name: type: - "null" - string description: Staff user name tipsTotal: type: number description: Allocated tips for this staff (cents) orderCount: type: number description: Tipped purchases this staff received a share of meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/bookings: get: summary: List bookings tags: - Bookings description: |- List bookings with optional filtering and pagination **Permissions:** 🔵 `bookings.read` parameters: - schema: type: number in: query name: locationId required: false description: Filter by location ID - schema: type: string in: query name: tableId required: false description: Filter by table ID - schema: type: string enum: - pending - confirmed - checked_in - seated - completed - cancelled - no_show in: query name: status required: false description: Booking status - schema: type: string format: date in: query name: bookingDate required: false description: Filter by exact date - schema: type: string format: date in: query name: startDate required: false description: Filter by start date (inclusive) - schema: type: string format: date in: query name: endDate required: false description: Filter by end date (inclusive) - schema: type: number in: query name: userId required: false description: Filter by user ID - schema: type: string in: query name: confirmationCode required: false description: Filter by confirmation code - schema: type: string enum: - direct - website - phone - walkin - third_party in: query name: bookingSource required: false description: Source of the booking - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: number minimum: 1 maximum: 100 default: 50 in: query name: limit required: false description: Items per page responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: bookings: type: array items: type: object properties: id: type: string format: uuid description: Unique booking ID locationId: type: number description: Location ID tableId: type: string format: uuid nullable: true description: Table/resource ID (QR code UUID) bookingDate: type: string format: date description: Date of the booking (YYYY-MM-DD) startTime: type: string description: Start time (HH:MM:SS) endTime: type: string description: End time (HH:MM:SS) timezone: type: string description: Timezone for the booking primaryUserId: type: - "null" - number description: Primary guest user ID (null for walk-ins) guestCount: type: number minimum: 0 description: Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests) occasion: type: string enum: - none - birthday - anniversary - business - date - celebration - other description: Occasion for the booking specialRequests: type: string nullable: true description: Guest special requests internalNotes: type: string nullable: true description: Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array. notes: type: array description: Staff-only notes attached to this booking (entity_type=booking in the notes table). items: type: object properties: uuid: type: string format: uuid note: type: string sortOrder: type: number createdByRetailerUserId: type: number nullable: true updatedByRetailerUserId: type: number nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - uuid - note - sortOrder - createdAt - updatedAt status: type: string enum: - pending - confirmed - checked_in - seated - completed - cancelled - no_show description: Booking status paymentType: type: string enum: - none - deposit - full_prepayment description: Payment type required for booking depositAmountCents: type: number nullable: true description: Deposit amount in cents purchaseId: type: number nullable: true description: Linked purchase ID confirmationCode: type: string description: Unique confirmation code for guest bookingSource: type: string enum: - direct - website - phone - walkin - third_party description: Source of the booking estimatedRevenueCents: type: number nullable: true description: AI-estimated revenue guestName: type: string nullable: true description: Guest contact name guestEmail: type: string nullable: true description: Guest contact email guestPhone: type: string nullable: true description: Guest contact phone createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp confirmedAt: type: string format: date-time nullable: true description: Confirmation timestamp seatedAt: type: string format: date-time nullable: true description: Seated timestamp completedAt: type: string format: date-time nullable: true description: Completion timestamp cancelledAt: type: string format: date-time nullable: true description: Cancellation timestamp tabId: type: string nullable: true description: UUID of the linked tab (if any) defaultTabStrategy: type: string enum: - single - per_resource description: Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat. resources: type: array description: Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`. items: type: object description: A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40). properties: qrCodeId: type: string format: uuid description: storefront_qr_codes.uuid for the reserved resource isPrimary: type: boolean description: True for the primary/anchor resource of the booking position: type: integer minimum: 0 description: Stable ordering index of this resource within the booking (0-based) required: - qrCodeId - isPrimary - position userName: type: string nullable: true description: Primary guest name userEmail: type: string nullable: true description: Primary guest email userPhone: type: string nullable: true description: Primary guest phone tableName: type: string nullable: true description: Table name required: - id - locationId - bookingDate - startTime - endTime - timezone - guestCount - status - confirmationCode - createdAt - updatedAt - defaultTabStrategy - resources pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages required: - bookings - pagination meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: summary: Create booking tags: - Bookings description: >- Create a new booking. The response always includes a linked `tab` (the booking creates a `pre_arrival` tab atomically) so integrations can begin committing orders against `data.tab.id` immediately. Pass `seatImmediately: true` in the body to atomically transition the new booking to `seated` and open its tab in a single call (recommended for walk-in flows). When `seatImmediately` is true and the booking has unpaid required items or its table already has an open tab, the booking is still created but seating is skipped and `seatWarning` is returned. **Permissions:** 🟢 `bookings.create` requestBody: content: application/json: schema: type: object properties: locationId: type: number description: Location ID tableId: type: - string - "null" format: uuid description: Legacy single-resource ID (kept for backwards compat). When `tableIds` is provided it takes precedence; otherwise `tableId` is folded into a single-element resource set. tableIds: type: array description: Multi-resource booking (Phase 40). Array of storefront_qr_code UUIDs to reserve. The first entry is treated as primary. When provided, supersedes `tableId`. items: type: string format: uuid minItems: 1 defaultTabStrategy: type: string enum: - single - per_resource description: Tab strategy locked in at booking time (Phase 40). `single` (default) — one shared tab across all reserved resources. `per_resource` — one tab per resource opened on seat. default: single bookingDate: type: string format: date description: Date of the booking startTime: type: string description: Start time (HH:MM) endTime: type: string description: End time (HH:MM) timezone: type: string description: Timezone (e.g., Europe/Stockholm) primaryUserId: type: - number - "null" description: Primary guest user ID (null for walk-ins) guestCount: type: number minimum: 0 description: Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests) occasion: type: string enum: - none - birthday - anniversary - business - date - celebration - other description: Occasion for the booking specialRequests: type: string description: Guest special requests internalNotes: type: string description: Staff-only notes paymentType: type: string enum: - none - deposit - full_prepayment description: Payment type required for booking depositAmountCents: type: number description: Deposit amount in cents bookingSource: type: string enum: - direct - website - phone - walkin - third_party description: Source of the booking guestName: type: string description: Guest contact name guestEmail: type: string description: Guest contact email guestPhone: type: string description: Guest contact phone seatImmediately: type: boolean description: If true, immediately seat the booking after creation. Requires a table assignment. Will check for conflicting open tabs on the table. required: - locationId - bookingDate - startTime - endTime - timezone - guestCount required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Unique booking ID locationId: type: number description: Location ID tableId: type: string format: uuid nullable: true description: Table/resource ID (QR code UUID) bookingDate: type: string format: date description: Date of the booking (YYYY-MM-DD) startTime: type: string description: Start time (HH:MM:SS) endTime: type: string description: End time (HH:MM:SS) timezone: type: string description: Timezone for the booking primaryUserId: type: - "null" - number description: Primary guest user ID (null for walk-ins) guestCount: type: number minimum: 0 description: Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests) occasion: type: string enum: - none - birthday - anniversary - business - date - celebration - other description: Occasion for the booking specialRequests: type: string nullable: true description: Guest special requests internalNotes: type: string nullable: true description: Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array. notes: type: array description: Staff-only notes attached to this booking (entity_type=booking in the notes table). items: type: object properties: uuid: type: string format: uuid note: type: string sortOrder: type: number createdByRetailerUserId: type: number nullable: true updatedByRetailerUserId: type: number nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - uuid - note - sortOrder - createdAt - updatedAt status: type: string enum: - pending - confirmed - checked_in - seated - completed - cancelled - no_show description: Booking status paymentType: type: string enum: - none - deposit - full_prepayment description: Payment type required for booking depositAmountCents: type: number nullable: true description: Deposit amount in cents purchaseId: type: number nullable: true description: Linked purchase ID confirmationCode: type: string description: Unique confirmation code for guest bookingSource: type: string enum: - direct - website - phone - walkin - third_party description: Source of the booking estimatedRevenueCents: type: number nullable: true description: AI-estimated revenue guestName: type: string nullable: true description: Guest contact name guestEmail: type: string nullable: true description: Guest contact email guestPhone: type: string nullable: true description: Guest contact phone createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp confirmedAt: type: string format: date-time nullable: true description: Confirmation timestamp seatedAt: type: string format: date-time nullable: true description: Seated timestamp completedAt: type: string format: date-time nullable: true description: Completion timestamp cancelledAt: type: string format: date-time nullable: true description: Cancellation timestamp tabId: type: string nullable: true description: UUID of the linked tab (if any) defaultTabStrategy: type: string enum: - single - per_resource description: Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat. resources: type: array description: Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`. items: type: object description: A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40). properties: qrCodeId: type: string format: uuid description: storefront_qr_codes.uuid for the reserved resource isPrimary: type: boolean description: True for the primary/anchor resource of the booking position: type: integer minimum: 0 description: Stable ordering index of this resource within the booking (0-based) required: - qrCodeId - isPrimary - position userName: type: string nullable: true description: Primary guest name userEmail: type: string nullable: true description: Primary guest email userPhone: type: string nullable: true description: Primary guest phone tableName: type: string nullable: true description: Table name tab: type: object description: Linked tab created with the booking. State is `pre_arrival` for normal bookings, `started` when seatImmediately=true succeeds, or `initiated` for walk-ins. properties: id: type: string format: uuid description: Tab UUID — use this to commit orders against the tab. tabMemberId: type: string format: uuid nullable: true description: Tab member UUID for the primary guest (null when the booking has no primary user, e.g. walk-ins without a guest record). requiresPayment: type: boolean description: True if the booking has required items (from a booking group) that need to be paid before the guest can be seated. totalRequiredItemsCents: type: number description: Total cents of required items added to the linked tab. Zero when the booking has no required items. seated: type: boolean description: Only present when `seatImmediately` was passed in the request body. True if the booking was successfully transitioned to `seated` and its tab is now open. seatWarning: type: string description: Only present when `seatImmediately` was passed and seating was skipped (e.g. payment required, or the table already has another open tab). The booking is still created. meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/bookings/{id}: get: summary: Get booking tags: - Bookings description: |- Get a single booking by ID **Permissions:** 🔵 `bookings.read` parameters: - schema: type: string format: uuid in: path name: id required: true description: Booking ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Unique booking ID locationId: type: number description: Location ID tableId: type: string format: uuid nullable: true description: Table/resource ID (QR code UUID) bookingDate: type: string format: date description: Date of the booking (YYYY-MM-DD) startTime: type: string description: Start time (HH:MM:SS) endTime: type: string description: End time (HH:MM:SS) timezone: type: string description: Timezone for the booking primaryUserId: type: - "null" - number description: Primary guest user ID (null for walk-ins) guestCount: type: number minimum: 0 description: Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests) occasion: type: string enum: - none - birthday - anniversary - business - date - celebration - other description: Occasion for the booking specialRequests: type: string nullable: true description: Guest special requests internalNotes: type: string nullable: true description: Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array. notes: type: array description: Staff-only notes attached to this booking (entity_type=booking in the notes table). items: type: object properties: uuid: type: string format: uuid note: type: string sortOrder: type: number createdByRetailerUserId: type: number nullable: true updatedByRetailerUserId: type: number nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - uuid - note - sortOrder - createdAt - updatedAt status: type: string enum: - pending - confirmed - checked_in - seated - completed - cancelled - no_show description: Booking status paymentType: type: string enum: - none - deposit - full_prepayment description: Payment type required for booking depositAmountCents: type: number nullable: true description: Deposit amount in cents purchaseId: type: number nullable: true description: Linked purchase ID confirmationCode: type: string description: Unique confirmation code for guest bookingSource: type: string enum: - direct - website - phone - walkin - third_party description: Source of the booking estimatedRevenueCents: type: number nullable: true description: AI-estimated revenue guestName: type: string nullable: true description: Guest contact name guestEmail: type: string nullable: true description: Guest contact email guestPhone: type: string nullable: true description: Guest contact phone createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp confirmedAt: type: string format: date-time nullable: true description: Confirmation timestamp seatedAt: type: string format: date-time nullable: true description: Seated timestamp completedAt: type: string format: date-time nullable: true description: Completion timestamp cancelledAt: type: string format: date-time nullable: true description: Cancellation timestamp tabId: type: string nullable: true description: UUID of the linked tab (if any) defaultTabStrategy: type: string enum: - single - per_resource description: Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat. resources: type: array description: Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`. items: type: object description: A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40). properties: qrCodeId: type: string format: uuid description: storefront_qr_codes.uuid for the reserved resource isPrimary: type: boolean description: True for the primary/anchor resource of the booking position: type: integer minimum: 0 description: Stable ordering index of this resource within the booking (0-based) required: - qrCodeId - isPrimary - position userName: type: string nullable: true description: Primary guest name userEmail: type: string nullable: true description: Primary guest email userPhone: type: string nullable: true description: Primary guest phone tableName: type: string nullable: true description: Table name required: - id - locationId - bookingDate - startTime - endTime - timezone - guestCount - status - confirmationCode - createdAt - updatedAt - defaultTabStrategy - resources meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: summary: Update booking tags: - Bookings description: |- Update an existing booking **Permissions:** 🟠 `bookings.update` requestBody: content: application/json: schema: type: object properties: tableId: type: string format: uuid nullable: true description: Legacy single-resource ID (kept for backwards compat). When `tableIds` is provided it takes precedence; otherwise `tableId` replaces the booking resource set with a single entry. tableIds: type: array description: Multi-resource booking (Phase 40). Array of storefront_qr_code UUIDs that replaces the booking resource set. The first entry is treated as primary. When provided, supersedes `tableId`. items: type: string format: uuid minItems: 1 defaultTabStrategy: type: string enum: - single - per_resource description: Change the booking tab strategy pre-seat (Phase 40). Staff can flip between `single` and `per_resource` until the booking is seated. confirmRemoveActiveTab: type: boolean default: false description: "Gates the destructive path in R8 (Phase 40): when shrinking `tableIds` would remove a resource that already has an active tab, the API only proceeds if this flag is true. Without it, the update is rejected with a 409 so staff can confirm." bookingDate: type: string format: date description: Date of the booking startTime: type: string description: Start time endTime: type: string description: End time guestCount: type: number minimum: 0 description: Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests) occasion: type: string enum: - none - birthday - anniversary - business - date - celebration - other description: Occasion for the booking specialRequests: type: string description: Guest special requests internalNotes: type: string description: Staff-only notes paymentType: type: string enum: - none - deposit - full_prepayment description: Payment type required for booking depositAmountCents: type: number description: Deposit amount in cents parameters: - schema: type: string format: uuid in: path name: id required: true description: Booking ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Unique booking ID locationId: type: number description: Location ID tableId: type: string format: uuid nullable: true description: Table/resource ID (QR code UUID) bookingDate: type: string format: date description: Date of the booking (YYYY-MM-DD) startTime: type: string description: Start time (HH:MM:SS) endTime: type: string description: End time (HH:MM:SS) timezone: type: string description: Timezone for the booking primaryUserId: type: - "null" - number description: Primary guest user ID (null for walk-ins) guestCount: type: number minimum: 0 description: Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests) occasion: type: string enum: - none - birthday - anniversary - business - date - celebration - other description: Occasion for the booking specialRequests: type: string nullable: true description: Guest special requests internalNotes: type: string nullable: true description: Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array. notes: type: array description: Staff-only notes attached to this booking (entity_type=booking in the notes table). items: type: object properties: uuid: type: string format: uuid note: type: string sortOrder: type: number createdByRetailerUserId: type: number nullable: true updatedByRetailerUserId: type: number nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - uuid - note - sortOrder - createdAt - updatedAt status: type: string enum: - pending - confirmed - checked_in - seated - completed - cancelled - no_show description: Booking status paymentType: type: string enum: - none - deposit - full_prepayment description: Payment type required for booking depositAmountCents: type: number nullable: true description: Deposit amount in cents purchaseId: type: number nullable: true description: Linked purchase ID confirmationCode: type: string description: Unique confirmation code for guest bookingSource: type: string enum: - direct - website - phone - walkin - third_party description: Source of the booking estimatedRevenueCents: type: number nullable: true description: AI-estimated revenue guestName: type: string nullable: true description: Guest contact name guestEmail: type: string nullable: true description: Guest contact email guestPhone: type: string nullable: true description: Guest contact phone createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp confirmedAt: type: string format: date-time nullable: true description: Confirmation timestamp seatedAt: type: string format: date-time nullable: true description: Seated timestamp completedAt: type: string format: date-time nullable: true description: Completion timestamp cancelledAt: type: string format: date-time nullable: true description: Cancellation timestamp tabId: type: string nullable: true description: UUID of the linked tab (if any) defaultTabStrategy: type: string enum: - single - per_resource description: Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat. resources: type: array description: Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`. items: type: object description: A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40). properties: qrCodeId: type: string format: uuid description: storefront_qr_codes.uuid for the reserved resource isPrimary: type: boolean description: True for the primary/anchor resource of the booking position: type: integer minimum: 0 description: Stable ordering index of this resource within the booking (0-based) required: - qrCodeId - isPrimary - position userName: type: string nullable: true description: Primary guest name userEmail: type: string nullable: true description: Primary guest email userPhone: type: string nullable: true description: Primary guest phone tableName: type: string nullable: true description: Table name required: - id - locationId - bookingDate - startTime - endTime - timezone - guestCount - status - confirmationCode - createdAt - updatedAt - defaultTabStrategy - resources meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/bookings/{id}/cancel: post: summary: Cancel booking tags: - Bookings description: |- Cancel a booking **Permissions:** ⚪ `bookings.manage` requestBody: content: application/json: schema: type: object properties: reason: type: string description: Cancellation reason closeTab: type: boolean description: Whether to close the linked pre-arrival tab. Defaults to true. parameters: - schema: type: string format: uuid in: path name: id required: true description: Booking ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Unique booking ID locationId: type: number description: Location ID tableId: type: string format: uuid nullable: true description: Table/resource ID (QR code UUID) bookingDate: type: string format: date description: Date of the booking (YYYY-MM-DD) startTime: type: string description: Start time (HH:MM:SS) endTime: type: string description: End time (HH:MM:SS) timezone: type: string description: Timezone for the booking primaryUserId: type: - "null" - number description: Primary guest user ID (null for walk-ins) guestCount: type: number minimum: 0 description: Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests) occasion: type: string enum: - none - birthday - anniversary - business - date - celebration - other description: Occasion for the booking specialRequests: type: string nullable: true description: Guest special requests internalNotes: type: string nullable: true description: Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array. notes: type: array description: Staff-only notes attached to this booking (entity_type=booking in the notes table). items: type: object properties: uuid: type: string format: uuid note: type: string sortOrder: type: number createdByRetailerUserId: type: number nullable: true updatedByRetailerUserId: type: number nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - uuid - note - sortOrder - createdAt - updatedAt status: type: string enum: - pending - confirmed - checked_in - seated - completed - cancelled - no_show description: Booking status paymentType: type: string enum: - none - deposit - full_prepayment description: Payment type required for booking depositAmountCents: type: number nullable: true description: Deposit amount in cents purchaseId: type: number nullable: true description: Linked purchase ID confirmationCode: type: string description: Unique confirmation code for guest bookingSource: type: string enum: - direct - website - phone - walkin - third_party description: Source of the booking estimatedRevenueCents: type: number nullable: true description: AI-estimated revenue guestName: type: string nullable: true description: Guest contact name guestEmail: type: string nullable: true description: Guest contact email guestPhone: type: string nullable: true description: Guest contact phone createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp confirmedAt: type: string format: date-time nullable: true description: Confirmation timestamp seatedAt: type: string format: date-time nullable: true description: Seated timestamp completedAt: type: string format: date-time nullable: true description: Completion timestamp cancelledAt: type: string format: date-time nullable: true description: Cancellation timestamp tabId: type: string nullable: true description: UUID of the linked tab (if any) defaultTabStrategy: type: string enum: - single - per_resource description: Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat. resources: type: array description: Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`. items: type: object description: A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40). properties: qrCodeId: type: string format: uuid description: storefront_qr_codes.uuid for the reserved resource isPrimary: type: boolean description: True for the primary/anchor resource of the booking position: type: integer minimum: 0 description: Stable ordering index of this resource within the booking (0-based) required: - qrCodeId - isPrimary - position userName: type: string nullable: true description: Primary guest name userEmail: type: string nullable: true description: Primary guest email userPhone: type: string nullable: true description: Primary guest phone tableName: type: string nullable: true description: Table name required: - id - locationId - bookingDate - startTime - endTime - timezone - guestCount - status - confirmationCode - createdAt - updatedAt - defaultTabStrategy - resources meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/bookings/{id}/check-in: post: summary: Confirm booking tags: &a1 - Bookings description: |- Confirm a pending booking **Permissions:** ⚪ `bookings.manage` parameters: - schema: type: string format: uuid in: path name: id required: true description: Booking ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Unique booking ID locationId: type: number description: Location ID tableId: type: string format: uuid nullable: true description: Table/resource ID (QR code UUID) bookingDate: type: string format: date description: Date of the booking (YYYY-MM-DD) startTime: type: string description: Start time (HH:MM:SS) endTime: type: string description: End time (HH:MM:SS) timezone: type: string description: Timezone for the booking primaryUserId: type: - "null" - number description: Primary guest user ID (null for walk-ins) guestCount: type: number minimum: 0 description: Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests) occasion: type: string enum: - none - birthday - anniversary - business - date - celebration - other description: Occasion for the booking specialRequests: type: string nullable: true description: Guest special requests internalNotes: type: string nullable: true description: Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array. notes: type: array description: Staff-only notes attached to this booking (entity_type=booking in the notes table). items: type: object properties: uuid: type: string format: uuid note: type: string sortOrder: type: number createdByRetailerUserId: type: number nullable: true updatedByRetailerUserId: type: number nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - uuid - note - sortOrder - createdAt - updatedAt status: type: string enum: - pending - confirmed - checked_in - seated - completed - cancelled - no_show description: Booking status paymentType: type: string enum: - none - deposit - full_prepayment description: Payment type required for booking depositAmountCents: type: number nullable: true description: Deposit amount in cents purchaseId: type: number nullable: true description: Linked purchase ID confirmationCode: type: string description: Unique confirmation code for guest bookingSource: type: string enum: - direct - website - phone - walkin - third_party description: Source of the booking estimatedRevenueCents: type: number nullable: true description: AI-estimated revenue guestName: type: string nullable: true description: Guest contact name guestEmail: type: string nullable: true description: Guest contact email guestPhone: type: string nullable: true description: Guest contact phone createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp confirmedAt: type: string format: date-time nullable: true description: Confirmation timestamp seatedAt: type: string format: date-time nullable: true description: Seated timestamp completedAt: type: string format: date-time nullable: true description: Completion timestamp cancelledAt: type: string format: date-time nullable: true description: Cancellation timestamp tabId: type: string nullable: true description: UUID of the linked tab (if any) defaultTabStrategy: type: string enum: - single - per_resource description: Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat. resources: type: array description: Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`. items: type: object description: A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40). properties: qrCodeId: type: string format: uuid description: storefront_qr_codes.uuid for the reserved resource isPrimary: type: boolean description: True for the primary/anchor resource of the booking position: type: integer minimum: 0 description: Stable ordering index of this resource within the booking (0-based) required: - qrCodeId - isPrimary - position userName: type: string nullable: true description: Primary guest name userEmail: type: string nullable: true description: Primary guest email userPhone: type: string nullable: true description: Primary guest phone tableName: type: string nullable: true description: Table name required: - id - locationId - bookingDate - startTime - endTime - timezone - guestCount - status - confirmationCode - createdAt - updatedAt - defaultTabStrategy - resources meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/bookings/{id}/complete: post: summary: Complete booking tags: - Bookings description: |- Mark a booking as completed **Permissions:** ⚪ `bookings.manage` parameters: - schema: type: string format: uuid in: path name: id required: true description: Booking ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Unique booking ID locationId: type: number description: Location ID tableId: type: string format: uuid nullable: true description: Table/resource ID (QR code UUID) bookingDate: type: string format: date description: Date of the booking (YYYY-MM-DD) startTime: type: string description: Start time (HH:MM:SS) endTime: type: string description: End time (HH:MM:SS) timezone: type: string description: Timezone for the booking primaryUserId: type: - "null" - number description: Primary guest user ID (null for walk-ins) guestCount: type: number minimum: 0 description: Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests) occasion: type: string enum: - none - birthday - anniversary - business - date - celebration - other description: Occasion for the booking specialRequests: type: string nullable: true description: Guest special requests internalNotes: type: string nullable: true description: Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array. notes: type: array description: Staff-only notes attached to this booking (entity_type=booking in the notes table). items: type: object properties: uuid: type: string format: uuid note: type: string sortOrder: type: number createdByRetailerUserId: type: number nullable: true updatedByRetailerUserId: type: number nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - uuid - note - sortOrder - createdAt - updatedAt status: type: string enum: - pending - confirmed - checked_in - seated - completed - cancelled - no_show description: Booking status paymentType: type: string enum: - none - deposit - full_prepayment description: Payment type required for booking depositAmountCents: type: number nullable: true description: Deposit amount in cents purchaseId: type: number nullable: true description: Linked purchase ID confirmationCode: type: string description: Unique confirmation code for guest bookingSource: type: string enum: - direct - website - phone - walkin - third_party description: Source of the booking estimatedRevenueCents: type: number nullable: true description: AI-estimated revenue guestName: type: string nullable: true description: Guest contact name guestEmail: type: string nullable: true description: Guest contact email guestPhone: type: string nullable: true description: Guest contact phone createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp confirmedAt: type: string format: date-time nullable: true description: Confirmation timestamp seatedAt: type: string format: date-time nullable: true description: Seated timestamp completedAt: type: string format: date-time nullable: true description: Completion timestamp cancelledAt: type: string format: date-time nullable: true description: Cancellation timestamp tabId: type: string nullable: true description: UUID of the linked tab (if any) defaultTabStrategy: type: string enum: - single - per_resource description: Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat. resources: type: array description: Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`. items: type: object description: A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40). properties: qrCodeId: type: string format: uuid description: storefront_qr_codes.uuid for the reserved resource isPrimary: type: boolean description: True for the primary/anchor resource of the booking position: type: integer minimum: 0 description: Stable ordering index of this resource within the booking (0-based) required: - qrCodeId - isPrimary - position userName: type: string nullable: true description: Primary guest name userEmail: type: string nullable: true description: Primary guest email userPhone: type: string nullable: true description: Primary guest phone tableName: type: string nullable: true description: Table name required: - id - locationId - bookingDate - startTime - endTime - timezone - guestCount - status - confirmationCode - createdAt - updatedAt - defaultTabStrategy - resources meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/bookings/{id}/confirm: post: summary: Confirm booking tags: *a1 description: |- Confirm a pending booking **Permissions:** ⚪ `bookings.manage` parameters: - schema: type: string format: uuid in: path name: id required: true description: Booking ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Unique booking ID locationId: type: number description: Location ID tableId: type: string format: uuid nullable: true description: Table/resource ID (QR code UUID) bookingDate: type: string format: date description: Date of the booking (YYYY-MM-DD) startTime: type: string description: Start time (HH:MM:SS) endTime: type: string description: End time (HH:MM:SS) timezone: type: string description: Timezone for the booking primaryUserId: type: - "null" - number description: Primary guest user ID (null for walk-ins) guestCount: type: number minimum: 0 description: Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests) occasion: type: string enum: - none - birthday - anniversary - business - date - celebration - other description: Occasion for the booking specialRequests: type: string nullable: true description: Guest special requests internalNotes: type: string nullable: true description: Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array. notes: type: array description: Staff-only notes attached to this booking (entity_type=booking in the notes table). items: type: object properties: uuid: type: string format: uuid note: type: string sortOrder: type: number createdByRetailerUserId: type: number nullable: true updatedByRetailerUserId: type: number nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - uuid - note - sortOrder - createdAt - updatedAt status: type: string enum: - pending - confirmed - checked_in - seated - completed - cancelled - no_show description: Booking status paymentType: type: string enum: - none - deposit - full_prepayment description: Payment type required for booking depositAmountCents: type: number nullable: true description: Deposit amount in cents purchaseId: type: number nullable: true description: Linked purchase ID confirmationCode: type: string description: Unique confirmation code for guest bookingSource: type: string enum: - direct - website - phone - walkin - third_party description: Source of the booking estimatedRevenueCents: type: number nullable: true description: AI-estimated revenue guestName: type: string nullable: true description: Guest contact name guestEmail: type: string nullable: true description: Guest contact email guestPhone: type: string nullable: true description: Guest contact phone createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp confirmedAt: type: string format: date-time nullable: true description: Confirmation timestamp seatedAt: type: string format: date-time nullable: true description: Seated timestamp completedAt: type: string format: date-time nullable: true description: Completion timestamp cancelledAt: type: string format: date-time nullable: true description: Cancellation timestamp tabId: type: string nullable: true description: UUID of the linked tab (if any) defaultTabStrategy: type: string enum: - single - per_resource description: Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat. resources: type: array description: Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`. items: type: object description: A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40). properties: qrCodeId: type: string format: uuid description: storefront_qr_codes.uuid for the reserved resource isPrimary: type: boolean description: True for the primary/anchor resource of the booking position: type: integer minimum: 0 description: Stable ordering index of this resource within the booking (0-based) required: - qrCodeId - isPrimary - position userName: type: string nullable: true description: Primary guest name userEmail: type: string nullable: true description: Primary guest email userPhone: type: string nullable: true description: Primary guest phone tableName: type: string nullable: true description: Table name required: - id - locationId - bookingDate - startTime - endTime - timezone - guestCount - status - confirmationCode - createdAt - updatedAt - defaultTabStrategy - resources meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/bookings/{id}/history: get: summary: Get booking history tags: - Bookings description: |- Get audit log/history for a booking **Permissions:** 🔵 `bookings.read` parameters: - schema: type: string format: uuid in: path name: id required: true description: Booking ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: array items: type: object properties: id: type: number description: Audit log ID bookingId: type: string format: uuid description: Booking ID eventType: type: string description: Event type eventData: type: object description: Event details userId: type: number nullable: true description: Guest user ID (if applicable) retailerUserId: type: number nullable: true description: Staff user ID (if applicable) createdAt: type: string format: date-time description: Event timestamp required: - id - bookingId - eventType - eventData - createdAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/bookings/{id}/members: get: summary: List booking members tags: - Bookings description: |- List members of a booking **Permissions:** 🔵 `bookings.read` parameters: - schema: type: string format: uuid in: path name: id required: true description: Booking ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: array items: type: object properties: id: type: string format: uuid bookingId: type: string format: uuid userId: type: - "null" - number isPrimary: type: boolean guestName: type: string nullable: true guestEmail: type: string nullable: true rsvpStatus: type: string enum: - pending - accepted - declined createdAt: type: string format: date-time required: - id - bookingId - isPrimary - createdAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: summary: Add booking member tags: - Bookings description: |- Add a member to a booking **Permissions:** ⚪ `bookings.manage` requestBody: content: application/json: schema: type: object properties: userId: type: number guestName: type: string guestEmail: type: string rsvpStatus: type: string enum: - pending - accepted - declined parameters: - schema: type: string format: uuid in: path name: id required: true description: Booking ID responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid bookingId: type: string format: uuid userId: type: - "null" - number isPrimary: type: boolean guestName: type: string nullable: true guestEmail: type: string nullable: true rsvpStatus: type: string enum: - pending - accepted - declined createdAt: type: string format: date-time required: - id - bookingId - isPrimary - createdAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/bookings/{id}/members/{memberId}: patch: summary: Update booking member tags: - Bookings description: |- Update a booking member RSVP status **Permissions:** ⚪ `bookings.manage` requestBody: content: application/json: schema: type: object properties: rsvpStatus: type: string enum: - pending - accepted - declined required: - rsvpStatus required: true parameters: - schema: type: string format: uuid in: path name: id required: true description: Booking ID - schema: type: string format: uuid in: path name: memberId required: true description: Member ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid bookingId: type: string format: uuid userId: type: - "null" - number isPrimary: type: boolean guestName: type: string nullable: true guestEmail: type: string nullable: true rsvpStatus: type: string enum: - pending - accepted - declined createdAt: type: string format: date-time required: - id - bookingId - isPrimary - createdAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Remove booking member tags: - Bookings description: |- Remove a non-primary member from a booking **Permissions:** ⚪ `bookings.manage` parameters: - schema: type: string format: uuid in: path name: id required: true description: Booking ID - schema: type: string format: uuid in: path name: memberId required: true description: Member ID responses: "200": description: Default Response content: application/json: schema: type: object "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/bookings/{id}/no-show: post: summary: Mark no-show tags: - Bookings description: |- Mark a booking as no-show **Permissions:** ⚪ `bookings.manage` parameters: - schema: type: string format: uuid in: path name: id required: true description: Booking ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Unique booking ID locationId: type: number description: Location ID tableId: type: string format: uuid nullable: true description: Table/resource ID (QR code UUID) bookingDate: type: string format: date description: Date of the booking (YYYY-MM-DD) startTime: type: string description: Start time (HH:MM:SS) endTime: type: string description: End time (HH:MM:SS) timezone: type: string description: Timezone for the booking primaryUserId: type: - "null" - number description: Primary guest user ID (null for walk-ins) guestCount: type: number minimum: 0 description: Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests) occasion: type: string enum: - none - birthday - anniversary - business - date - celebration - other description: Occasion for the booking specialRequests: type: string nullable: true description: Guest special requests internalNotes: type: string nullable: true description: Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array. notes: type: array description: Staff-only notes attached to this booking (entity_type=booking in the notes table). items: type: object properties: uuid: type: string format: uuid note: type: string sortOrder: type: number createdByRetailerUserId: type: number nullable: true updatedByRetailerUserId: type: number nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - uuid - note - sortOrder - createdAt - updatedAt status: type: string enum: - pending - confirmed - checked_in - seated - completed - cancelled - no_show description: Booking status paymentType: type: string enum: - none - deposit - full_prepayment description: Payment type required for booking depositAmountCents: type: number nullable: true description: Deposit amount in cents purchaseId: type: number nullable: true description: Linked purchase ID confirmationCode: type: string description: Unique confirmation code for guest bookingSource: type: string enum: - direct - website - phone - walkin - third_party description: Source of the booking estimatedRevenueCents: type: number nullable: true description: AI-estimated revenue guestName: type: string nullable: true description: Guest contact name guestEmail: type: string nullable: true description: Guest contact email guestPhone: type: string nullable: true description: Guest contact phone createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp confirmedAt: type: string format: date-time nullable: true description: Confirmation timestamp seatedAt: type: string format: date-time nullable: true description: Seated timestamp completedAt: type: string format: date-time nullable: true description: Completion timestamp cancelledAt: type: string format: date-time nullable: true description: Cancellation timestamp tabId: type: string nullable: true description: UUID of the linked tab (if any) defaultTabStrategy: type: string enum: - single - per_resource description: Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat. resources: type: array description: Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`. items: type: object description: A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40). properties: qrCodeId: type: string format: uuid description: storefront_qr_codes.uuid for the reserved resource isPrimary: type: boolean description: True for the primary/anchor resource of the booking position: type: integer minimum: 0 description: Stable ordering index of this resource within the booking (0-based) required: - qrCodeId - isPrimary - position userName: type: string nullable: true description: Primary guest name userEmail: type: string nullable: true description: Primary guest email userPhone: type: string nullable: true description: Primary guest phone tableName: type: string nullable: true description: Table name required: - id - locationId - bookingDate - startTime - endTime - timezone - guestCount - status - confirmationCode - createdAt - updatedAt - defaultTabStrategy - resources meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/bookings/{id}/seat: post: summary: Seat booking tags: - Bookings description: >- Mark a booking as seated. Optionally create a linked tab for the booking. **Permissions:** ⚪ `bookings.manage` requestBody: content: application/json: schema: type: object properties: tabId: type: string format: uuid description: Optional existing tab ID to link createTab: type: boolean default: false description: If true, creates a new tab linked to this booking. The tab will be associated with the booking's primary user and table. parameters: - schema: type: string format: uuid in: path name: id required: true description: Booking ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Unique booking ID locationId: type: number description: Location ID tableId: type: string format: uuid nullable: true description: Table/resource ID (QR code UUID) bookingDate: type: string format: date description: Date of the booking (YYYY-MM-DD) startTime: type: string description: Start time (HH:MM:SS) endTime: type: string description: End time (HH:MM:SS) timezone: type: string description: Timezone for the booking primaryUserId: type: - "null" - number description: Primary guest user ID (null for walk-ins) guestCount: type: number minimum: 0 description: Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests) occasion: type: string enum: - none - birthday - anniversary - business - date - celebration - other description: Occasion for the booking specialRequests: type: string nullable: true description: Guest special requests internalNotes: type: string nullable: true description: Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array. notes: type: array description: Staff-only notes attached to this booking (entity_type=booking in the notes table). items: type: object properties: uuid: type: string format: uuid note: type: string sortOrder: type: number createdByRetailerUserId: type: number nullable: true updatedByRetailerUserId: type: number nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - uuid - note - sortOrder - createdAt - updatedAt status: type: string enum: - pending - confirmed - checked_in - seated - completed - cancelled - no_show description: Booking status paymentType: type: string enum: - none - deposit - full_prepayment description: Payment type required for booking depositAmountCents: type: number nullable: true description: Deposit amount in cents purchaseId: type: number nullable: true description: Linked purchase ID confirmationCode: type: string description: Unique confirmation code for guest bookingSource: type: string enum: - direct - website - phone - walkin - third_party description: Source of the booking estimatedRevenueCents: type: number nullable: true description: AI-estimated revenue guestName: type: string nullable: true description: Guest contact name guestEmail: type: string nullable: true description: Guest contact email guestPhone: type: string nullable: true description: Guest contact phone createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp confirmedAt: type: string format: date-time nullable: true description: Confirmation timestamp seatedAt: type: string format: date-time nullable: true description: Seated timestamp completedAt: type: string format: date-time nullable: true description: Completion timestamp cancelledAt: type: string format: date-time nullable: true description: Cancellation timestamp tabId: type: string nullable: true description: UUID of the linked tab (if any) defaultTabStrategy: type: string enum: - single - per_resource description: Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat. resources: type: array description: Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`. items: type: object description: A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40). properties: qrCodeId: type: string format: uuid description: storefront_qr_codes.uuid for the reserved resource isPrimary: type: boolean description: True for the primary/anchor resource of the booking position: type: integer minimum: 0 description: Stable ordering index of this resource within the booking (0-based) required: - qrCodeId - isPrimary - position userName: type: string nullable: true description: Primary guest name userEmail: type: string nullable: true description: Primary guest email userPhone: type: string nullable: true description: Primary guest phone tableName: type: string nullable: true description: Table name tab: type: object nullable: true description: Linked tab information (present when booking has a pre_arrival or active tab) properties: id: type: string format: uuid description: Tab UUID tabMemberId: type: string format: uuid nullable: true description: Tab member UUID for the primary guest meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/bookings/{id}/split: post: summary: Split booking into per-resource tabs tags: - Bookings description: >- Phase 40 R6 — convert a seated `single`-strategy multi-resource booking into per-resource tabs. Creates N-1 new tabs (one per non-primary resource that does not yet have its own tab). The existing primary tab and any items on it are preserved. `bookings.default_tab_strategy` is NOT mutated — it records the original choice. Idempotent: re-running only creates tabs for resources missing one. **Permissions:** ⚪ `bookings.manage` parameters: - schema: type: string format: uuid in: path name: id required: true description: Booking ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: tabs: type: array description: All non-terminal tabs linked to the booking after the split. Includes the pre-existing primary tab plus one entry per newly-created sibling tab. items: type: object properties: id: type: string format: uuid description: Tab UUID qrCodeId: type: string format: uuid description: storefront_qr_codes.uuid this tab is anchored on isPrimary: type: boolean description: True for the booking's primary resource tab created: type: boolean description: True if this tab was created by the split call; false if it already existed required: - id - qrCodeId - isPrimary - created createdCount: type: integer description: Number of NEW tabs created by this split call (0 on idempotent re-runs) required: - tabs - createdCount meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/bookings/{id}/unseat: post: summary: Unseat booking tags: - Bookings description: >- Undo a seat operation. Reverts the booking to its prior status (checked_in or confirmed), puts the linked tab back to pre_arrival, and reverses all kitchen dispatches advanced by seating. Refuses if purchases exist, additional orders were placed, or any dispatch is past accepted. **Permissions:** ⚪ `bookings.manage` requestBody: content: application/json: schema: type: object properties: reason: type: string description: Why the booking is being unseated (shown on the kitchen correction ticket). parameters: - schema: type: string format: uuid in: path name: id required: true description: Booking ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Unique booking ID locationId: type: number description: Location ID tableId: type: string format: uuid nullable: true description: Table/resource ID (QR code UUID) bookingDate: type: string format: date description: Date of the booking (YYYY-MM-DD) startTime: type: string description: Start time (HH:MM:SS) endTime: type: string description: End time (HH:MM:SS) timezone: type: string description: Timezone for the booking primaryUserId: type: - "null" - number description: Primary guest user ID (null for walk-ins) guestCount: type: number minimum: 0 description: Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests) occasion: type: string enum: - none - birthday - anniversary - business - date - celebration - other description: Occasion for the booking specialRequests: type: string nullable: true description: Guest special requests internalNotes: type: string nullable: true description: Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array. notes: type: array description: Staff-only notes attached to this booking (entity_type=booking in the notes table). items: type: object properties: uuid: type: string format: uuid note: type: string sortOrder: type: number createdByRetailerUserId: type: number nullable: true updatedByRetailerUserId: type: number nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - uuid - note - sortOrder - createdAt - updatedAt status: type: string enum: - pending - confirmed - checked_in - seated - completed - cancelled - no_show description: Booking status paymentType: type: string enum: - none - deposit - full_prepayment description: Payment type required for booking depositAmountCents: type: number nullable: true description: Deposit amount in cents purchaseId: type: number nullable: true description: Linked purchase ID confirmationCode: type: string description: Unique confirmation code for guest bookingSource: type: string enum: - direct - website - phone - walkin - third_party description: Source of the booking estimatedRevenueCents: type: number nullable: true description: AI-estimated revenue guestName: type: string nullable: true description: Guest contact name guestEmail: type: string nullable: true description: Guest contact email guestPhone: type: string nullable: true description: Guest contact phone createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp confirmedAt: type: string format: date-time nullable: true description: Confirmation timestamp seatedAt: type: string format: date-time nullable: true description: Seated timestamp completedAt: type: string format: date-time nullable: true description: Completion timestamp cancelledAt: type: string format: date-time nullable: true description: Cancellation timestamp tabId: type: string nullable: true description: UUID of the linked tab (if any) defaultTabStrategy: type: string enum: - single - per_resource description: Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat. resources: type: array description: Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`. items: type: object description: A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40). properties: qrCodeId: type: string format: uuid description: storefront_qr_codes.uuid for the reserved resource isPrimary: type: boolean description: True for the primary/anchor resource of the booking position: type: integer minimum: 0 description: Stable ordering index of this resource within the booking (0-based) required: - qrCodeId - isPrimary - position userName: type: string nullable: true description: Primary guest name userEmail: type: string nullable: true description: Primary guest email userPhone: type: string nullable: true description: Primary guest phone tableName: type: string nullable: true description: Table name required: - id - locationId - bookingDate - startTime - endTime - timezone - guestCount - status - confirmationCode - createdAt - updatedAt - defaultTabStrategy - resources meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/bookings/by-code/{code}/cancel: post: summary: Cancel booking by confirmation code tags: - Bookings description: "Public endpoint: cancel a booking using confirmation code (no auth required)" requestBody: content: application/json: schema: type: object properties: reason: type: string description: Cancellation reason parameters: - schema: type: string in: path name: code required: true description: Booking confirmation code responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Unique booking ID locationId: type: number description: Location ID tableId: type: string format: uuid nullable: true description: Table/resource ID (QR code UUID) bookingDate: type: string format: date description: Date of the booking (YYYY-MM-DD) startTime: type: string description: Start time (HH:MM:SS) endTime: type: string description: End time (HH:MM:SS) timezone: type: string description: Timezone for the booking primaryUserId: type: - "null" - number description: Primary guest user ID (null for walk-ins) guestCount: type: number minimum: 0 description: Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests) occasion: type: string enum: - none - birthday - anniversary - business - date - celebration - other description: Occasion for the booking specialRequests: type: string nullable: true description: Guest special requests internalNotes: type: string nullable: true description: Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array. notes: type: array description: Staff-only notes attached to this booking (entity_type=booking in the notes table). items: type: object properties: uuid: type: string format: uuid note: type: string sortOrder: type: number createdByRetailerUserId: type: number nullable: true updatedByRetailerUserId: type: number nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - uuid - note - sortOrder - createdAt - updatedAt status: type: string enum: - pending - confirmed - checked_in - seated - completed - cancelled - no_show description: Booking status paymentType: type: string enum: - none - deposit - full_prepayment description: Payment type required for booking depositAmountCents: type: number nullable: true description: Deposit amount in cents purchaseId: type: number nullable: true description: Linked purchase ID confirmationCode: type: string description: Unique confirmation code for guest bookingSource: type: string enum: - direct - website - phone - walkin - third_party description: Source of the booking estimatedRevenueCents: type: number nullable: true description: AI-estimated revenue guestName: type: string nullable: true description: Guest contact name guestEmail: type: string nullable: true description: Guest contact email guestPhone: type: string nullable: true description: Guest contact phone createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp confirmedAt: type: string format: date-time nullable: true description: Confirmation timestamp seatedAt: type: string format: date-time nullable: true description: Seated timestamp completedAt: type: string format: date-time nullable: true description: Completion timestamp cancelledAt: type: string format: date-time nullable: true description: Cancellation timestamp tabId: type: string nullable: true description: UUID of the linked tab (if any) defaultTabStrategy: type: string enum: - single - per_resource description: Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat. resources: type: array description: Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`. items: type: object description: A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40). properties: qrCodeId: type: string format: uuid description: storefront_qr_codes.uuid for the reserved resource isPrimary: type: boolean description: True for the primary/anchor resource of the booking position: type: integer minimum: 0 description: Stable ordering index of this resource within the booking (0-based) required: - qrCodeId - isPrimary - position userName: type: string nullable: true description: Primary guest name userEmail: type: string nullable: true description: Primary guest email userPhone: type: string nullable: true description: Primary guest phone tableName: type: string nullable: true description: Table name required: - id - locationId - bookingDate - startTime - endTime - timezone - guestCount - status - confirmationCode - createdAt - updatedAt - defaultTabStrategy - resources meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/bookings/rsvp: post: summary: RSVP to booking tags: - Bookings description: "Public endpoint: RSVP to a booking using confirmation code (no auth required)" requestBody: content: application/json: schema: type: object properties: confirmationCode: type: string guestName: type: string guestEmail: type: string rsvpStatus: type: string enum: - pending - accepted - declined required: - confirmationCode - guestName - rsvpStatus required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid bookingId: type: string format: uuid userId: type: - "null" - number isPrimary: type: boolean guestName: type: string nullable: true guestEmail: type: string nullable: true rsvpStatus: type: string enum: - pending - accepted - declined createdAt: type: string format: date-time required: - id - bookingId - isPrimary - createdAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid bookingId: type: string format: uuid userId: type: - "null" - number isPrimary: type: boolean guestName: type: string nullable: true guestEmail: type: string nullable: true rsvpStatus: type: string enum: - pending - accepted - declined createdAt: type: string format: date-time required: - id - bookingId - isPrimary - createdAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/locations/{locationId}/booking-availability: get: summary: Get availability tags: - Bookings description: |- Get available booking slots for a date and party size **Permissions:** 🔵 `bookings.read` parameters: - schema: type: string format: date in: query name: date required: true description: Date to check availability - schema: type: number minimum: 1 in: query name: partySize required: true description: Number of guests - schema: type: string format: uuid in: query name: bookingGroupId required: false description: Optional booking group ID to filter availability by group schedule, table pool, and settings - schema: type: number in: path name: locationId required: true description: Location ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: date: type: string format: date partySize: type: number slots: type: array items: type: object properties: id: type: string format: uuid description: Unique slot ID tableId: type: string format: uuid nullable: true description: Table/resource ID locationId: type: number description: Location ID slotDate: type: string format: date description: Date of the slot startTime: type: string description: Start time endTime: type: string description: End time durationMinutes: type: number description: Duration in minutes maxCapacity: type: number description: Maximum capacity currentBookings: type: number description: Current number of bookings status: type: string enum: - available - partially_booked - fully_booked - blocked description: Slot status predictedDemandScore: type: number nullable: true description: AI demand prediction (0.00-1.00) optimalPartySizeMin: type: number nullable: true description: AI-suggested minimum party size optimalPartySizeMax: type: number nullable: true description: AI-suggested maximum party size scheduleId: type: string format: uuid nullable: true description: Schedule that generated this slot createdAt: type: string format: date-time description: Creation timestamp required: - id - locationId - slotDate - startTime - endTime - durationMinutes - maxCapacity - currentBookings - status - createdAt tables: type: array items: type: object properties: id: type: string name: type: string minCapacity: type: number maxCapacity: type: number availableSlots: type: array items: type: object properties: id: type: string format: uuid description: Unique slot ID tableId: type: string format: uuid nullable: true description: Table/resource ID locationId: type: number description: Location ID slotDate: type: string format: date description: Date of the slot startTime: type: string description: Start time endTime: type: string description: End time durationMinutes: type: number description: Duration in minutes maxCapacity: type: number description: Maximum capacity currentBookings: type: number description: Current number of bookings status: type: string enum: - available - partially_booked - fully_booked - blocked description: Slot status predictedDemandScore: type: number nullable: true description: AI demand prediction (0.00-1.00) optimalPartySizeMin: type: number nullable: true description: AI-suggested minimum party size optimalPartySizeMax: type: number nullable: true description: AI-suggested maximum party size scheduleId: type: string format: uuid nullable: true description: Schedule that generated this slot createdAt: type: string format: date-time description: Creation timestamp required: - id - locationId - slotDate - startTime - endTime - durationMinutes - maxCapacity - currentBookings - status - createdAt required: - date - partySize - slots meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/locations/{locationId}/bookings/by-table: get: summary: Get bookings by table tags: - Bookings description: >- Get bookings grouped by table for a specific date. Useful for table map display in POS. **Permissions:** 🔵 `bookings.read` parameters: - schema: type: string format: date in: query name: date required: true description: Date to fetch bookings for (YYYY-MM-DD) - schema: type: number in: path name: locationId required: true description: Location ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: tables: type: array items: type: object properties: tableId: type: string format: uuid description: Table/QR code UUID tableName: type: string nullable: true description: Table name bookings: type: array items: type: object properties: id: type: string format: uuid description: Unique booking ID locationId: type: number description: Location ID tableId: type: string format: uuid nullable: true description: Table/resource ID (QR code UUID) bookingDate: type: string format: date description: Date of the booking (YYYY-MM-DD) startTime: type: string description: Start time (HH:MM:SS) endTime: type: string description: End time (HH:MM:SS) timezone: type: string description: Timezone for the booking primaryUserId: type: - "null" - number description: Primary guest user ID (null for walk-ins) guestCount: type: number minimum: 0 description: Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests) occasion: type: string enum: - none - birthday - anniversary - business - date - celebration - other description: Occasion for the booking specialRequests: type: string nullable: true description: Guest special requests internalNotes: type: string nullable: true description: Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array. notes: type: array description: Staff-only notes attached to this booking (entity_type=booking in the notes table). items: type: object properties: uuid: type: string format: uuid note: type: string sortOrder: type: number createdByRetailerUserId: type: number nullable: true updatedByRetailerUserId: type: number nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - uuid - note - sortOrder - createdAt - updatedAt status: type: string enum: - pending - confirmed - checked_in - seated - completed - cancelled - no_show description: Booking status paymentType: type: string enum: - none - deposit - full_prepayment description: Payment type required for booking depositAmountCents: type: number nullable: true description: Deposit amount in cents purchaseId: type: number nullable: true description: Linked purchase ID confirmationCode: type: string description: Unique confirmation code for guest bookingSource: type: string enum: - direct - website - phone - walkin - third_party description: Source of the booking estimatedRevenueCents: type: number nullable: true description: AI-estimated revenue guestName: type: string nullable: true description: Guest contact name guestEmail: type: string nullable: true description: Guest contact email guestPhone: type: string nullable: true description: Guest contact phone createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp confirmedAt: type: string format: date-time nullable: true description: Confirmation timestamp seatedAt: type: string format: date-time nullable: true description: Seated timestamp completedAt: type: string format: date-time nullable: true description: Completion timestamp cancelledAt: type: string format: date-time nullable: true description: Cancellation timestamp tabId: type: string nullable: true description: UUID of the linked tab (if any) defaultTabStrategy: type: string enum: - single - per_resource description: Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat. resources: type: array description: Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`. items: type: object description: A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40). properties: qrCodeId: type: string format: uuid description: storefront_qr_codes.uuid for the reserved resource isPrimary: type: boolean description: True for the primary/anchor resource of the booking position: type: integer minimum: 0 description: Stable ordering index of this resource within the booking (0-based) required: - qrCodeId - isPrimary - position userName: type: string nullable: true description: Primary guest name userEmail: type: string nullable: true description: Primary guest email userPhone: type: string nullable: true description: Primary guest phone tableName: type: string nullable: true description: Table name required: - id - locationId - bookingDate - startTime - endTime - timezone - guestCount - status - confirmationCode - createdAt - updatedAt - defaultTabStrategy - resources description: Bookings for this table required: - tableId - bookings required: - tables meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/bookings/{id}/lock: patch: summary: Toggle booking resource lock tags: - Bookings - Optimization description: >- Lock or unlock a booking to its assigned table. Locked bookings will not be moved by the optimizer. **Permissions:** ⚪ `bookings.manage` requestBody: content: application/json: schema: type: object properties: locked: type: boolean description: Whether to lock (true) or unlock (false) the booking required: - locked required: true parameters: - schema: type: string format: uuid in: path name: id required: true description: Booking ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Unique booking ID locationId: type: number description: Location ID tableId: type: string format: uuid nullable: true description: Table/resource ID (QR code UUID) bookingDate: type: string format: date description: Date of the booking (YYYY-MM-DD) startTime: type: string description: Start time (HH:MM:SS) endTime: type: string description: End time (HH:MM:SS) timezone: type: string description: Timezone for the booking primaryUserId: type: - "null" - number description: Primary guest user ID (null for walk-ins) guestCount: type: number minimum: 0 description: Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests) occasion: type: string enum: - none - birthday - anniversary - business - date - celebration - other description: Occasion for the booking specialRequests: type: string nullable: true description: Guest special requests internalNotes: type: string nullable: true description: Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array. notes: type: array description: Staff-only notes attached to this booking (entity_type=booking in the notes table). items: type: object properties: uuid: type: string format: uuid note: type: string sortOrder: type: number createdByRetailerUserId: type: number nullable: true updatedByRetailerUserId: type: number nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - uuid - note - sortOrder - createdAt - updatedAt status: type: string enum: - pending - confirmed - checked_in - seated - completed - cancelled - no_show description: Booking status paymentType: type: string enum: - none - deposit - full_prepayment description: Payment type required for booking depositAmountCents: type: number nullable: true description: Deposit amount in cents purchaseId: type: number nullable: true description: Linked purchase ID confirmationCode: type: string description: Unique confirmation code for guest bookingSource: type: string enum: - direct - website - phone - walkin - third_party description: Source of the booking estimatedRevenueCents: type: number nullable: true description: AI-estimated revenue guestName: type: string nullable: true description: Guest contact name guestEmail: type: string nullable: true description: Guest contact email guestPhone: type: string nullable: true description: Guest contact phone createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp confirmedAt: type: string format: date-time nullable: true description: Confirmation timestamp seatedAt: type: string format: date-time nullable: true description: Seated timestamp completedAt: type: string format: date-time nullable: true description: Completion timestamp cancelledAt: type: string format: date-time nullable: true description: Cancellation timestamp tabId: type: string nullable: true description: UUID of the linked tab (if any) defaultTabStrategy: type: string enum: - single - per_resource description: Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat. resources: type: array description: Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`. items: type: object description: A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40). properties: qrCodeId: type: string format: uuid description: storefront_qr_codes.uuid for the reserved resource isPrimary: type: boolean description: True for the primary/anchor resource of the booking position: type: integer minimum: 0 description: Stable ordering index of this resource within the booking (0-based) required: - qrCodeId - isPrimary - position userName: type: string nullable: true description: Primary guest name userEmail: type: string nullable: true description: Primary guest email userPhone: type: string nullable: true description: Primary guest phone tableName: type: string nullable: true description: Table name required: - id - locationId - bookingDate - startTime - endTime - timezone - guestCount - status - confirmationCode - createdAt - updatedAt - defaultTabStrategy - resources meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/locations/{locationId}/bookings/optimize: post: summary: Optimize booking table assignments tags: - Bookings - Optimization description: >- Run the booking optimization algorithm to improve table utilization. Use dryRun=true to preview changes without applying them. **Permissions:** ⚪ `bookings.manage` requestBody: content: application/json: schema: type: object properties: dryRun: type: boolean default: true description: If true, only preview changes without applying them parameters: - schema: type: string format: date in: query name: date required: true description: Date to optimize (YYYY-MM-DD) - schema: type: number in: path name: locationId required: true description: Location ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: changes: type: array items: type: object properties: bookingId: type: string format: uuid description: Booking ID guestName: type: string nullable: true description: Guest name partySize: type: number description: Party size fromTableId: type: string format: uuid nullable: true description: Original table ID fromTableName: type: string nullable: true description: Original table name toTableId: type: string format: uuid description: New table ID toTableName: type: string description: New table name reason: type: string description: Reason for the change required: - bookingId - partySize - toTableId - toTableName - reason description: List of proposed or applied changes stats: type: object properties: totalBookings: type: number description: Total bookings for the date optimizedCount: type: number description: Number of bookings moved lockedCount: type: number description: Number of locked bookings (not moved) tablesFreed: type: number description: Number of tables freed up utilizationImprovement: type: number description: Improvement in table utilization (percentage) required: - totalBookings - optimizedCount - lockedCount - tablesFreed - utilizationImprovement required: - changes - stats meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/locations/{locationId}/booking-settings: get: summary: Get location booking settings tags: - Bookings - Settings description: >- Get booking settings for a location. Creates default settings if none exist. **Permissions:** 🔵 `bookings.read` parameters: - schema: type: number in: path name: locationId required: true description: Location ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Settings ID locationId: type: number description: Location ID bufferMinutes: type: number description: Time buffer between bookings on same table (minutes) defaultDurationMinutes: type: number description: Default booking duration (minutes) autoOptimizeEnabled: type: boolean description: Whether to auto-optimize table assignments maxPartySize: type: number description: Maximum party size allowed for online bookings minAdvanceHours: type: number description: Minimum hours in advance a booking must be made maxAdvanceDays: type: number description: Maximum days in advance a booking can be made allowedPartySizes: type: array items: type: number description: Specific party sizes allowed (empty = all sizes up to max) operatingHours: type: object description: Per-day booking hours override slotIntervalMinutes: type: number description: Time slot interval (minutes) overbookingBufferPercentage: type: number description: Overbooking buffer percentage confirmationMode: type: string enum: - instant - request_based description: Booking confirmation mode autoNoShowDelayMinutes: type: - "null" - number description: Minutes after start before auto no-show (null = disabled) cancellationPolicyHours: type: - "null" - number description: Free cancellation until X hours before (null = anytime) bookingWindowDays: type: - "null" - number description: How far ahead guests can book in days (null = use maxAdvanceDays) maxActiveBookingsPerGuest: type: - "null" - number description: Max concurrent active bookings per guest per location (null = unlimited) createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - id - locationId - bufferMinutes - defaultDurationMinutes - autoOptimizeEnabled - confirmationMode - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: summary: Update location booking settings tags: - Bookings - Settings description: |- Update booking settings for a location. **Permissions:** ⚪ `bookings.manage` requestBody: content: application/json: schema: type: object properties: bufferMinutes: type: number minimum: 0 maximum: 120 description: Time buffer between bookings (minutes) defaultDurationMinutes: type: number minimum: 15 maximum: 480 description: Default booking duration (minutes) autoOptimizeEnabled: type: boolean description: Enable automatic table optimization maxPartySize: type: number minimum: 1 maximum: 100 description: Maximum party size allowed minAdvanceHours: type: number minimum: 0 maximum: 168 description: Minimum hours in advance maxAdvanceDays: type: number minimum: 1 maximum: 365 description: Maximum days in advance allowedPartySizes: type: array items: type: number description: Specific party sizes allowed operatingHours: type: object description: Per-day booking hours override slotIntervalMinutes: type: number enum: - 15 - 30 - 45 - 60 - 90 description: Time slot interval (minutes) overbookingBufferPercentage: type: number minimum: 0 maximum: 50 description: Overbooking buffer percentage confirmationMode: type: string enum: - instant - request_based description: Booking confirmation mode autoNoShowDelayMinutes: type: - number - "null" minimum: 5 maximum: 120 description: Auto no-show delay (minutes) cancellationPolicyHours: type: - number - "null" minimum: 0 maximum: 168 description: Cancellation policy (hours before) bookingWindowDays: type: - number - "null" minimum: 1 maximum: 365 description: Booking window (days ahead) maxActiveBookingsPerGuest: type: - number - "null" minimum: 1 maximum: 50 description: Max active bookings per guest parameters: - schema: type: number in: path name: locationId required: true description: Location ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Settings ID locationId: type: number description: Location ID bufferMinutes: type: number description: Time buffer between bookings on same table (minutes) defaultDurationMinutes: type: number description: Default booking duration (minutes) autoOptimizeEnabled: type: boolean description: Whether to auto-optimize table assignments maxPartySize: type: number description: Maximum party size allowed for online bookings minAdvanceHours: type: number description: Minimum hours in advance a booking must be made maxAdvanceDays: type: number description: Maximum days in advance a booking can be made allowedPartySizes: type: array items: type: number description: Specific party sizes allowed (empty = all sizes up to max) operatingHours: type: object description: Per-day booking hours override slotIntervalMinutes: type: number description: Time slot interval (minutes) overbookingBufferPercentage: type: number description: Overbooking buffer percentage confirmationMode: type: string enum: - instant - request_based description: Booking confirmation mode autoNoShowDelayMinutes: type: - "null" - number description: Minutes after start before auto no-show (null = disabled) cancellationPolicyHours: type: - "null" - number description: Free cancellation until X hours before (null = anytime) bookingWindowDays: type: - "null" - number description: How far ahead guests can book in days (null = use maxAdvanceDays) maxActiveBookingsPerGuest: type: - "null" - number description: Max concurrent active bookings per guest per location (null = unlimited) createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - id - locationId - bufferMinutes - defaultDurationMinutes - autoOptimizeEnabled - confirmationMode - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/users/guests: post: summary: Create guest user tags: - Bookings - Users description: |- Create a new guest user. At least email or phone is required. **Permissions:** 🟢 `bookings.create` requestBody: content: application/json: schema: type: object properties: name: type: string description: Guest name email: type: string format: email description: Guest email phone: type: string description: Guest phone number responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: User ID email: type: string nullable: true description: User email phone: type: string nullable: true description: Effective phone (location override if set, else global) name: type: string nullable: true description: Effective display name (location override if set, else global) lastSeenDate: type: string format: date-time nullable: true description: Last activity date bookingCount: type: number description: Number of bookings at this location lastBookingDate: type: string format: date nullable: true description: Last booking date vip: type: boolean description: Per-location VIP flag flags: type: object additionalProperties: true description: Per-location flags (allergies, dietary, accessibility, etc.) hasLocationOverride: type: boolean description: True when a per-location override exists for this user at the searched location required: - id - bookingCount - vip - flags - hasLocationOverride meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/users/search: get: summary: Search guest users tags: - Bookings - Users description: >- Search for guest users by email, phone, or name. Returns users with their booking history at the location. **Permissions:** 🔵 `bookings.read` parameters: - schema: type: string minLength: 2 in: query name: q required: true description: Search query (email, phone, or name) - schema: type: number in: query name: locationId required: false description: Location ID for booking history context - schema: type: number minimum: 1 maximum: 50 default: 20 in: query name: limit required: false description: Maximum results to return responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: users: type: array items: type: object properties: id: type: number description: User ID email: type: string nullable: true description: User email phone: type: string nullable: true description: Effective phone (location override if set, else global) name: type: string nullable: true description: Effective display name (location override if set, else global) lastSeenDate: type: string format: date-time nullable: true description: Last activity date bookingCount: type: number description: Number of bookings at this location lastBookingDate: type: string format: date nullable: true description: Last booking date vip: type: boolean description: Per-location VIP flag flags: type: object additionalProperties: true description: Per-location flags (allergies, dietary, accessibility, etc.) hasLocationOverride: type: boolean description: True when a per-location override exists for this user at the searched location required: - id - bookingCount - vip - flags - hasLocationOverride required: - users meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/booking-waitlist: get: summary: List waitlist tags: - Bookings - Waitlist description: |- List waitlist entries **Permissions:** 🔵 `booking_waitlist.read` parameters: - schema: type: number in: query name: locationId required: false description: Filter by location ID - schema: type: string enum: - waiting - notified - converted - expired - removed in: query name: status required: false description: Waitlist entry status - schema: type: string format: date in: query name: requestedDate required: false description: Filter by requested date - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: number minimum: 1 maximum: 100 default: 50 in: query name: limit required: false description: Items per page responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: entries: type: array items: type: object properties: id: type: string format: uuid description: Waitlist entry ID locationId: type: number description: Location ID userId: type: number description: User ID requestedDate: type: string format: date description: Requested date preferredStartTime: type: string nullable: true description: Preferred start time preferredEndTime: type: string nullable: true description: Preferred end time partySize: type: number description: Number of guests status: type: string enum: - waiting - notified - converted - expired - removed description: Waitlist entry status convertedBookingId: type: string format: uuid nullable: true description: Booking ID if converted expiresAt: type: string format: date-time nullable: true description: Expiration timestamp notifiedAt: type: string format: date-time nullable: true description: Notification timestamp createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp userName: type: string nullable: true description: User name userEmail: type: string nullable: true description: User email userPhone: type: string nullable: true description: User phone required: - id - locationId - userId - requestedDate - partySize - status - createdAt - updatedAt pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages required: - entries - pagination meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: summary: Add to waitlist tags: - Bookings - Waitlist description: |- Add a guest to the waitlist **Permissions:** ⚪ `booking_waitlist.manage` requestBody: content: application/json: schema: type: object properties: locationId: type: number description: Location ID userId: type: number description: User ID requestedDate: type: string format: date description: Requested date partySize: type: number minimum: 1 description: Number of guests preferredStartTime: type: string description: Preferred start time preferredEndTime: type: string description: Preferred end time required: - locationId - userId - requestedDate - partySize required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Waitlist entry ID locationId: type: number description: Location ID userId: type: number description: User ID requestedDate: type: string format: date description: Requested date preferredStartTime: type: string nullable: true description: Preferred start time preferredEndTime: type: string nullable: true description: Preferred end time partySize: type: number description: Number of guests status: type: string enum: - waiting - notified - converted - expired - removed description: Waitlist entry status convertedBookingId: type: string format: uuid nullable: true description: Booking ID if converted expiresAt: type: string format: date-time nullable: true description: Expiration timestamp notifiedAt: type: string format: date-time nullable: true description: Notification timestamp createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp userName: type: string nullable: true description: User name userEmail: type: string nullable: true description: User email userPhone: type: string nullable: true description: User phone required: - id - locationId - userId - requestedDate - partySize - status - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/booking-waitlist/{id}: delete: summary: Remove from waitlist tags: - Bookings - Waitlist description: |- Remove a guest from the waitlist **Permissions:** ⚪ `booking_waitlist.manage` parameters: - schema: type: string format: uuid in: path name: id required: true description: Waitlist entry ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: deleted: type: boolean meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/booking-waitlist/{id}/convert: post: summary: Convert waitlist to booking tags: - Bookings - Waitlist description: |- Convert a waitlist entry to a booking **Permissions:** ⚪ `booking_waitlist.manage` requestBody: content: application/json: schema: type: object properties: tableId: type: string format: uuid description: Table to assign startTime: type: string description: Start time endTime: type: string description: End time required: - startTime - endTime required: true parameters: - schema: type: string format: uuid in: path name: id required: true description: Waitlist entry ID responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Unique booking ID locationId: type: number description: Location ID tableId: type: string format: uuid nullable: true description: Table/resource ID (QR code UUID) bookingDate: type: string format: date description: Date of the booking (YYYY-MM-DD) startTime: type: string description: Start time (HH:MM:SS) endTime: type: string description: End time (HH:MM:SS) timezone: type: string description: Timezone for the booking primaryUserId: type: - "null" - number description: Primary guest user ID (null for walk-ins) guestCount: type: number minimum: 0 description: Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests) occasion: type: string enum: - none - birthday - anniversary - business - date - celebration - other description: Occasion for the booking specialRequests: type: string nullable: true description: Guest special requests internalNotes: type: string nullable: true description: Legacy single-string notes field. Derived from notes[0]?.note for forward compat. Prefer reading from `notes` array. notes: type: array description: Staff-only notes attached to this booking (entity_type=booking in the notes table). items: type: object properties: uuid: type: string format: uuid note: type: string sortOrder: type: number createdByRetailerUserId: type: number nullable: true updatedByRetailerUserId: type: number nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - uuid - note - sortOrder - createdAt - updatedAt status: type: string enum: - pending - confirmed - checked_in - seated - completed - cancelled - no_show description: Booking status paymentType: type: string enum: - none - deposit - full_prepayment description: Payment type required for booking depositAmountCents: type: number nullable: true description: Deposit amount in cents purchaseId: type: number nullable: true description: Linked purchase ID confirmationCode: type: string description: Unique confirmation code for guest bookingSource: type: string enum: - direct - website - phone - walkin - third_party description: Source of the booking estimatedRevenueCents: type: number nullable: true description: AI-estimated revenue guestName: type: string nullable: true description: Guest contact name guestEmail: type: string nullable: true description: Guest contact email guestPhone: type: string nullable: true description: Guest contact phone createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp confirmedAt: type: string format: date-time nullable: true description: Confirmation timestamp seatedAt: type: string format: date-time nullable: true description: Seated timestamp completedAt: type: string format: date-time nullable: true description: Completion timestamp cancelledAt: type: string format: date-time nullable: true description: Cancellation timestamp tabId: type: string nullable: true description: UUID of the linked tab (if any) defaultTabStrategy: type: string enum: - single - per_resource description: Default tab strategy chosen at booking time (Phase 40). `single` keeps one shared tab across all resources; `per_resource` opens one tab per resource on seat. resources: type: array description: Resources reserved by this booking (Phase 40 multi-resource). Single-resource bookings return one entry. Populated by the handler from `booking_resources`. items: type: object description: A single resource (storefront_qr_code, e.g. table/QR) reserved by a booking. Returned in `resources[]` on booking responses (Phase 40). properties: qrCodeId: type: string format: uuid description: storefront_qr_codes.uuid for the reserved resource isPrimary: type: boolean description: True for the primary/anchor resource of the booking position: type: integer minimum: 0 description: Stable ordering index of this resource within the booking (0-based) required: - qrCodeId - isPrimary - position userName: type: string nullable: true description: Primary guest name userEmail: type: string nullable: true description: Primary guest email userPhone: type: string nullable: true description: Primary guest phone tableName: type: string nullable: true description: Table name required: - id - locationId - bookingDate - startTime - endTime - timezone - guestCount - status - confirmationCode - createdAt - updatedAt - defaultTabStrategy - resources meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/booking-waitlist/{id}/notify: post: summary: Notify waitlist tags: - Bookings - Waitlist description: |- Notify a waitlist entry of available slot **Permissions:** ⚪ `booking_waitlist.manage` parameters: - schema: type: string format: uuid in: path name: id required: true description: Waitlist entry ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Waitlist entry ID locationId: type: number description: Location ID userId: type: number description: User ID requestedDate: type: string format: date description: Requested date preferredStartTime: type: string nullable: true description: Preferred start time preferredEndTime: type: string nullable: true description: Preferred end time partySize: type: number description: Number of guests status: type: string enum: - waiting - notified - converted - expired - removed description: Waitlist entry status convertedBookingId: type: string format: uuid nullable: true description: Booking ID if converted expiresAt: type: string format: date-time nullable: true description: Expiration timestamp notifiedAt: type: string format: date-time nullable: true description: Notification timestamp createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp userName: type: string nullable: true description: User name userEmail: type: string nullable: true description: User email userPhone: type: string nullable: true description: User phone required: - id - locationId - userId - requestedDate - partySize - status - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/locations/{locationId}/capacity-settings: get: tags: - Capacity Settings description: List all capacity settings for a location parameters: - schema: type: string in: path name: locationId required: true description: Location ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: capacitySettings: type: array items: type: object properties: id: type: number locationId: type: number orderCapacity: type: - "null" - number itemCapacity: type: - "null" - number name: type: string priority: type: number enabled: type: boolean timeStart: type: - "null" - string description: HH:mm:ss format timeEnd: type: - "null" - string description: HH:mm:ss format validFrom: type: - "null" - string description: ISO timestamp validTo: type: - "null" - string description: ISO timestamp validOnDays: type: array items: type: number description: Array of days (1-7, Monday-Sunday) createdAt: type: string updatedAt: type: string required: - id - locationId - orderCapacity - itemCapacity - name - priority - enabled - timeStart - timeEnd - validFrom - validTo - validOnDays - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: tags: - Capacity Settings description: Create a new capacity setting requestBody: content: application/json: schema: type: object properties: orderCapacity: type: - number - "null" description: Max orders per time slot itemCapacity: type: - number - "null" description: Max items per time slot name: type: string description: Display name for this setting priority: type: number description: Sort order (lower = higher priority) enabled: type: boolean default: true timeStart: type: - string - "null" description: HH:mm:ss format timeEnd: type: - string - "null" description: HH:mm:ss format validFrom: type: - string - "null" description: ISO timestamp validTo: type: - string - "null" description: ISO timestamp validOnDays: type: array items: type: number description: Array of days (1-7, Monday-Sunday) required: - name - validOnDays required: true parameters: - schema: type: string in: path name: locationId required: true description: Location ID responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: capacitySetting: type: object properties: id: type: number locationId: type: number orderCapacity: type: - "null" - number itemCapacity: type: - "null" - number name: type: string priority: type: number enabled: type: boolean timeStart: type: - "null" - string description: HH:mm:ss format timeEnd: type: - "null" - string description: HH:mm:ss format validFrom: type: - "null" - string description: ISO timestamp validTo: type: - "null" - string description: ISO timestamp validOnDays: type: array items: type: number description: Array of days (1-7, Monday-Sunday) createdAt: type: string updatedAt: type: string required: - id - locationId - orderCapacity - itemCapacity - name - priority - enabled - timeStart - timeEnd - validFrom - validTo - validOnDays - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/locations/{locationId}/capacity-settings/{id}: get: tags: - Capacity Settings description: Get a single capacity setting parameters: - schema: type: string in: path name: locationId required: true description: Location ID - schema: type: string in: path name: id required: true description: Capacity setting ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: capacitySetting: type: object properties: id: type: number locationId: type: number orderCapacity: type: - "null" - number itemCapacity: type: - "null" - number name: type: string priority: type: number enabled: type: boolean timeStart: type: - "null" - string description: HH:mm:ss format timeEnd: type: - "null" - string description: HH:mm:ss format validFrom: type: - "null" - string description: ISO timestamp validTo: type: - "null" - string description: ISO timestamp validOnDays: type: array items: type: number description: Array of days (1-7, Monday-Sunday) createdAt: type: string updatedAt: type: string required: - id - locationId - orderCapacity - itemCapacity - name - priority - enabled - timeStart - timeEnd - validFrom - validTo - validOnDays - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: tags: - Capacity Settings description: Update an existing capacity setting requestBody: content: application/json: schema: type: object properties: orderCapacity: type: - number - "null" itemCapacity: type: - number - "null" name: type: string priority: type: number enabled: type: boolean timeStart: type: - string - "null" timeEnd: type: - string - "null" validFrom: type: - string - "null" validTo: type: - string - "null" validOnDays: type: array items: type: number parameters: - schema: type: string in: path name: locationId required: true description: Location ID - schema: type: string in: path name: id required: true description: Capacity setting ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: capacitySetting: type: object properties: id: type: number locationId: type: number orderCapacity: type: - "null" - number itemCapacity: type: - "null" - number name: type: string priority: type: number enabled: type: boolean timeStart: type: - "null" - string description: HH:mm:ss format timeEnd: type: - "null" - string description: HH:mm:ss format validFrom: type: - "null" - string description: ISO timestamp validTo: type: - "null" - string description: ISO timestamp validOnDays: type: array items: type: number description: Array of days (1-7, Monday-Sunday) createdAt: type: string updatedAt: type: string required: - id - locationId - orderCapacity - itemCapacity - name - priority - enabled - timeStart - timeEnd - validFrom - validTo - validOnDays - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: tags: - Capacity Settings description: Delete a capacity setting parameters: - schema: type: string in: path name: locationId required: true description: Location ID - schema: type: string in: path name: id required: true description: Capacity setting ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: deleted: type: boolean meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/locations/{locationId}/capacity-settings/reorder: put: tags: - Capacity Settings description: Reorder capacity settings (update priorities) requestBody: content: application/json: schema: type: object properties: orderedIds: type: array items: type: number description: Array of capacity setting IDs in desired priority order required: - orderedIds required: true parameters: - schema: type: string in: path name: locationId required: true description: Location ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: capacitySettings: type: array items: type: object properties: id: type: number locationId: type: number orderCapacity: type: - "null" - number itemCapacity: type: - "null" - number name: type: string priority: type: number enabled: type: boolean timeStart: type: - "null" - string description: HH:mm:ss format timeEnd: type: - "null" - string description: HH:mm:ss format validFrom: type: - "null" - string description: ISO timestamp validTo: type: - "null" - string description: ISO timestamp validOnDays: type: array items: type: number description: Array of days (1-7, Monday-Sunday) createdAt: type: string updatedAt: type: string required: - id - locationId - orderCapacity - itemCapacity - name - priority - enabled - timeStart - timeEnd - validFrom - validTo - validOnDays - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/channels: get: summary: List channels tags: - Channels description: List channels with optional filtering parameters: - schema: type: number in: query name: locationId required: false description: Filter by location ID - schema: type: string enum: - MENU - ITEM - LOCATION - MODIFIER - CATEGORY - MENU_LAYOUT - VARIANT_GROUP in: query name: entityType required: false description: Filter by entity type - schema: type: string in: query name: entityId required: false description: Filter by entity ID - schema: type: string enum: - KIOSK - POS - ONLINE - TAKEAWAY in: query name: channelType required: false description: Filter by specific channel type - schema: type: boolean in: query name: isActive required: false description: Filter by active status - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: number minimum: 1 maximum: 100 default: 20 in: query name: limit required: false description: Items per page responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: channels: type: array items: type: object properties: id: type: string description: Unique channel ID entityType: type: string enum: - MENU - ITEM - LOCATION - MODIFIER - CATEGORY - MENU_LAYOUT - VARIANT_GROUP description: Type of entity this channel applies to entityId: type: string description: ID of the entity locationId: type: number nullable: true description: Location ID this channel applies to isActive: type: boolean description: Whether channel is active createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp assignments: type: array items: type: object properties: id: type: string description: Unique assignment ID channelId: type: string description: Channel ID this assignment belongs to channelType: type: string enum: - KIOSK - POS - ONLINE - TAKEAWAY description: Type of channel (KIOSK, POS, ONLINE, TAKEAWAY) isEnabled: type: boolean description: Whether this channel type is enabled createdAt: type: string format: date-time description: Creation timestamp required: - id - channelId - channelType - isEnabled - createdAt description: Channel type assignments required: - id - entityType - entityId - isActive - createdAt - updatedAt - assignments pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages required: - channels - pagination meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: summary: Create channel tags: - Channels description: Create a new channel with assignments requestBody: content: application/json: schema: type: object properties: entityType: type: string enum: - MENU - ITEM - LOCATION - MODIFIER - CATEGORY - MENU_LAYOUT - VARIANT_GROUP description: Type of entity entityId: type: string description: ID of the entity locationId: type: number nullable: true description: Location ID isActive: type: boolean default: true description: Whether channel is active assignments: type: array items: type: object properties: channelType: type: string enum: - KIOSK - POS - ONLINE - TAKEAWAY description: Type of channel isEnabled: type: boolean default: true description: Whether channel type is enabled required: - channelType description: Channel type assignments required: - entityType - entityId - assignments required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string description: Unique channel ID entityType: type: string enum: - MENU - ITEM - LOCATION - MODIFIER - CATEGORY - MENU_LAYOUT - VARIANT_GROUP description: Type of entity this channel applies to entityId: type: string description: ID of the entity locationId: type: number nullable: true description: Location ID this channel applies to isActive: type: boolean description: Whether channel is active createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp assignments: type: array items: type: object properties: id: type: string description: Unique assignment ID channelId: type: string description: Channel ID this assignment belongs to channelType: type: string enum: - KIOSK - POS - ONLINE - TAKEAWAY description: Type of channel (KIOSK, POS, ONLINE, TAKEAWAY) isEnabled: type: boolean description: Whether this channel type is enabled createdAt: type: string format: date-time description: Creation timestamp required: - id - channelId - channelType - isEnabled - createdAt description: Channel type assignments required: - id - entityType - entityId - isActive - createdAt - updatedAt - assignments meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/channels/{channelId}/assignments: post: summary: Add channel assignment tags: - Channels description: Add a new channel type assignment to an existing channel requestBody: content: application/json: schema: type: object properties: channelType: type: string enum: - KIOSK - POS - ONLINE - TAKEAWAY description: Type of channel isEnabled: type: boolean default: true description: Whether channel type is enabled required: - channelType required: true parameters: - schema: type: string in: path name: channelId required: true description: Channel ID responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string description: Unique assignment ID channelId: type: string description: Channel ID this assignment belongs to channelType: type: string enum: - KIOSK - POS - ONLINE - TAKEAWAY description: Type of channel (KIOSK, POS, ONLINE, TAKEAWAY) isEnabled: type: boolean description: Whether this channel type is enabled createdAt: type: string format: date-time description: Creation timestamp required: - id - channelId - channelType - isEnabled - createdAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/channels/{id}: get: summary: Get channel tags: - Channels description: Get a single channel by ID with its assignments parameters: - schema: type: string in: path name: id required: true description: Channel ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string description: Unique channel ID entityType: type: string enum: - MENU - ITEM - LOCATION - MODIFIER - CATEGORY - MENU_LAYOUT - VARIANT_GROUP description: Type of entity this channel applies to entityId: type: string description: ID of the entity locationId: type: number nullable: true description: Location ID this channel applies to isActive: type: boolean description: Whether channel is active createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp assignments: type: array items: type: object properties: id: type: string description: Unique assignment ID channelId: type: string description: Channel ID this assignment belongs to channelType: type: string enum: - KIOSK - POS - ONLINE - TAKEAWAY description: Type of channel (KIOSK, POS, ONLINE, TAKEAWAY) isEnabled: type: boolean description: Whether this channel type is enabled createdAt: type: string format: date-time description: Creation timestamp required: - id - channelId - channelType - isEnabled - createdAt description: Channel type assignments required: - id - entityType - entityId - isActive - createdAt - updatedAt - assignments meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: summary: Update channel tags: - Channels description: |- Update an existing channel **Permissions:** 🟠 `channels.update` requestBody: content: application/json: schema: type: object properties: isActive: type: boolean description: Whether channel is active parameters: - schema: type: string in: path name: id required: true description: Channel ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string description: Unique channel ID entityType: type: string enum: - MENU - ITEM - LOCATION - MODIFIER - CATEGORY - MENU_LAYOUT - VARIANT_GROUP description: Type of entity this channel applies to entityId: type: string description: ID of the entity locationId: type: number nullable: true description: Location ID this channel applies to isActive: type: boolean description: Whether channel is active createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp assignments: type: array items: type: object properties: id: type: string description: Unique assignment ID channelId: type: string description: Channel ID this assignment belongs to channelType: type: string enum: - KIOSK - POS - ONLINE - TAKEAWAY description: Type of channel (KIOSK, POS, ONLINE, TAKEAWAY) isEnabled: type: boolean description: Whether this channel type is enabled createdAt: type: string format: date-time description: Creation timestamp required: - id - channelId - channelType - isEnabled - createdAt description: Channel type assignments required: - id - entityType - entityId - isActive - createdAt - updatedAt - assignments meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete channel tags: - Channels description: Delete a channel and its assignments parameters: - schema: type: string in: path name: id required: true description: Channel ID responses: "200": description: Channel successfully deleted content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: deleted: type: boolean meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/channels/assignments/{assignmentId}: put: summary: Update channel assignment tags: - Channels description: Update an existing channel assignment requestBody: content: application/json: schema: type: object properties: isEnabled: type: boolean description: Whether channel type is enabled parameters: - schema: type: string in: path name: assignmentId required: true description: Assignment ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string description: Unique assignment ID channelId: type: string description: Channel ID this assignment belongs to channelType: type: string enum: - KIOSK - POS - ONLINE - TAKEAWAY description: Type of channel (KIOSK, POS, ONLINE, TAKEAWAY) isEnabled: type: boolean description: Whether this channel type is enabled createdAt: type: string format: date-time description: Creation timestamp required: - id - channelId - channelType - isEnabled - createdAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete channel assignment tags: - Channels description: |- Delete a channel assignment **Permissions:** 🔴 `channels.delete` parameters: - schema: type: string in: path name: assignmentId required: true description: Assignment ID responses: "200": description: Assignment successfully deleted content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: deleted: type: boolean meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/coursings: get: summary: List coursings tags: - Coursings description: |- List coursings with optional filtering **Permissions:** 🔵 `coursings.read` parameters: - schema: type: number in: query name: locationId required: false description: Filter by location ID - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: number minimum: 1 maximum: 100 default: 20 in: query name: limit required: false description: Items per page responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: coursings: type: array items: type: object properties: id: type: string description: Unique coursing ID (UUID) locationId: type: number description: Location ID this coursing belongs to title: type: string description: Coursing title (e.g., "Appetizer", "Main", "Dessert") order: type: number minimum: 0 maximum: 100 description: Display order (0-100) color: type: string nullable: true description: "Hex color code (e.g., #FF5733) for visual differentiation" createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - id - locationId - title - order - color - createdAt - updatedAt pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages required: - coursings - pagination meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: summary: Create coursing tags: - Coursings description: |- Create a new coursing **Permissions:** 🟢 `coursings.create` requestBody: content: application/json: schema: type: object properties: locationId: type: number description: Location ID title: type: string minLength: 1 description: Coursing title order: type: number minimum: 0 maximum: 100 description: Display order (0-100) color: type: string nullable: true description: "Hex color code (e.g., #FF5733)" required: - locationId - title - order required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string description: Unique coursing ID (UUID) locationId: type: number description: Location ID this coursing belongs to title: type: string description: Coursing title (e.g., "Appetizer", "Main", "Dessert") order: type: number minimum: 0 maximum: 100 description: Display order (0-100) color: type: string nullable: true description: "Hex color code (e.g., #FF5733) for visual differentiation" createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - id - locationId - title - order - color - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/coursings/{id}: get: summary: Get coursing tags: - Coursings description: |- Get a single coursing by ID **Permissions:** 🔵 `coursings.read` parameters: - schema: type: string in: path name: id required: true description: Coursing ID (UUID) responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string description: Unique coursing ID (UUID) locationId: type: number description: Location ID this coursing belongs to title: type: string description: Coursing title (e.g., "Appetizer", "Main", "Dessert") order: type: number minimum: 0 maximum: 100 description: Display order (0-100) color: type: string nullable: true description: "Hex color code (e.g., #FF5733) for visual differentiation" createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - id - locationId - title - order - color - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: summary: Update coursing tags: - Coursings description: |- Update an existing coursing **Permissions:** 🟠 `coursings.update` requestBody: content: application/json: schema: type: object properties: title: type: string minLength: 1 order: type: number minimum: 0 maximum: 100 color: type: string nullable: true description: "Hex color code (e.g., #FF5733)" parameters: - schema: type: string in: path name: id required: true description: Coursing ID (UUID) responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string description: Unique coursing ID (UUID) locationId: type: number description: Location ID this coursing belongs to title: type: string description: Coursing title (e.g., "Appetizer", "Main", "Dessert") order: type: number minimum: 0 maximum: 100 description: Display order (0-100) color: type: string nullable: true description: "Hex color code (e.g., #FF5733) for visual differentiation" createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - id - locationId - title - order - color - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete coursing tags: - Coursings description: |- Delete a coursing **Permissions:** 🔴 `coursings.delete` parameters: - schema: type: string in: path name: id required: true description: Coursing ID (UUID) responses: "200": description: Coursing successfully deleted content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: deleted: type: boolean meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/custom-tags: post: summary: Create custom tag tags: - Custom Tags description: |- Create a new custom tag and link it to an item **Permissions:** 🟢 `custom_tags.create` requestBody: content: application/json: schema: type: object properties: itemId: type: number description: Item ID to tag categoryHandle: type: string description: Category handle key: type: string minLength: 1 description: Tag key/name required: - itemId - categoryHandle - key required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Unique tag ID key: type: string description: Tag key/name categoryHandle: type: string description: Category handle categoryId: type: number description: Category ID languageId: type: number description: Language ID required: - id - key - categoryHandle - categoryId - languageId meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/custom-tags/link: post: summary: Link custom tag tags: - Custom Tags description: |- Link an existing custom tag to an item **Permissions:** 🟠 `custom_tags.update` requestBody: content: application/json: schema: type: object properties: itemId: type: number description: Item ID customTagId: type: number description: Custom tag ID to link required: - itemId - customTagId required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: success: type: boolean meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/custom-tags/search: get: summary: Search custom tags tags: - Custom Tags description: |- Search for custom tags by query string **Permissions:** 🔵 `custom_tags.read` parameters: - schema: type: string minLength: 3 in: query name: query required: true description: Search string (minimum 3 characters) responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: array items: type: object properties: id: type: number description: Unique tag ID key: type: string description: Tag key/name categoryHandle: type: string description: Category handle categoryId: type: number description: Category ID languageId: type: number description: Language ID required: - id - key - categoryHandle - categoryId - languageId meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/custom-tags/unlink: post: summary: Unlink custom tag tags: - Custom Tags description: |- Unlink a custom tag from an item **Permissions:** 🟠 `custom_tags.update` requestBody: content: application/json: schema: type: object properties: itemId: type: number description: Item ID customTagId: type: number description: Custom tag ID to unlink required: - itemId - customTagId required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: success: type: boolean meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/cwi/items: put: summary: Create or update a CWI item by EAN tags: - CWI description: >- Create or update a CWI item by EAN. If an item with the given EAN already exists for the company, it is updated. Otherwise, a new item is created. Returns 201 for creation, 200 for update. **Discount validation:** Must be between 50 and 90, and must end in 0 or 5 (e.g. 50, 55, 60, 65, 70, 75, 80, 85, 90). **Allergen codes:** Use two-letter codes (e.g. `AW` = Gluten, `AE` = Egg, `AM` = Milk). See the allergenCodes field for the full list. **Permissions:** ⚪ `cwi.write` requestBody: content: application/json: schema: type: object properties: ean: type: string description: EAN / article number (unique per company) example: "7310070771223" title: type: string description: Item title example: Sourdough Bread fullPrice: type: number description: Full price in cents (e.g. 5900 = 59 SEK) example: 5900 discount: type: number description: Discount percentage (50-90, must end in 0 or 5) minimum: 50 maximum: 90 example: 50 description: type: string description: Item description example: Freshly baked sourdough bread category: type: string enum: - DRINK - GROCERY - FULL_MEAL - BREAD - SWEETS - SNACK description: Item category preferences: type: array items: type: string enum: - GLUTEN_FREE - PORK - BEEF - CHICKEN - VEGAN - VEGETARIAN - FISH_PREF - SHELLFISH_PREF - LACTOSE_FREE description: Dietary preferences allergenCodes: type: array items: type: string enum: - AC - AE - AF - AM - AN - AP - AS - AU - AW - AY - BC - BM - GB - GO - GS - ML - NC - NL - NM - NR - SA - SC - SH - SM - SO - SP - SR - ST - SW - UM - UW - NONE description: "Allergen codes. Common codes: AW=Gluten, AE=Egg, AF=Fish, AM=Milk, AN=Nuts, AP=Peanuts, AY=Soya, UW=Wheat" required: - ean - title - fullPrice - discount required: true responses: "200": description: Item updated successfully content: application/json: schema: description: Item updated successfully type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Item ID ean: type: string nullable: true description: EAN / article number title: type: string description: Item title fullPrice: type: number description: Full price in cents discount: type: number description: Discount percentage (50-90, must end in 0 or 5) description: type: string nullable: true description: Item description companyId: type: number description: Company ID locationId: type: number nullable: true description: Location ID category: type: string nullable: true description: Category tag (DRINK, GROCERY, FULL_MEAL, BREAD, SWEETS, SNACK) preferences: type: array items: type: string description: Dietary preferences (VEGAN, VEGETARIAN, GLUTEN_FREE, etc.) allergenCodes: type: array items: type: string description: Allergen codes (AW=GLUTEN, AE=EGG, AM=MILK, etc.) createdAt: type: string format: date-time description: Creation timestamp required: - id - title - fullPrice - discount - companyId - createdAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "201": description: Item created successfully content: application/json: schema: description: Item created successfully type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Item ID ean: type: string nullable: true description: EAN / article number title: type: string description: Item title fullPrice: type: number description: Full price in cents discount: type: number description: Discount percentage (50-90, must end in 0 or 5) description: type: string nullable: true description: Item description companyId: type: number description: Company ID locationId: type: number nullable: true description: Location ID category: type: string nullable: true description: Category tag (DRINK, GROCERY, FULL_MEAL, BREAD, SWEETS, SNACK) preferences: type: array items: type: string description: Dietary preferences (VEGAN, VEGETARIAN, GLUTEN_FREE, etc.) allergenCodes: type: array items: type: string description: Allergen codes (AW=GLUTEN, AE=EGG, AM=MILK, etc.) createdAt: type: string format: date-time description: Creation timestamp required: - id - title - fullPrice - discount - companyId - createdAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 get: summary: List CWI items for company tags: - CWI description: |- List all CWI items (items with EAN) for the authenticated company. Supports pagination and optional filtering by location. **Permissions:** 🔵 `cwi.read` parameters: - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: number minimum: 1 maximum: 100 default: 50 in: query name: limit required: false description: Items per page - schema: type: number in: query name: locationId required: false description: Filter by location ID responses: "200": description: List of CWI items content: application/json: schema: description: List of CWI items type: object properties: status: type: string enum: - success data: type: object properties: items: type: array items: type: object properties: id: type: number description: Item ID ean: type: string nullable: true description: EAN / article number title: type: string description: Item title fullPrice: type: number description: Full price in cents discount: type: number description: Discount percentage (50-90, must end in 0 or 5) description: type: string nullable: true description: Item description companyId: type: number description: Company ID locationId: type: number nullable: true description: Location ID category: type: string nullable: true description: Category tag (DRINK, GROCERY, FULL_MEAL, BREAD, SWEETS, SNACK) preferences: type: array items: type: string description: Dietary preferences (VEGAN, VEGETARIAN, GLUTEN_FREE, etc.) allergenCodes: type: array items: type: string description: Allergen codes (AW=GLUTEN, AE=EGG, AM=MILK, etc.) createdAt: type: string format: date-time description: Creation timestamp required: - id - title - fullPrice - discount - companyId - createdAt pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages required: - items - pagination meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/cwi/items/{ean}: delete: summary: Delete a CWI item by EAN tags: - CWI description: >- Soft-delete a CWI item by EAN. Marks the item as deleted. The item can no longer be found via the list endpoint. **Permissions:** 🔴 `cwi.delete` parameters: - schema: type: string in: path name: ean required: true description: EAN / article number of the item to delete responses: "200": description: Item deleted successfully content: application/json: schema: description: Item deleted successfully type: object properties: status: type: string enum: - success data: type: object properties: message: type: string ean: type: string meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/data-streaming/connection: get: summary: Get connection details including BigQuery credentials and available datasets tags: - Data Streaming description: Get data streaming connection for current company responses: "200": description: Data streaming connection details content: application/json: schema: description: Data streaming connection details type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid companyId: type: integer status: type: string enum: - pending - active - suspended - inactive bqProjectId: type: string nullable: true bqDatasetId: type: string nullable: true gcpServiceAccountEmail: type: string nullable: true availableDatasets: type: array items: type: string currentMonthBytesScanned: type: integer lastUsageSyncAt: type: string format: date-time nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time activatedAt: type: string format: date-time nullable: true meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/data-streaming/usage: get: summary: Get monthly usage history including bytes scanned and estimated costs tags: - Data Streaming description: Get usage statistics for data streaming connection parameters: - schema: type: integer minimum: 1 maximum: 24 default: 3 in: query name: months required: false description: Number of months of usage history to return responses: "200": description: Usage statistics content: application/json: schema: description: Usage statistics type: object properties: status: type: string enum: - success data: type: object properties: months: type: array items: type: object properties: month: type: string description: Month in YYYY-MM format bytesScanned: type: integer queryCount: type: integer estimatedCostSek: type: number totalBytesScanned: type: integer totalQueryCount: type: integer totalCostSek: type: number meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/extended-waiting-time: get: tags: - Extended Waiting Time description: Get extended waiting time for a location parameters: - schema: type: number in: query name: locationId required: false description: Location ID (optional if X-Location-Id header is provided) responses: "200": description: Extended waiting time retrieved successfully content: application/json: schema: description: Extended waiting time retrieved successfully type: object properties: status: type: string enum: - success data: type: object properties: extendedWaitingTime: oneOf: - type: object properties: id: type: number description: Extended waiting time ID locationId: type: number description: Location ID endsAt: type: string format: date-time description: When the extended waiting time ends (ISO 8601) delayInMinutes: type: number nullable: true description: Delay in minutes (optional) required: - id - locationId - endsAt - type: "null" description: No extended waiting time set for this location required: - extendedWaitingTime meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: tags: - Extended Waiting Time description: Create or update extended waiting time for a location requestBody: content: application/json: schema: type: object properties: locationId: type: number description: Location ID endsAt: type: string format: date-time description: When the extended waiting time ends (ISO 8601) delayInMinutes: type: number nullable: true description: Delay in minutes (optional) required: - locationId - endsAt required: true responses: "201": description: Extended waiting time created/updated successfully content: application/json: schema: description: Extended waiting time created/updated successfully type: object properties: status: type: string enum: - success data: type: object properties: extendedWaitingTime: type: object properties: id: type: number description: Extended waiting time ID locationId: type: number description: Location ID endsAt: type: string format: date-time description: When the extended waiting time ends (ISO 8601) delayInMinutes: type: number nullable: true description: Delay in minutes (optional) required: - id - locationId - endsAt required: - extendedWaitingTime meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: tags: - Extended Waiting Time description: Delete extended waiting time by location ID parameters: - schema: type: number in: query name: locationId required: true description: Location ID responses: "200": description: Extended waiting time deleted successfully content: application/json: schema: description: Extended waiting time deleted successfully type: object properties: status: type: string enum: - success data: type: object properties: deleted: type: boolean enum: - true id: type: number description: Deleted extended waiting time ID required: - deleted - id meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/extended-waiting-time/{id}: delete: tags: - Extended Waiting Time description: Delete extended waiting time by ID parameters: - schema: type: number in: path name: id required: true description: Extended waiting time ID responses: "200": description: Extended waiting time deleted successfully content: application/json: schema: description: Extended waiting time deleted successfully type: object properties: status: type: string enum: - success data: type: object properties: deleted: type: boolean enum: - true id: type: number description: Deleted extended waiting time ID required: - deleted - id meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /health: get: tags: - Internal description: Simple health check endpoint. Returns basic status of database and Redis dependencies. Used for quick health verification. x-internal: true responses: "200": description: Service is healthy content: application/json: schema: type: object properties: status: type: string enum: - healthy - unhealthy description: Overall service status checks: type: object properties: database: type: boolean description: Database connectivity redis: type: boolean description: Redis connectivity required: - database - redis timestamp: type: string format: date-time description: Check timestamp required: - status - checks - timestamp example: status: healthy checks: database: true redis: true timestamp: 2025-01-15T10:30:00.000Z "503": description: Service is unhealthy content: application/json: schema: type: object properties: status: type: string enum: - unhealthy checks: type: object properties: database: type: boolean redis: type: boolean timestamp: type: string format: date-time example: status: unhealthy checks: database: true redis: false timestamp: 2025-01-15T10:30:00.000Z /live: get: tags: - Internal description: Kubernetes liveness probe. Lightweight check that the service process is running. Does not check external dependencies. Use to determine if the service should be restarted. x-internal: true responses: "200": description: Service is alive content: application/json: schema: type: object properties: status: type: string enum: - alive description: Process status timestamp: type: string format: date-time description: Check timestamp uptime: type: number description: Service uptime in seconds required: - status - timestamp - uptime example: status: alive timestamp: 2025-01-15T10:30:00.000Z uptime: 3600 /ready: get: tags: - Internal description: Kubernetes readiness probe with detailed dependency status. Returns response times and error details for each dependency. Use for determining if the service is ready to receive traffic. x-internal: true responses: "200": description: Service is ready to receive traffic content: application/json: schema: type: object properties: status: type: string enum: - healthy - degraded - unhealthy description: Overall status timestamp: type: string format: date-time description: Check timestamp uptime: type: number description: Service uptime in seconds dependencies: type: object properties: database: type: object properties: status: type: string enum: - healthy - unhealthy - degraded description: Dependency health status responseTimeMs: type: number description: Response time to check dependency in milliseconds error: type: string description: Error message if unhealthy required: - status redis: type: object properties: status: type: string enum: - healthy - unhealthy - degraded description: Dependency health status responseTimeMs: type: number description: Response time to check dependency in milliseconds error: type: string description: Error message if unhealthy required: - status required: - database - redis required: - status - timestamp - uptime - dependencies example: status: healthy timestamp: 2025-01-15T10:30:00.000Z uptime: 3600 dependencies: database: status: healthy responseTimeMs: 5 redis: status: healthy responseTimeMs: 2 "503": description: Service is not ready content: application/json: schema: type: object properties: status: type: string enum: - degraded - unhealthy timestamp: type: string format: date-time uptime: type: number dependencies: type: object properties: database: type: object properties: status: type: string enum: - healthy - unhealthy - degraded description: Dependency health status responseTimeMs: type: number description: Response time to check dependency in milliseconds error: type: string description: Error message if unhealthy required: - status redis: type: object properties: status: type: string enum: - healthy - unhealthy - degraded description: Dependency health status responseTimeMs: type: number description: Response time to check dependency in milliseconds error: type: string description: Error message if unhealthy required: - status example: status: unhealthy timestamp: 2025-01-15T10:30:00.000Z uptime: 3600 dependencies: database: status: healthy responseTimeMs: 5 redis: status: unhealthy responseTimeMs: 1000 error: Connection refused /api/v1/inventory: get: summary: List inventory items tags: - Inventory description: >- Retrieve a paginated list of inventory items with filtering and search capabilities **Permissions:** 🔵 `inventory.read` parameters: - schema: type: number in: query name: locationId required: false description: Filter by location ID - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: number minimum: 1 maximum: 100 default: 20 in: query name: limit required: false description: Items per page - schema: type: string default: title in: query name: sort required: false description: Field to sort by (title, basePrice, createdAt, etc.) - schema: type: string enum: - asc - desc default: asc in: query name: order required: false description: Sort order - schema: type: boolean default: false in: query name: deleted required: false description: Include deleted items - schema: type: string in: query name: search required: false description: Search term for title/description - schema: type: array items: type: string in: query name: tags required: false description: Filter by tags - schema: type: string in: query name: itemType required: false description: Filter by item type - schema: type: boolean default: false in: query name: excludeUnmapped required: false description: When true and the location has an active POS integration, drop items that lack an integration_resource_mappings row. Used by storefront-web to hide items that would otherwise produce empty kitchen tickets. responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: items: type: array items: type: object properties: id: type: number description: Unique inventory item ID locationId: type: number description: Location ID this item belongs to title: type: string description: Item title/name description: type: string nullable: true description: Item description basePrice: type: number nullable: true description: Base price in cents (deprecated - use calculatedPrice) calculatedPrice: type: number description: Final calculated price in cents after applying all pricings itemType: type: string nullable: true description: Item type (food, beverage, etc.) vatId: type: integer nullable: true description: VAT ID vatValue: type: number nullable: true description: VAT value takeawayVatId: type: integer nullable: true description: Takeaway VAT ID takeawayVatValue: type: number nullable: true description: Takeaway VAT value isAvailable: type: boolean description: Whether item is available for ordering deleted: type: boolean description: Whether item is soft-deleted madeToOrder: type: boolean description: Whether item is made to order tags: type: object description: Item tags grouped by type createdDate: type: string format: date-time description: Creation timestamp channelAvailability: type: object description: Channel availability flags properties: online: type: boolean description: Available on online channel qr: type: boolean description: Available on QR channel kiosk: type: boolean description: Available on kiosk channel pos: type: boolean description: Available on POS channel posIntegration: type: object description: POS integration mapping status. Present only when the location has an enabled integration_type='pos' config (e.g. Trivec, Domino). When isMapped is false, the item is missing an integration_resource_mappings row and orders containing it will reach the POS as an empty kitchen ticket. properties: integrationConfigId: type: number description: integration_configs.id of the active POS integration provider: type: string description: Human-readable integration name, e.g. "Trivec" or "Domino" externalItemId: type: string nullable: true description: External POS item id if mapped, null otherwise isMapped: type: boolean description: True iff an integration_resource_mappings row exists for this item under the active POS config required: - integrationConfigId - provider - externalItemId - isMapped required: - id - locationId - title - deleted - createdDate - madeToOrder pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages required: - items - pagination meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: summary: Create inventory item tags: - Inventory description: |- Add a new menu item or product to the inventory **Permissions:** 🟢 `inventory.create` requestBody: content: application/json: schema: type: object properties: locationId: type: number description: Location ID title: type: string minLength: 1 maxLength: 255 description: Item title description: type: string nullable: true maxLength: 255 description: Item description basePrice: type: number minimum: 0 description: Base price in cents itemType: type: string maxLength: 255 description: Item type tags: anyOf: - type: array items: type: string - type: object additionalProperties: true description: Item tags (array of strings or grouped tags object) vatId: type: integer nullable: true description: VAT ID vatValue: type: number nullable: true description: VAT value (legacy) accountIds: type: array items: type: string description: Bookkeeping account IDs printerGroupIds: type: array items: type: string description: Printer group IDs variantGroupIds: type: array items: type: number description: Variant group IDs visibility: type: array items: type: string description: Visibility settings additionalProperties: true required: - locationId - title - basePrice - itemType required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Unique inventory item ID locationId: type: number description: Location ID this item belongs to title: type: string description: Item title/name description: type: string nullable: true description: Item description basePrice: type: number nullable: true description: Base price in cents (deprecated - use calculatedPrice) calculatedPrice: type: number description: Final calculated price in cents after applying all pricings itemType: type: string nullable: true description: Item type (food, beverage, etc.) vatId: type: integer nullable: true description: VAT ID vatValue: type: number nullable: true description: VAT value takeawayVatId: type: integer nullable: true description: Takeaway VAT ID takeawayVatValue: type: number nullable: true description: Takeaway VAT value isAvailable: type: boolean description: Whether item is available for ordering deleted: type: boolean description: Whether item is soft-deleted madeToOrder: type: boolean description: Whether item is made to order tags: type: object description: Item tags grouped by type createdDate: type: string format: date-time description: Creation timestamp channelAvailability: type: object description: Channel availability flags properties: online: type: boolean description: Available on online channel qr: type: boolean description: Available on QR channel kiosk: type: boolean description: Available on kiosk channel pos: type: boolean description: Available on POS channel posIntegration: type: object description: POS integration mapping status. Present only when the location has an enabled integration_type='pos' config (e.g. Trivec, Domino). When isMapped is false, the item is missing an integration_resource_mappings row and orders containing it will reach the POS as an empty kitchen ticket. properties: integrationConfigId: type: number description: integration_configs.id of the active POS integration provider: type: string description: Human-readable integration name, e.g. "Trivec" or "Domino" externalItemId: type: string nullable: true description: External POS item id if mapped, null otherwise isMapped: type: boolean description: True iff an integration_resource_mappings row exists for this item under the active POS config required: - integrationConfigId - provider - externalItemId - isMapped required: - id - locationId - title - deleted - createdDate - madeToOrder meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/inventory/{id}: get: summary: Get inventory item tags: - Inventory description: |- Retrieve detailed information about a specific inventory item by its ID **Permissions:** 🔵 `inventory.read` parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: id required: true description: Inventory item ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Unique inventory item ID locationId: type: number description: Location ID this item belongs to title: type: string description: Item title/name description: type: string nullable: true description: Item description basePrice: type: number nullable: true description: Base price in cents (deprecated - use calculatedPrice) calculatedPrice: type: number description: Final calculated price in cents after applying all pricings itemType: type: string nullable: true description: Item type (food, beverage, etc.) vatId: type: integer nullable: true description: VAT ID vatValue: type: number nullable: true description: VAT value takeawayVatId: type: integer nullable: true description: Takeaway VAT ID takeawayVatValue: type: number nullable: true description: Takeaway VAT value isAvailable: type: boolean description: Whether item is available for ordering deleted: type: boolean description: Whether item is soft-deleted madeToOrder: type: boolean description: Whether item is made to order tags: type: object description: Item tags grouped by type createdDate: type: string format: date-time description: Creation timestamp channelAvailability: type: object description: Channel availability flags properties: online: type: boolean description: Available on online channel qr: type: boolean description: Available on QR channel kiosk: type: boolean description: Available on kiosk channel pos: type: boolean description: Available on POS channel posIntegration: type: object description: POS integration mapping status. Present only when the location has an enabled integration_type='pos' config (e.g. Trivec, Domino). When isMapped is false, the item is missing an integration_resource_mappings row and orders containing it will reach the POS as an empty kitchen ticket. properties: integrationConfigId: type: number description: integration_configs.id of the active POS integration provider: type: string description: Human-readable integration name, e.g. "Trivec" or "Domino" externalItemId: type: string nullable: true description: External POS item id if mapped, null otherwise isMapped: type: boolean description: True iff an integration_resource_mappings row exists for this item under the active POS config required: - integrationConfigId - provider - externalItemId - isMapped required: - id - locationId - title - deleted - createdDate - madeToOrder meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: summary: Update inventory item tags: - Inventory description: |- Modify an existing inventory item's details **Permissions:** 🟠 `inventory.update` requestBody: content: application/json: schema: type: object properties: title: type: string minLength: 1 maxLength: 255 description: type: string nullable: true maxLength: 255 basePrice: type: number minimum: 0 itemType: type: string maxLength: 255 available: type: boolean takeawayVatId: type: integer nullable: true integrationId: type: string nullable: true maxLength: 255 integrationItemId: type: string nullable: true maxLength: 255 imageUrl: type: string nullable: true maxLength: 255 externalImageUrl: type: string nullable: true maxLength: 255 context: anyOf: - type: object additionalProperties: true - type: string - type: "null" titlePrep: type: string nullable: true maxLength: 255 color: type: string nullable: true maxLength: 255 kitchenSortOrder: type: integer nullable: true description: Sort order within groups on printed kitchen tickets and KDS. Lower numbers appear first. NULL = sort last alphabetically. additionalProperties: true parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: id required: true description: Inventory item ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Unique inventory item ID locationId: type: number description: Location ID this item belongs to title: type: string description: Item title/name description: type: string nullable: true description: Item description basePrice: type: number nullable: true description: Base price in cents (deprecated - use calculatedPrice) calculatedPrice: type: number description: Final calculated price in cents after applying all pricings itemType: type: string nullable: true description: Item type (food, beverage, etc.) vatId: type: integer nullable: true description: VAT ID vatValue: type: number nullable: true description: VAT value takeawayVatId: type: integer nullable: true description: Takeaway VAT ID takeawayVatValue: type: number nullable: true description: Takeaway VAT value isAvailable: type: boolean description: Whether item is available for ordering deleted: type: boolean description: Whether item is soft-deleted madeToOrder: type: boolean description: Whether item is made to order tags: type: object description: Item tags grouped by type createdDate: type: string format: date-time description: Creation timestamp channelAvailability: type: object description: Channel availability flags properties: online: type: boolean description: Available on online channel qr: type: boolean description: Available on QR channel kiosk: type: boolean description: Available on kiosk channel pos: type: boolean description: Available on POS channel posIntegration: type: object description: POS integration mapping status. Present only when the location has an enabled integration_type='pos' config (e.g. Trivec, Domino). When isMapped is false, the item is missing an integration_resource_mappings row and orders containing it will reach the POS as an empty kitchen ticket. properties: integrationConfigId: type: number description: integration_configs.id of the active POS integration provider: type: string description: Human-readable integration name, e.g. "Trivec" or "Domino" externalItemId: type: string nullable: true description: External POS item id if mapped, null otherwise isMapped: type: boolean description: True iff an integration_resource_mappings row exists for this item under the active POS config required: - integrationConfigId - provider - externalItemId - isMapped required: - id - locationId - title - deleted - createdDate - madeToOrder meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete inventory item tags: - Inventory description: >- Soft-delete an inventory item (marks as deleted without removing from database) **Permissions:** 🔴 `inventory.delete` parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: id required: true description: Inventory item ID responses: "200": description: Item successfully deleted content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: deleted: type: boolean meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/inventory/{id}/inheritance: put: summary: Update item inheritance tags: - Inventory description: >- Update inheritance settings for an inventory item in a multi-location hierarchy **Permissions:** 🟠 `inventory.update` requestBody: content: application/json: schema: type: object properties: inheritToChildren: type: boolean description: Whether this item should be inherited to child locations allowedOverrides: type: array items: type: string description: Fields that child locations are allowed to override parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: id required: true description: Inventory item ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number inheritToChildren: type: boolean allowedOverrides: type: array items: type: string meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/inventory/{id}/overrides: get: summary: Get item overrides tags: - Inventory description: |- Get all location-specific overrides for an inherited inventory item **Permissions:** 🔵 `inventory.read` parameters: - schema: type: number in: query name: locationId required: false description: Filter overrides by location ID - schema: type: string pattern: ^[0-9]+$ in: path name: id required: true description: Inventory item ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: overrides: type: array items: type: object properties: locationId: type: number field: type: string value: type: object additionalProperties: true meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: summary: Update item overrides tags: - Inventory description: |- Update location-specific overrides for an inherited inventory item **Permissions:** 🟠 `inventory.update` requestBody: content: application/json: schema: type: object additionalProperties: true description: Fields to override at this location description: Fields to override at this location parameters: - schema: type: number in: query name: locationId required: false description: Location ID for the override - schema: type: string pattern: ^[0-9]+$ in: path name: id required: true description: Inventory item ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number overrides: type: object additionalProperties: true meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/inventory/{itemId}/availability: post: summary: Toggle item availability tags: - Inventory description: |- Enable or disable an inventory item for customer ordering **Permissions:** 🟠 `inventory.update` requestBody: content: application/json: schema: type: object properties: action: type: string enum: - ACTIVATE - DEACTIVATE description: "Action to perform: ACTIVATE to make item available, DEACTIVATE to hide it" required: - action required: true parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: itemId required: true description: Inventory item ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: itemId: type: number description: Inventory item ID action: type: string enum: - ACTIVATE - DEACTIVATE description: Action performed isAvailable: type: boolean description: Current availability status required: - itemId - action - isAvailable meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/inventory/validate: post: summary: Validate inventory items tags: - Inventory description: Validate inventory items and variants before creating an order. Returns validation results for each item. requestBody: content: application/json: schema: type: object required: - locationId - items properties: locationId: type: number minimum: 1 items: type: array minItems: 1 items: type: object required: - itemId properties: itemId: type: number minimum: 1 variants: type: array items: type: object required: - id additionalProperties: true properties: id: type: number minimum: 1 quantity: type: number minimum: 0.01 quantity: type: number minimum: 1 menuId: type: string validateMenu: type: boolean required: true responses: "200": description: Validation response containing valid and invalid items with nested variant structures content: application/json: schema: type: object additionalProperties: true description: Validation response containing valid and invalid items with nested variant structures "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/invoice-location-settings: get: summary: Get invoice location settings tags: - Invoices description: >- Retrieve invoice settings for a specific location. Creates default settings if none exist. **Permissions:** 🔵 `invoices.read` parameters: - schema: type: number in: query name: locationId required: true description: Location ID to fetch settings for (required) responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Settings UUID locationId: type: number description: Location ID defaultPaymentTermsDays: type: number description: Default payment terms in days default: 30 invoiceNumberPrefix: type: string nullable: true description: Prefix for invoice numbers (e.g., "INV") invoiceNumberCounter: type: number description: Current invoice number counter minInvoiceAmount: type: number description: Minimum amount for invoicing senderName: type: string nullable: true description: Sender/company name senderAddressLine1: type: string nullable: true description: Sender address line 1 senderAddressLine2: type: string nullable: true description: Sender address line 2 senderPostalCode: type: string nullable: true description: Sender postal code senderCity: type: string nullable: true description: Sender city senderCountry: type: string nullable: true description: Sender country senderEmail: type: string nullable: true description: Sender email address senderPhone: type: string nullable: true description: Sender phone number senderOrganizationNumber: type: string nullable: true description: Sender organization number senderVatNumber: type: string nullable: true description: Sender VAT number bankAccountNumber: type: string nullable: true description: Bank account number bankName: type: string nullable: true description: Bank name swiftBic: type: string nullable: true description: SWIFT/BIC code iban: type: string nullable: true description: IBAN paymentReferencePrefix: type: string nullable: true description: Payment reference prefix invoiceFooterText: type: string nullable: true description: Footer text for invoices invoiceTermsText: type: string nullable: true description: Terms and conditions text latePaymentFee: type: number description: Late payment fee amount latePaymentInterestRate: type: number description: Late payment interest rate (percentage) autoGenerateEnabled: type: boolean description: Enable automatic invoice generation autoSendOnGeneration: type: boolean description: Automatically send invoices when generated collectionPeriodType: type: string enum: - calendar_month - rolling_30_days - weekly description: Collection period type for auto-invoicing reminderEnabled: type: boolean description: Enable payment reminders firstReminderDaysAfterDue: type: number description: Days after due date for first reminder secondReminderDaysAfterDue: type: number description: Days after due date for second reminder thirdReminderDaysAfterDue: type: number description: Days after due date for third reminder reminderFeeAmount: type: number description: Fee amount added per reminder autoMarkOverdueDays: type: number description: Days after due date to auto-mark as overdue currency: type: string description: Currency code (e.g., SEK, EUR) createdAt: type: string format: date-time description: Created timestamp updatedAt: type: string format: date-time description: Updated timestamp required: - id - locationId - defaultPaymentTermsDays - invoiceNumberCounter - minInvoiceAmount - latePaymentFee - latePaymentInterestRate - autoGenerateEnabled - autoSendOnGeneration - collectionPeriodType - reminderEnabled - firstReminderDaysAfterDue - secondReminderDaysAfterDue - thirdReminderDaysAfterDue - reminderFeeAmount - autoMarkOverdueDays - currency - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: summary: Update invoice location settings tags: - Invoices description: >- Update invoice settings for a specific location. Creates settings if they do not exist (upsert). All fields except locationId are optional for partial updates. **Permissions:** 🟠 `invoices.update` requestBody: content: application/json: schema: type: object properties: locationId: type: number description: Location ID (required) defaultPaymentTermsDays: type: number description: Default payment terms in days invoiceNumberPrefix: type: string nullable: true description: Prefix for invoice numbers minInvoiceAmount: type: number description: Minimum amount for invoicing senderName: type: string nullable: true description: Sender/company name senderAddressLine1: type: string nullable: true description: Sender address line 1 senderAddressLine2: type: string nullable: true description: Sender address line 2 senderPostalCode: type: string nullable: true description: Sender postal code senderCity: type: string nullable: true description: Sender city senderCountry: type: string nullable: true description: Sender country senderEmail: type: string nullable: true description: Sender email address senderPhone: type: string nullable: true description: Sender phone number senderOrganizationNumber: type: string nullable: true description: Sender organization number senderVatNumber: type: string nullable: true description: Sender VAT number bankAccountNumber: type: string nullable: true description: Bank account number bankName: type: string nullable: true description: Bank name swiftBic: type: string nullable: true description: SWIFT/BIC code iban: type: string nullable: true description: IBAN paymentReferencePrefix: type: string nullable: true description: Payment reference prefix invoiceFooterText: type: string nullable: true description: Footer text for invoices invoiceTermsText: type: string nullable: true description: Terms and conditions text latePaymentFee: type: number description: Late payment fee amount latePaymentInterestRate: type: number description: Late payment interest rate (percentage) autoGenerateEnabled: type: boolean description: Enable automatic invoice generation autoSendOnGeneration: type: boolean description: Automatically send invoices when generated collectionPeriodType: type: string enum: - calendar_month - rolling_30_days - weekly description: Collection period type for auto-invoicing reminderEnabled: type: boolean description: Enable payment reminders firstReminderDaysAfterDue: type: number description: Days after due date for first reminder secondReminderDaysAfterDue: type: number description: Days after due date for second reminder thirdReminderDaysAfterDue: type: number description: Days after due date for third reminder reminderFeeAmount: type: number description: Fee amount added per reminder autoMarkOverdueDays: type: number description: Days after due date to auto-mark as overdue currency: type: string description: Currency code (e.g., SEK, EUR) required: - locationId required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Settings UUID locationId: type: number description: Location ID defaultPaymentTermsDays: type: number description: Default payment terms in days default: 30 invoiceNumberPrefix: type: string nullable: true description: Prefix for invoice numbers (e.g., "INV") invoiceNumberCounter: type: number description: Current invoice number counter minInvoiceAmount: type: number description: Minimum amount for invoicing senderName: type: string nullable: true description: Sender/company name senderAddressLine1: type: string nullable: true description: Sender address line 1 senderAddressLine2: type: string nullable: true description: Sender address line 2 senderPostalCode: type: string nullable: true description: Sender postal code senderCity: type: string nullable: true description: Sender city senderCountry: type: string nullable: true description: Sender country senderEmail: type: string nullable: true description: Sender email address senderPhone: type: string nullable: true description: Sender phone number senderOrganizationNumber: type: string nullable: true description: Sender organization number senderVatNumber: type: string nullable: true description: Sender VAT number bankAccountNumber: type: string nullable: true description: Bank account number bankName: type: string nullable: true description: Bank name swiftBic: type: string nullable: true description: SWIFT/BIC code iban: type: string nullable: true description: IBAN paymentReferencePrefix: type: string nullable: true description: Payment reference prefix invoiceFooterText: type: string nullable: true description: Footer text for invoices invoiceTermsText: type: string nullable: true description: Terms and conditions text latePaymentFee: type: number description: Late payment fee amount latePaymentInterestRate: type: number description: Late payment interest rate (percentage) autoGenerateEnabled: type: boolean description: Enable automatic invoice generation autoSendOnGeneration: type: boolean description: Automatically send invoices when generated collectionPeriodType: type: string enum: - calendar_month - rolling_30_days - weekly description: Collection period type for auto-invoicing reminderEnabled: type: boolean description: Enable payment reminders firstReminderDaysAfterDue: type: number description: Days after due date for first reminder secondReminderDaysAfterDue: type: number description: Days after due date for second reminder thirdReminderDaysAfterDue: type: number description: Days after due date for third reminder reminderFeeAmount: type: number description: Fee amount added per reminder autoMarkOverdueDays: type: number description: Days after due date to auto-mark as overdue currency: type: string description: Currency code (e.g., SEK, EUR) createdAt: type: string format: date-time description: Created timestamp updatedAt: type: string format: date-time description: Updated timestamp required: - id - locationId - defaultPaymentTermsDays - invoiceNumberCounter - minInvoiceAmount - latePaymentFee - latePaymentInterestRate - autoGenerateEnabled - autoSendOnGeneration - collectionPeriodType - reminderEnabled - firstReminderDaysAfterDue - secondReminderDaysAfterDue - thirdReminderDaysAfterDue - reminderFeeAmount - autoMarkOverdueDays - currency - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/invoice-recipients: get: summary: List invoice recipients tags: - Invoices description: >- List all invoice recipients for a location with optional filtering and pagination. **Permissions:** 🔵 `invoices.read` parameters: - schema: type: number in: query name: locationId required: true description: Location ID (required) - schema: type: boolean in: query name: isActive required: false description: Filter by active status - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: number minimum: 1 maximum: 100 default: 50 in: query name: limit required: false description: Items per page responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: items: type: array items: type: object properties: id: type: string format: uuid description: Recipient UUID locationId: type: number description: Location ID name: type: string description: Recipient name email: type: string description: Email address organizationName: type: string nullable: true description: Organization/company name organizationNumber: type: string nullable: true description: Organization number phone: type: string nullable: true description: Phone number billingAddressLine1: type: string nullable: true description: Address line 1 billingAddressLine2: type: string nullable: true description: Address line 2 postalCode: type: string nullable: true description: Postal code city: type: string nullable: true description: City country: type: string nullable: true description: Country reference: type: string nullable: true description: Reference/PO number contactPerson: type: string nullable: true description: Contact person name vatNumber: type: string nullable: true description: VAT number totalInvoicedAmount: type: number description: Total amount invoiced to this recipient totalPaidAmount: type: number description: Total amount paid by this recipient outstandingAmount: type: number description: Outstanding amount (unpaid) invoiceCount: type: number description: Number of invoices sent to this recipient isActive: type: boolean description: Whether the recipient is active createdAt: type: string format: date-time description: Created timestamp updatedAt: type: string format: date-time description: Updated timestamp required: - id - locationId - name - email - totalInvoicedAmount - totalPaidAmount - outstandingAmount - invoiceCount - isActive - createdAt - updatedAt pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages required: - items - pagination meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: summary: Create invoice recipient tags: - Invoices description: |- Create a new invoice recipient for a location. **Permissions:** 🟢 `invoices.create` requestBody: content: application/json: schema: type: object properties: locationId: type: number description: Location ID (required) name: type: string description: Recipient name (required) email: type: string description: Email address (required) organizationName: type: string description: Organization/company name organizationNumber: type: string description: Organization number phone: type: string description: Phone number billingAddressLine1: type: string description: Address line 1 billingAddressLine2: type: string description: Address line 2 postalCode: type: string description: Postal code city: type: string description: City country: type: string description: Country reference: type: string description: Reference/PO number contactPerson: type: string description: Contact person name vatNumber: type: string description: VAT number required: - locationId - name - email required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Recipient UUID locationId: type: number description: Location ID name: type: string description: Recipient name email: type: string description: Email address organizationName: type: string nullable: true description: Organization/company name organizationNumber: type: string nullable: true description: Organization number phone: type: string nullable: true description: Phone number billingAddressLine1: type: string nullable: true description: Address line 1 billingAddressLine2: type: string nullable: true description: Address line 2 postalCode: type: string nullable: true description: Postal code city: type: string nullable: true description: City country: type: string nullable: true description: Country reference: type: string nullable: true description: Reference/PO number contactPerson: type: string nullable: true description: Contact person name vatNumber: type: string nullable: true description: VAT number totalInvoicedAmount: type: number description: Total amount invoiced to this recipient totalPaidAmount: type: number description: Total amount paid by this recipient outstandingAmount: type: number description: Outstanding amount (unpaid) invoiceCount: type: number description: Number of invoices sent to this recipient isActive: type: boolean description: Whether the recipient is active createdAt: type: string format: date-time description: Created timestamp updatedAt: type: string format: date-time description: Updated timestamp required: - id - locationId - name - email - totalInvoicedAmount - totalPaidAmount - outstandingAmount - invoiceCount - isActive - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/invoice-recipients/{recipientId}: get: summary: Get invoice recipient tags: - Invoices description: |- Get a single invoice recipient by ID. **Permissions:** 🔵 `invoices.read` parameters: - schema: type: string format: uuid in: path name: recipientId required: true description: Recipient UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Recipient UUID locationId: type: number description: Location ID name: type: string description: Recipient name email: type: string description: Email address organizationName: type: string nullable: true description: Organization/company name organizationNumber: type: string nullable: true description: Organization number phone: type: string nullable: true description: Phone number billingAddressLine1: type: string nullable: true description: Address line 1 billingAddressLine2: type: string nullable: true description: Address line 2 postalCode: type: string nullable: true description: Postal code city: type: string nullable: true description: City country: type: string nullable: true description: Country reference: type: string nullable: true description: Reference/PO number contactPerson: type: string nullable: true description: Contact person name vatNumber: type: string nullable: true description: VAT number totalInvoicedAmount: type: number description: Total amount invoiced to this recipient totalPaidAmount: type: number description: Total amount paid by this recipient outstandingAmount: type: number description: Outstanding amount (unpaid) invoiceCount: type: number description: Number of invoices sent to this recipient isActive: type: boolean description: Whether the recipient is active createdAt: type: string format: date-time description: Created timestamp updatedAt: type: string format: date-time description: Updated timestamp required: - id - locationId - name - email - totalInvoicedAmount - totalPaidAmount - outstandingAmount - invoiceCount - isActive - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: summary: Update invoice recipient tags: - Invoices description: >- Update an existing invoice recipient. All fields are optional for partial updates. **Permissions:** 🟠 `invoices.update` requestBody: content: application/json: schema: type: object properties: name: type: string description: Recipient name email: type: string description: Email address organizationName: type: string nullable: true description: Organization/company name organizationNumber: type: string nullable: true description: Organization number phone: type: string nullable: true description: Phone number billingAddressLine1: type: string nullable: true description: Address line 1 billingAddressLine2: type: string nullable: true description: Address line 2 postalCode: type: string nullable: true description: Postal code city: type: string nullable: true description: City country: type: string nullable: true description: Country reference: type: string nullable: true description: Reference/PO number contactPerson: type: string nullable: true description: Contact person name vatNumber: type: string nullable: true description: VAT number isActive: type: boolean description: Whether the recipient is active parameters: - schema: type: string format: uuid in: path name: recipientId required: true description: Recipient UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Recipient UUID locationId: type: number description: Location ID name: type: string description: Recipient name email: type: string description: Email address organizationName: type: string nullable: true description: Organization/company name organizationNumber: type: string nullable: true description: Organization number phone: type: string nullable: true description: Phone number billingAddressLine1: type: string nullable: true description: Address line 1 billingAddressLine2: type: string nullable: true description: Address line 2 postalCode: type: string nullable: true description: Postal code city: type: string nullable: true description: City country: type: string nullable: true description: Country reference: type: string nullable: true description: Reference/PO number contactPerson: type: string nullable: true description: Contact person name vatNumber: type: string nullable: true description: VAT number totalInvoicedAmount: type: number description: Total amount invoiced to this recipient totalPaidAmount: type: number description: Total amount paid by this recipient outstandingAmount: type: number description: Outstanding amount (unpaid) invoiceCount: type: number description: Number of invoices sent to this recipient isActive: type: boolean description: Whether the recipient is active createdAt: type: string format: date-time description: Created timestamp updatedAt: type: string format: date-time description: Updated timestamp required: - id - locationId - name - email - totalInvoicedAmount - totalPaidAmount - outstandingAmount - invoiceCount - isActive - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete invoice recipient tags: - Invoices description: |- Soft-delete an invoice recipient (sets isActive to false). **Permissions:** 🔴 `invoices.delete` parameters: - schema: type: string format: uuid in: path name: recipientId required: true description: Recipient UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: deleted: type: boolean enum: - true required: - deleted meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/invoice-recipients/{recipientId}/rules: get: summary: List recipient rules tags: - Invoices description: |- List all active eligibility rules for an invoice recipient. **Permissions:** 🔵 `invoices.read` parameters: - schema: type: string format: uuid in: path name: recipientId required: true description: Recipient UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: rules: type: array items: type: object properties: id: type: string format: uuid description: Rule UUID recipientId: type: string format: uuid description: Recipient UUID locationId: type: number description: Location ID ruleType: type: string enum: - email_exact - email_wildcard - user_id description: "Type of rule: email_exact (exact match), email_wildcard (pattern match), user_id (user ID match)" ruleValue: type: string description: Rule value (email, pattern, or user ID) isActive: type: boolean description: Whether the rule is active maxCreditLimit: type: number nullable: true description: Maximum credit limit for auto-invoicing autoApprove: type: boolean description: Auto-approve invoices matching this rule createdAt: type: string format: date-time description: Created timestamp updatedAt: type: string format: date-time description: Updated timestamp required: - id - recipientId - locationId - ruleType - ruleValue - isActive - autoApprove - createdAt - updatedAt required: - rules meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: summary: Create recipient rule tags: - Invoices description: |- Create a new eligibility rule for automatic invoice assignment. **Permissions:** 🟢 `invoices.create` requestBody: content: application/json: schema: type: object properties: locationId: type: number description: Location ID (required) ruleType: type: string enum: - email_exact - email_wildcard - user_id description: Type of rule (required) ruleValue: type: string description: Rule value - email, pattern (*@company.com), or user ID (required) maxCreditLimit: type: number description: Maximum credit limit for auto-invoicing autoApprove: type: boolean description: Auto-approve invoices matching this rule required: - locationId - ruleType - ruleValue required: true parameters: - schema: type: string format: uuid in: path name: recipientId required: true description: Recipient UUID responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Rule UUID recipientId: type: string format: uuid description: Recipient UUID locationId: type: number description: Location ID ruleType: type: string enum: - email_exact - email_wildcard - user_id description: "Type of rule: email_exact (exact match), email_wildcard (pattern match), user_id (user ID match)" ruleValue: type: string description: Rule value (email, pattern, or user ID) isActive: type: boolean description: Whether the rule is active maxCreditLimit: type: number nullable: true description: Maximum credit limit for auto-invoicing autoApprove: type: boolean description: Auto-approve invoices matching this rule createdAt: type: string format: date-time description: Created timestamp updatedAt: type: string format: date-time description: Updated timestamp required: - id - recipientId - locationId - ruleType - ruleValue - isActive - autoApprove - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/invoice-recipients/{recipientId}/rules/{ruleId}: delete: summary: Delete recipient rule tags: - Invoices description: |- Delete an eligibility rule. **Permissions:** 🔴 `invoices.delete` parameters: - schema: type: string format: uuid in: path name: recipientId required: true description: Recipient UUID - schema: type: string format: uuid in: path name: ruleId required: true description: Rule UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: deleted: type: boolean enum: - true required: - deleted meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/invoices: get: summary: List invoices tags: - Invoices description: |- List all invoices for a location with optional filtering and pagination. **Permissions:** 🔵 `invoices.read` parameters: - schema: type: number in: query name: locationId required: true description: Location ID (required) - schema: type: string format: uuid in: query name: recipientId required: false description: Filter by recipient - schema: type: string enum: - draft - sent - paid - overdue - cancelled - auto_draft in: query name: status required: false description: Filter by status - schema: type: string enum: - manual - auto_generated in: query name: invoiceType required: false description: Filter by invoice type - schema: type: string format: date-time in: query name: startDate required: false description: Filter by start date - schema: type: string format: date-time in: query name: endDate required: false description: Filter by end date - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: number minimum: 1 maximum: 100 default: 50 in: query name: limit required: false description: Items per page responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: items: type: array items: type: object properties: id: type: string format: uuid description: Invoice UUID locationId: type: number description: Location ID recipientId: type: string format: uuid description: Recipient UUID invoiceNumber: type: string description: Invoice number (unique per location) status: type: string enum: - draft - sent - paid - overdue - cancelled - auto_draft description: Invoice status invoiceType: type: string enum: - manual - auto_generated description: Invoice type collectionPeriodStart: type: string nullable: true format: date-time description: Collection period start (for auto-generated) collectionPeriodEnd: type: string nullable: true format: date-time description: Collection period end (for auto-generated) totalAmount: type: number description: Total invoice amount (including tax) taxAmount: type: number description: Total tax amount subtotalAmount: type: number description: Subtotal (before tax) currency: type: string description: Currency code (e.g., SEK) dueDate: type: string format: date description: Due date (YYYY-MM-DD) issuedDate: type: string nullable: true format: date description: Issue date paidDate: type: string nullable: true format: date description: Payment date paymentReference: type: string nullable: true description: Payment reference code notes: type: string nullable: true description: Additional notes createdBy: type: number nullable: true description: User ID who created the invoice createdAt: type: string format: date-time description: Created timestamp updatedAt: type: string format: date-time description: Updated timestamp required: - id - locationId - recipientId - invoiceNumber - status - invoiceType - totalAmount - taxAmount - subtotalAmount - currency - dueDate - createdAt - updatedAt pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages required: - items - pagination meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: summary: Create invoice tags: - Invoices description: |- Create a new invoice. Invoice number is automatically generated. **Permissions:** 🟢 `invoices.create` requestBody: content: application/json: schema: type: object properties: locationId: type: number description: Location ID (required) recipientId: type: string format: uuid description: Recipient UUID (required) dueDate: type: string format: date description: Due date YYYY-MM-DD (required) currency: type: string description: Currency code (optional - defaults to location currency) invoiceType: type: string enum: - manual - auto_generated description: "Invoice type (default: manual)" collectionPeriodStart: type: string format: date-time description: Collection period start collectionPeriodEnd: type: string format: date-time description: Collection period end totalAmount: type: number description: Total amount taxAmount: type: number description: Tax amount subtotalAmount: type: number description: Subtotal amount issuedDate: type: string format: date description: Issue date paymentReference: type: string description: Payment reference notes: type: string description: Notes purchaseIds: type: array items: type: number description: Purchase IDs to link to invoice required: - locationId - recipientId - dueDate required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Invoice UUID locationId: type: number description: Location ID recipientId: type: string format: uuid description: Recipient UUID invoiceNumber: type: string description: Invoice number (unique per location) status: type: string enum: - draft - sent - paid - overdue - cancelled - auto_draft description: Invoice status invoiceType: type: string enum: - manual - auto_generated description: Invoice type collectionPeriodStart: type: string nullable: true format: date-time description: Collection period start (for auto-generated) collectionPeriodEnd: type: string nullable: true format: date-time description: Collection period end (for auto-generated) totalAmount: type: number description: Total invoice amount (including tax) taxAmount: type: number description: Total tax amount subtotalAmount: type: number description: Subtotal (before tax) currency: type: string description: Currency code (e.g., SEK) dueDate: type: string format: date description: Due date (YYYY-MM-DD) issuedDate: type: string nullable: true format: date description: Issue date paidDate: type: string nullable: true format: date description: Payment date paymentReference: type: string nullable: true description: Payment reference code notes: type: string nullable: true description: Additional notes createdBy: type: number nullable: true description: User ID who created the invoice createdAt: type: string format: date-time description: Created timestamp updatedAt: type: string format: date-time description: Updated timestamp required: - id - locationId - recipientId - invoiceNumber - status - invoiceType - totalAmount - taxAmount - subtotalAmount - currency - dueDate - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/invoices/{invoiceId}: get: summary: Get invoice tags: - Invoices description: |- Get a single invoice by ID. **Permissions:** 🔵 `invoices.read` parameters: - schema: type: string format: uuid in: path name: invoiceId required: true description: Invoice UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Invoice UUID locationId: type: number description: Location ID recipientId: type: string format: uuid description: Recipient UUID invoiceNumber: type: string description: Invoice number (unique per location) status: type: string enum: - draft - sent - paid - overdue - cancelled - auto_draft description: Invoice status invoiceType: type: string enum: - manual - auto_generated description: Invoice type collectionPeriodStart: type: string nullable: true format: date-time description: Collection period start (for auto-generated) collectionPeriodEnd: type: string nullable: true format: date-time description: Collection period end (for auto-generated) totalAmount: type: number description: Total invoice amount (including tax) taxAmount: type: number description: Total tax amount subtotalAmount: type: number description: Subtotal (before tax) currency: type: string description: Currency code (e.g., SEK) dueDate: type: string format: date description: Due date (YYYY-MM-DD) issuedDate: type: string nullable: true format: date description: Issue date paidDate: type: string nullable: true format: date description: Payment date paymentReference: type: string nullable: true description: Payment reference code notes: type: string nullable: true description: Additional notes createdBy: type: number nullable: true description: User ID who created the invoice createdAt: type: string format: date-time description: Created timestamp updatedAt: type: string format: date-time description: Updated timestamp required: - id - locationId - recipientId - invoiceNumber - status - invoiceType - totalAmount - taxAmount - subtotalAmount - currency - dueDate - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: summary: Update invoice tags: - Invoices description: |- Update an existing invoice. All fields are optional for partial updates. **Permissions:** 🟠 `invoices.update` requestBody: content: application/json: schema: type: object properties: status: type: string enum: - draft - sent - paid - overdue - cancelled - auto_draft description: Invoice status dueDate: type: string format: date description: Due date issuedDate: type: string nullable: true format: date description: Issue date paidDate: type: string nullable: true format: date description: Payment date paymentReference: type: string nullable: true description: Payment reference notes: type: string nullable: true description: Notes totalAmount: type: number description: Total amount taxAmount: type: number description: Tax amount subtotalAmount: type: number description: Subtotal amount parameters: - schema: type: string format: uuid in: path name: invoiceId required: true description: Invoice UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Invoice UUID locationId: type: number description: Location ID recipientId: type: string format: uuid description: Recipient UUID invoiceNumber: type: string description: Invoice number (unique per location) status: type: string enum: - draft - sent - paid - overdue - cancelled - auto_draft description: Invoice status invoiceType: type: string enum: - manual - auto_generated description: Invoice type collectionPeriodStart: type: string nullable: true format: date-time description: Collection period start (for auto-generated) collectionPeriodEnd: type: string nullable: true format: date-time description: Collection period end (for auto-generated) totalAmount: type: number description: Total invoice amount (including tax) taxAmount: type: number description: Total tax amount subtotalAmount: type: number description: Subtotal (before tax) currency: type: string description: Currency code (e.g., SEK) dueDate: type: string format: date description: Due date (YYYY-MM-DD) issuedDate: type: string nullable: true format: date description: Issue date paidDate: type: string nullable: true format: date description: Payment date paymentReference: type: string nullable: true description: Payment reference code notes: type: string nullable: true description: Additional notes createdBy: type: number nullable: true description: User ID who created the invoice createdAt: type: string format: date-time description: Created timestamp updatedAt: type: string format: date-time description: Updated timestamp required: - id - locationId - recipientId - invoiceNumber - status - invoiceType - totalAmount - taxAmount - subtotalAmount - currency - dueDate - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete invoice tags: - Invoices description: >- Delete a draft invoice. Only draft or auto_draft invoices can be deleted. **Permissions:** 🔴 `invoices.delete` parameters: - schema: type: string format: uuid in: path name: invoiceId required: true description: Invoice UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: deleted: type: boolean enum: - true required: - deleted meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/invoices/{invoiceId}/cancel: post: summary: Cancel invoice tags: - Invoices description: |- Cancel an invoice. Cannot cancel paid invoices. **Permissions:** 🟠 `invoices.update` parameters: - schema: type: string format: uuid in: path name: invoiceId required: true description: Invoice UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Invoice UUID locationId: type: number description: Location ID recipientId: type: string format: uuid description: Recipient UUID invoiceNumber: type: string description: Invoice number (unique per location) status: type: string enum: - draft - sent - paid - overdue - cancelled - auto_draft description: Invoice status invoiceType: type: string enum: - manual - auto_generated description: Invoice type collectionPeriodStart: type: string nullable: true format: date-time description: Collection period start (for auto-generated) collectionPeriodEnd: type: string nullable: true format: date-time description: Collection period end (for auto-generated) totalAmount: type: number description: Total invoice amount (including tax) taxAmount: type: number description: Total tax amount subtotalAmount: type: number description: Subtotal (before tax) currency: type: string description: Currency code (e.g., SEK) dueDate: type: string format: date description: Due date (YYYY-MM-DD) issuedDate: type: string nullable: true format: date description: Issue date paidDate: type: string nullable: true format: date description: Payment date paymentReference: type: string nullable: true description: Payment reference code notes: type: string nullable: true description: Additional notes createdBy: type: number nullable: true description: User ID who created the invoice createdAt: type: string format: date-time description: Created timestamp updatedAt: type: string format: date-time description: Updated timestamp required: - id - locationId - recipientId - invoiceNumber - status - invoiceType - totalAmount - taxAmount - subtotalAmount - currency - dueDate - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/invoices/{invoiceId}/mark-paid: post: summary: Mark invoice as paid tags: - Invoices description: |- Mark an invoice as paid. Cannot mark cancelled invoices as paid. **Permissions:** 🟠 `invoices.update` requestBody: content: application/json: schema: type: object properties: paymentReference: type: string description: Payment reference (optional) parameters: - schema: type: string format: uuid in: path name: invoiceId required: true description: Invoice UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Invoice UUID locationId: type: number description: Location ID recipientId: type: string format: uuid description: Recipient UUID invoiceNumber: type: string description: Invoice number (unique per location) status: type: string enum: - draft - sent - paid - overdue - cancelled - auto_draft description: Invoice status invoiceType: type: string enum: - manual - auto_generated description: Invoice type collectionPeriodStart: type: string nullable: true format: date-time description: Collection period start (for auto-generated) collectionPeriodEnd: type: string nullable: true format: date-time description: Collection period end (for auto-generated) totalAmount: type: number description: Total invoice amount (including tax) taxAmount: type: number description: Total tax amount subtotalAmount: type: number description: Subtotal (before tax) currency: type: string description: Currency code (e.g., SEK) dueDate: type: string format: date description: Due date (YYYY-MM-DD) issuedDate: type: string nullable: true format: date description: Issue date paidDate: type: string nullable: true format: date description: Payment date paymentReference: type: string nullable: true description: Payment reference code notes: type: string nullable: true description: Additional notes createdBy: type: number nullable: true description: User ID who created the invoice createdAt: type: string format: date-time description: Created timestamp updatedAt: type: string format: date-time description: Updated timestamp required: - id - locationId - recipientId - invoiceNumber - status - invoiceType - totalAmount - taxAmount - subtotalAmount - currency - dueDate - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/invoices/{invoiceId}/pdf-data: get: summary: Get invoice PDF data tags: - Invoices description: >- Get all data needed for PDF generation (invoice, recipient, settings, location, purchases). **Permissions:** 🔵 `invoices.read` parameters: - schema: type: string format: uuid in: path name: invoiceId required: true description: Invoice UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: invoice: type: object properties: id: type: string format: uuid description: Invoice UUID locationId: type: number description: Location ID recipientId: type: string format: uuid description: Recipient UUID invoiceNumber: type: string description: Invoice number (unique per location) status: type: string enum: - draft - sent - paid - overdue - cancelled - auto_draft description: Invoice status invoiceType: type: string enum: - manual - auto_generated description: Invoice type collectionPeriodStart: type: string nullable: true format: date-time description: Collection period start (for auto-generated) collectionPeriodEnd: type: string nullable: true format: date-time description: Collection period end (for auto-generated) totalAmount: type: number description: Total invoice amount (including tax) taxAmount: type: number description: Total tax amount subtotalAmount: type: number description: Subtotal (before tax) currency: type: string description: Currency code (e.g., SEK) dueDate: type: string format: date description: Due date (YYYY-MM-DD) issuedDate: type: string nullable: true format: date description: Issue date paidDate: type: string nullable: true format: date description: Payment date paymentReference: type: string nullable: true description: Payment reference code notes: type: string nullable: true description: Additional notes createdBy: type: number nullable: true description: User ID who created the invoice createdAt: type: string format: date-time description: Created timestamp updatedAt: type: string format: date-time description: Updated timestamp required: - id - locationId - recipientId - invoiceNumber - status - invoiceType - totalAmount - taxAmount - subtotalAmount - currency - dueDate - createdAt - updatedAt recipient: type: object properties: id: type: string format: uuid description: Recipient UUID locationId: type: number description: Location ID name: type: string description: Recipient name email: type: string description: Email address organizationName: type: string nullable: true description: Organization/company name organizationNumber: type: string nullable: true description: Organization number phone: type: string nullable: true description: Phone number billingAddressLine1: type: string nullable: true description: Address line 1 billingAddressLine2: type: string nullable: true description: Address line 2 postalCode: type: string nullable: true description: Postal code city: type: string nullable: true description: City country: type: string nullable: true description: Country reference: type: string nullable: true description: Reference/PO number contactPerson: type: string nullable: true description: Contact person name vatNumber: type: string nullable: true description: VAT number totalInvoicedAmount: type: number description: Total amount invoiced to this recipient totalPaidAmount: type: number description: Total amount paid by this recipient outstandingAmount: type: number description: Outstanding amount (unpaid) invoiceCount: type: number description: Number of invoices sent to this recipient isActive: type: boolean description: Whether the recipient is active createdAt: type: string format: date-time description: Created timestamp updatedAt: type: string format: date-time description: Updated timestamp required: - id - locationId - name - email - totalInvoicedAmount - totalPaidAmount - outstandingAmount - invoiceCount - isActive - createdAt - updatedAt nullable: true settings: type: object properties: id: type: string format: uuid description: Settings UUID locationId: type: number description: Location ID defaultPaymentTermsDays: type: number description: Default payment terms in days default: 30 invoiceNumberPrefix: type: string nullable: true description: Prefix for invoice numbers (e.g., "INV") invoiceNumberCounter: type: number description: Current invoice number counter minInvoiceAmount: type: number description: Minimum amount for invoicing senderName: type: string nullable: true description: Sender/company name senderAddressLine1: type: string nullable: true description: Sender address line 1 senderAddressLine2: type: string nullable: true description: Sender address line 2 senderPostalCode: type: string nullable: true description: Sender postal code senderCity: type: string nullable: true description: Sender city senderCountry: type: string nullable: true description: Sender country senderEmail: type: string nullable: true description: Sender email address senderPhone: type: string nullable: true description: Sender phone number senderOrganizationNumber: type: string nullable: true description: Sender organization number senderVatNumber: type: string nullable: true description: Sender VAT number bankAccountNumber: type: string nullable: true description: Bank account number bankName: type: string nullable: true description: Bank name swiftBic: type: string nullable: true description: SWIFT/BIC code iban: type: string nullable: true description: IBAN paymentReferencePrefix: type: string nullable: true description: Payment reference prefix invoiceFooterText: type: string nullable: true description: Footer text for invoices invoiceTermsText: type: string nullable: true description: Terms and conditions text latePaymentFee: type: number description: Late payment fee amount latePaymentInterestRate: type: number description: Late payment interest rate (percentage) autoGenerateEnabled: type: boolean description: Enable automatic invoice generation autoSendOnGeneration: type: boolean description: Automatically send invoices when generated collectionPeriodType: type: string enum: - calendar_month - rolling_30_days - weekly description: Collection period type for auto-invoicing reminderEnabled: type: boolean description: Enable payment reminders firstReminderDaysAfterDue: type: number description: Days after due date for first reminder secondReminderDaysAfterDue: type: number description: Days after due date for second reminder thirdReminderDaysAfterDue: type: number description: Days after due date for third reminder reminderFeeAmount: type: number description: Fee amount added per reminder autoMarkOverdueDays: type: number description: Days after due date to auto-mark as overdue currency: type: string description: Currency code (e.g., SEK, EUR) createdAt: type: string format: date-time description: Created timestamp updatedAt: type: string format: date-time description: Updated timestamp required: - id - locationId - defaultPaymentTermsDays - invoiceNumberCounter - minInvoiceAmount - latePaymentFee - latePaymentInterestRate - autoGenerateEnabled - autoSendOnGeneration - collectionPeriodType - reminderEnabled - firstReminderDaysAfterDue - secondReminderDaysAfterDue - thirdReminderDaysAfterDue - reminderFeeAmount - autoMarkOverdueDays - currency - createdAt - updatedAt nullable: true location: type: object properties: id: type: number description: Location ID name: type: string nullable: true description: Location name address: type: string nullable: true description: Address postalCode: type: string nullable: true description: Postal code city: type: string nullable: true description: City country: type: string nullable: true description: Country phone: type: string nullable: true description: Phone organizationNumber: type: string nullable: true description: Organization number email: type: string nullable: true description: Email vatNumber: type: string nullable: true description: VAT number required: - id nullable: true purchaseDetails: type: array items: type: object properties: id: type: number description: Purchase ID intentId: type: string description: Intent ID purchasedAt: type: string format: date-time description: Purchase timestamp totalAmountCents: type: number description: Total amount in cents vatAmountCents: type: number description: VAT amount in cents items: type: string nullable: true description: Items description lineItems: type: array items: type: object properties: id: type: number description: Line item ID type: type: string description: Item type title: type: string description: Item title quantity: type: number description: Quantity finalAmountCents: type: number description: Final amount in cents vatRateBasisPoints: type: number nullable: true description: VAT rate in basis points vatAmountCents: type: number description: VAT amount in cents articleNo: type: string nullable: true description: Article number required: - id - type - title - quantity - finalAmountCents - vatAmountCents description: Line items required: - id - intentId - purchasedAt - totalAmountCents - vatAmountCents - lineItems required: - invoice - purchaseDetails meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/invoices/{invoiceId}/purchases: post: summary: Add purchases to invoice tags: - Invoices description: >- Add purchases to an invoice. Only draft invoices can have purchases added. **Permissions:** 🟠 `invoices.update` requestBody: content: application/json: schema: type: object properties: purchaseIds: type: array items: type: number description: Array of purchase IDs to add to the invoice required: - purchaseIds required: true parameters: - schema: type: string format: uuid in: path name: invoiceId required: true description: Invoice UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Invoice UUID locationId: type: number description: Location ID recipientId: type: string format: uuid description: Recipient UUID invoiceNumber: type: string description: Invoice number (unique per location) status: type: string enum: - draft - sent - paid - overdue - cancelled - auto_draft description: Invoice status invoiceType: type: string enum: - manual - auto_generated description: Invoice type collectionPeriodStart: type: string nullable: true format: date-time description: Collection period start (for auto-generated) collectionPeriodEnd: type: string nullable: true format: date-time description: Collection period end (for auto-generated) totalAmount: type: number description: Total invoice amount (including tax) taxAmount: type: number description: Total tax amount subtotalAmount: type: number description: Subtotal (before tax) currency: type: string description: Currency code (e.g., SEK) dueDate: type: string format: date description: Due date (YYYY-MM-DD) issuedDate: type: string nullable: true format: date description: Issue date paidDate: type: string nullable: true format: date description: Payment date paymentReference: type: string nullable: true description: Payment reference code notes: type: string nullable: true description: Additional notes createdBy: type: number nullable: true description: User ID who created the invoice createdAt: type: string format: date-time description: Created timestamp updatedAt: type: string format: date-time description: Updated timestamp required: - id - locationId - recipientId - invoiceNumber - status - invoiceType - totalAmount - taxAmount - subtotalAmount - currency - dueDate - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/invoices/{invoiceId}/purchases/{purchaseId}: delete: summary: Remove purchase from invoice tags: - Invoices description: >- Remove a purchase from an invoice. Only draft invoices can have purchases removed. **Permissions:** 🟠 `invoices.update` parameters: - schema: type: string format: uuid in: path name: invoiceId required: true description: Invoice UUID - schema: type: number in: path name: purchaseId required: true description: Purchase ID to remove responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Invoice UUID locationId: type: number description: Location ID recipientId: type: string format: uuid description: Recipient UUID invoiceNumber: type: string description: Invoice number (unique per location) status: type: string enum: - draft - sent - paid - overdue - cancelled - auto_draft description: Invoice status invoiceType: type: string enum: - manual - auto_generated description: Invoice type collectionPeriodStart: type: string nullable: true format: date-time description: Collection period start (for auto-generated) collectionPeriodEnd: type: string nullable: true format: date-time description: Collection period end (for auto-generated) totalAmount: type: number description: Total invoice amount (including tax) taxAmount: type: number description: Total tax amount subtotalAmount: type: number description: Subtotal (before tax) currency: type: string description: Currency code (e.g., SEK) dueDate: type: string format: date description: Due date (YYYY-MM-DD) issuedDate: type: string nullable: true format: date description: Issue date paidDate: type: string nullable: true format: date description: Payment date paymentReference: type: string nullable: true description: Payment reference code notes: type: string nullable: true description: Additional notes createdBy: type: number nullable: true description: User ID who created the invoice createdAt: type: string format: date-time description: Created timestamp updatedAt: type: string format: date-time description: Updated timestamp required: - id - locationId - recipientId - invoiceNumber - status - invoiceType - totalAmount - taxAmount - subtotalAmount - currency - dueDate - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/invoices/{invoiceId}/send: post: summary: Send invoice tags: - Invoices description: |- Send an invoice to the recipient. Only draft invoices can be sent. **Permissions:** 🟠 `invoices.update` parameters: - schema: type: string format: uuid in: path name: invoiceId required: true description: Invoice UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Invoice UUID locationId: type: number description: Location ID recipientId: type: string format: uuid description: Recipient UUID invoiceNumber: type: string description: Invoice number (unique per location) status: type: string enum: - draft - sent - paid - overdue - cancelled - auto_draft description: Invoice status invoiceType: type: string enum: - manual - auto_generated description: Invoice type collectionPeriodStart: type: string nullable: true format: date-time description: Collection period start (for auto-generated) collectionPeriodEnd: type: string nullable: true format: date-time description: Collection period end (for auto-generated) totalAmount: type: number description: Total invoice amount (including tax) taxAmount: type: number description: Total tax amount subtotalAmount: type: number description: Subtotal (before tax) currency: type: string description: Currency code (e.g., SEK) dueDate: type: string format: date description: Due date (YYYY-MM-DD) issuedDate: type: string nullable: true format: date description: Issue date paidDate: type: string nullable: true format: date description: Payment date paymentReference: type: string nullable: true description: Payment reference code notes: type: string nullable: true description: Additional notes createdBy: type: number nullable: true description: User ID who created the invoice createdAt: type: string format: date-time description: Created timestamp updatedAt: type: string format: date-time description: Updated timestamp required: - id - locationId - recipientId - invoiceNumber - status - invoiceType - totalAmount - taxAmount - subtotalAmount - currency - dueDate - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/invoices/{invoiceId}/send-reminder: post: summary: Send invoice reminder tags: - Invoices description: |- Send a payment reminder for an overdue invoice. **Permissions:** 🟠 `invoices.update` requestBody: content: application/json: schema: type: object properties: reminderNumber: type: number minimum: 1 maximum: 3 description: Reminder number (1, 2, or 3) required: - reminderNumber required: true parameters: - schema: type: string format: uuid in: path name: invoiceId required: true description: Invoice UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: sent: type: boolean reminderNumber: type: number required: - sent - reminderNumber meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/invoices/{invoiceId}/upload-pdf: post: summary: Upload invoice PDF tags: - Invoices description: |- Upload a generated PDF for an invoice. The PDF should be base64-encoded. **Permissions:** 🟠 `invoices.update` requestBody: content: application/json: schema: type: object properties: pdfBase64: type: string description: Base64-encoded PDF content required: - pdfBase64 required: true parameters: - schema: type: string format: uuid in: path name: invoiceId required: true description: Invoice UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: PDF storage record ID invoiceId: type: string format: uuid description: Invoice ID pdfUrl: type: string description: URL to the PDF cdnPath: type: string description: CDN path fileSize: type: number description: File size in bytes generatedAt: type: string format: date-time description: Generation timestamp required: - id - invoiceId - pdfUrl - cdnPath - fileSize - generatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/invoices/check-eligibility: get: summary: Check invoice eligibility tags: - Invoices description: |- Check if a user/email is eligible for invoice payment at a location. **Permissions:** 🔵 `invoices.read` parameters: - schema: type: number in: query name: locationId required: true description: Location ID (required) - schema: type: string in: query name: email required: true description: Email to check eligibility for (required) - schema: type: number in: query name: userId required: false description: User ID to check eligibility for (optional) responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: eligible: type: boolean description: Whether the user is eligible for invoice payment recipientId: type: string nullable: true description: Matched recipient ID creditLimit: type: number nullable: true description: Credit limit for this user outstandingAmount: type: number nullable: true description: Current outstanding amount required: - eligible meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/invoices/start-purchase: post: summary: Start invoice purchase (POS) tags: - Invoices description: >- Start an invoice-based purchase from POS. Creates a tab settlement and initiates payment via the invoice PSP. **Permissions:** 🟢 `invoices.create` requestBody: content: application/json: schema: type: object properties: tabId: type: string format: uuid description: Tab UUID to pay locationId: type: number description: Location ID recipientId: type: string format: uuid description: Invoice recipient UUID selectedKitchenDispatchItemIds: type: array items: type: string format: uuid description: "Optional: specific kitchen dispatch item IDs to pay. If omitted, pays all unpaid items." voucherCodes: type: array items: type: string description: "Optional: voucher codes to apply to this payment." required: - tabId - locationId required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: success: type: boolean purchaseIntentId: type: string format: uuid invoiceReference: type: string nullable: true required: - success - purchaseIntentId meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/invoices/unclaimed-purchases: get: summary: Get unclaimed invoice purchases tags: - Invoices description: >- Get purchases that were made with invoice payment but not yet assigned to an invoice. **Permissions:** 🔵 `invoices.read` parameters: - schema: type: number in: query name: locationId required: true description: Location ID (required) - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: number minimum: 1 maximum: 100 default: 50 in: query name: limit required: false description: Items per page responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: items: type: array items: type: object properties: id: type: number description: Purchase ID intentId: type: string description: Intent ID purchasedAt: type: string format: date-time description: Purchase timestamp payingUserId: type: number nullable: true description: Paying user ID state: type: string description: Purchase state currencyCode: type: string description: Currency code totalAmountCents: type: number description: Total amount in cents vatAmountCents: type: number description: VAT amount in cents items: type: string nullable: true description: Comma-separated list of items userEmail: type: string nullable: true description: User email userName: type: string nullable: true description: User name required: - id - intentId - purchasedAt - state - currencyCode - totalAmountCents - vatAmountCents pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages required: - items - pagination meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/location-maps: get: summary: List location maps tags: - Location Maps description: |- List location maps with optional filtering **Permissions:** 🔵 `location_maps.read` parameters: - schema: type: number in: query name: locationId required: false description: Filter by location ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: maps: type: array items: type: object properties: id: type: string format: uuid description: Unique location map ID (UUID) locationId: type: number description: Location ID context: type: object additionalProperties: true description: JSON object with map configuration and layout data createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - id - locationId - context - createdAt - updatedAt required: - maps meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: summary: Create location map tags: - Location Maps description: |- Create a new location map **Permissions:** 🟢 `location_maps.create` requestBody: content: application/json: schema: type: object properties: locationId: type: number description: Location ID context: type: object additionalProperties: true description: JSON object with map configuration required: - locationId - context required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Unique location map ID (UUID) locationId: type: number description: Location ID context: type: object additionalProperties: true description: JSON object with map configuration and layout data createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - id - locationId - context - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/location-maps/{id}: get: summary: Get location map tags: - Location Maps description: |- Get a single location map by ID **Permissions:** 🔵 `location_maps.read` parameters: - schema: type: string format: uuid in: path name: id required: true description: Location map UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Unique location map ID (UUID) locationId: type: number description: Location ID context: type: object additionalProperties: true description: JSON object with map configuration and layout data createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - id - locationId - context - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: summary: Update location map tags: - Location Maps description: |- Update an existing location map **Permissions:** 🟠 `location_maps.update` requestBody: content: application/json: schema: type: object properties: context: type: object additionalProperties: true description: Updated JSON object with map configuration required: - context required: true parameters: - schema: type: string format: uuid in: path name: id required: true description: Location map UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Unique location map ID (UUID) locationId: type: number description: Location ID context: type: object additionalProperties: true description: JSON object with map configuration and layout data createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - id - locationId - context - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete location map tags: - Location Maps description: |- Delete a location map **Permissions:** 🔴 `location_maps.delete` parameters: - schema: type: string format: uuid in: path name: id required: true description: Location map UUID responses: "200": description: Location map successfully deleted content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: deleted: type: boolean meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/locations: post: summary: Create a new location tags: - Locations description: >- Create a new location for the merchant. The location will be linked to the same company as the user's current active location. **Hierarchy Options:** - **Standalone** (default): Independent location with no parent - **Parent**: Set `isRootCompany: true` to mark as a parent/root location - **Child**: Provide `parentLocationId` to create as a child of another location **Payout Account:** A payout account will be created with the specified PSP (STRIPE or ADYEN). For Adyen, `billingEmail` is required. **Required Fields:** - `name`: Location name (1-255 characters) - `address`: Street address - `city`: City name - `country`: Country code (e.g., SE, NO) - `psp`: Payment Service Provider (STRIPE or ADYEN) **Permissions:** 🟢 `locations.create` requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 255 description: Location name (1-255 characters) address: type: string minLength: 1 description: Street address city: type: string minLength: 1 description: City name country: type: string minLength: 2 maxLength: 2 description: Country code (e.g., SE, NO, DK) psp: type: string enum: - STRIPE - ADYEN description: Payment Service Provider for payout account (STRIPE or ADYEN) parentLocationId: type: number description: Parent location ID (required for child locations) locationType: type: string enum: - company_hq - division - region - area - city - store - warehouse - kitchen - office - other description: Type of location in the organization hierarchy isRootCompany: type: boolean description: Set to true to mark this as a parent/root company location timezone: type: string description: Timezone name (e.g., Europe/Stockholm). Defaults to parent location or company default. currency: type: string description: Currency code (e.g., SEK). Defaults to parent location or company default. zip: type: string description: ZIP/postal code billingEmail: type: string format: email description: Billing email address (required if psp is ADYEN) required: - name - address - city - country - psp required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: location: type: object properties: id: type: number description: Unique location ID name: type: string description: Location name companyId: type: number description: Company ID this location belongs to address: type: string nullable: true description: Street address city: type: string nullable: true description: City name zip: type: string nullable: true description: ZIP/postal code country: type: string nullable: true description: Country code (SE, NO, etc.) timezone: type: string nullable: true description: Timezone name (e.g., Europe/Stockholm) currency: type: string nullable: true description: Currency code (e.g., SEK) parentLocationId: type: number nullable: true description: Parent location ID for hierarchy locationType: type: string enum: - company_hq - division - region - area - city - store - warehouse - kitchen - office - other description: Type of location in the hierarchy nullable: true isRootCompany: type: boolean nullable: true description: Whether this is a root company location hierarchyMetadata: type: object nullable: true description: Hierarchy metadata (level, path, etc.) createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - id - name - companyId - createdAt - updatedAt payoutAccount: type: object properties: id: type: string nullable: true description: Payout account ID psp: type: string enum: - STRIPE - ADYEN description: Payment Service Provider for payout account required: - id - psp required: - location - payoutAccount meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/locations/{locationId}: get: summary: Get a location by ID tags: - Locations description: >- Get detailed information about a specific location, including its feature toggles. **Features:** By default, the response includes all available features and their status for this location. Set `includeFeatures=false` to exclude features from the response. **Response includes:** - Location details (name, address, timezone, currency, etc.) - Feature toggles with enabled status and optional metadata - Hierarchy information if applicable **Permissions:** 🔵 `locations.read` parameters: - schema: type: boolean in: query name: includeFeatures required: false description: "Include feature toggles in response (default: true)" - schema: type: string in: path name: locationId required: true description: Location ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: location: type: object properties: id: type: number description: Unique location ID name: type: string description: Location name companyId: type: number description: Company ID this location belongs to address: type: string nullable: true description: Street address city: type: string nullable: true description: City name zip: type: string nullable: true description: ZIP/postal code country: type: string nullable: true description: Country code (SE, NO, etc.) timezone: type: string nullable: true description: Timezone name (e.g., Europe/Stockholm) currency: type: string nullable: true description: Currency code (e.g., SEK) parentLocationId: type: number nullable: true description: Parent location ID for hierarchy locationType: type: string enum: - company_hq - division - region - area - city - store - warehouse - kitchen - office - other description: Type of location in the hierarchy nullable: true isRootCompany: type: boolean nullable: true description: Whether this is a root company location hierarchyMetadata: type: object nullable: true description: Hierarchy metadata (level, path, etc.) createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp features: type: array items: type: object properties: key: type: string description: Feature key identifier category: type: string enum: - ordering - kitchen - loyalty - payments - inventory - integrations - storefront - operations description: Feature category enabled: type: boolean description: Whether the feature is enabled for this location metadata: type: object nullable: true description: Optional feature configuration metadata required: - key - category - enabled description: List of features and their status for this location required: - id - name - companyId - createdAt - updatedAt required: - location meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/locations/{locationId}/features/{featureKey}: get: summary: Check if a feature is enabled for a location tags: - Locations description: |- Quick check if a specific feature is enabled for a location. **Use cases:** - Feature gating in UI components - Conditional logic based on feature availability - Quick feature checks without fetching full location data **Permissions:** 🔵 `locations.read` parameters: - schema: type: string in: path name: locationId required: true description: Location ID - schema: type: string in: path name: featureKey required: true description: Feature key to check (e.g., loyalty, kds, pos) responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: featureKey: type: string description: Feature key that was checked enabled: type: boolean description: Whether the feature is enabled source: type: string enum: - location_override - subscription_override - plan_included - feature_default description: Where this feature setting comes from required: - featureKey - enabled meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/locations/{locationId}/hierarchy: get: summary: Get location hierarchy tree tags: - Locations description: >- Get the location hierarchy tree starting from a specific location. Returns the location and all its descendants in a tree structure. **Permissions:** 🔵 `locations.read` parameters: - schema: type: string in: path name: locationId required: true description: Root location ID to get hierarchy for responses: "200": description: Location hierarchy retrieved content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Location ID name: type: string description: Location name type: type: string nullable: true description: Location type (restaurant, kitchen, etc.) level: type: number description: Hierarchy level (0 = root) children: type: array items: type: object properties: id: type: number name: type: string type: type: string nullable: true level: type: number description: Child locations required: - id - name - level meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta example: status: success data: id: 100 name: Main Restaurant type: restaurant level: 0 children: - id: 101 name: Kitchen 1 type: kitchen level: 1 - id: 102 name: Bar type: bar level: 1 meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 15 "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/locations/{locationId}/hours: get: summary: Get location opening hours tags: - Locations description: Get opening hours for a location including weekly schedule, exceptions, and current open/closed status parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: locationId required: true description: Location ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: scheduleId: type: string nullable: true format: uuid description: ID of the underlying schedule (null if no hours defined) isOpenNow: type: boolean description: Whether the location is currently open based on these hours nextStatusChange: type: string nullable: true format: date-time description: ISO 8601 timestamp of when the open/closed status will next change weeklyHours: type: object description: Opening hours for each day of the week properties: monday: type: object properties: open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time in HH:MM format (e.g., 08:00) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time in HH:MM format (e.g., 22:00) closed: type: boolean description: Whether the location is closed on this day required: - closed tuesday: type: object properties: open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time in HH:MM format (e.g., 08:00) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time in HH:MM format (e.g., 22:00) closed: type: boolean description: Whether the location is closed on this day required: - closed wednesday: type: object properties: open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time in HH:MM format (e.g., 08:00) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time in HH:MM format (e.g., 22:00) closed: type: boolean description: Whether the location is closed on this day required: - closed thursday: type: object properties: open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time in HH:MM format (e.g., 08:00) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time in HH:MM format (e.g., 22:00) closed: type: boolean description: Whether the location is closed on this day required: - closed friday: type: object properties: open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time in HH:MM format (e.g., 08:00) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time in HH:MM format (e.g., 22:00) closed: type: boolean description: Whether the location is closed on this day required: - closed saturday: type: object properties: open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time in HH:MM format (e.g., 08:00) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time in HH:MM format (e.g., 22:00) closed: type: boolean description: Whether the location is closed on this day required: - closed sunday: type: object properties: open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time in HH:MM format (e.g., 08:00) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time in HH:MM format (e.g., 22:00) closed: type: boolean description: Whether the location is closed on this day required: - closed exceptions: type: array items: type: object description: Holiday or special hours exception properties: id: type: string format: uuid description: Unique exception ID (for existing exceptions) name: type: string description: Name of the exception (e.g., "Christmas Day") date: type: string format: date description: Single date in YYYY-MM-DD format (mutually exclusive with startDate/endDate) startDate: type: string format: date description: Start date for a date range (use with endDate) endDate: type: string format: date description: End date for a date range (use with startDate) closed: type: boolean description: Whether the location is closed during this exception open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time if not closed (HH:MM format) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time if not closed (HH:MM format) required: - name - closed description: List of exceptions (holidays, special hours) required: - scheduleId - isOpenNow - nextStatusChange - weeklyHours - exceptions meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: summary: Update location opening hours tags: - Locations description: >- Update or create opening hours for a location. This replaces the entire schedule. **Permissions:** 🟠 `schedules.update` requestBody: content: application/json: schema: type: object properties: weeklyHours: type: object description: Opening hours for each day of the week. Days not provided will be left unchanged. properties: monday: type: object properties: open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time in HH:MM format (e.g., 08:00) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time in HH:MM format (e.g., 22:00) closed: type: boolean description: Whether the location is closed on this day required: - closed tuesday: type: object properties: open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time in HH:MM format (e.g., 08:00) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time in HH:MM format (e.g., 22:00) closed: type: boolean description: Whether the location is closed on this day required: - closed wednesday: type: object properties: open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time in HH:MM format (e.g., 08:00) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time in HH:MM format (e.g., 22:00) closed: type: boolean description: Whether the location is closed on this day required: - closed thursday: type: object properties: open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time in HH:MM format (e.g., 08:00) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time in HH:MM format (e.g., 22:00) closed: type: boolean description: Whether the location is closed on this day required: - closed friday: type: object properties: open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time in HH:MM format (e.g., 08:00) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time in HH:MM format (e.g., 22:00) closed: type: boolean description: Whether the location is closed on this day required: - closed saturday: type: object properties: open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time in HH:MM format (e.g., 08:00) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time in HH:MM format (e.g., 22:00) closed: type: boolean description: Whether the location is closed on this day required: - closed sunday: type: object properties: open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time in HH:MM format (e.g., 08:00) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time in HH:MM format (e.g., 22:00) closed: type: boolean description: Whether the location is closed on this day required: - closed exceptions: type: array items: type: object description: Holiday or special hours exception properties: id: type: string format: uuid description: Unique exception ID (for existing exceptions) name: type: string description: Name of the exception (e.g., "Christmas Day") date: type: string format: date description: Single date in YYYY-MM-DD format (mutually exclusive with startDate/endDate) startDate: type: string format: date description: Start date for a date range (use with endDate) endDate: type: string format: date description: End date for a date range (use with startDate) closed: type: boolean description: Whether the location is closed during this exception open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time if not closed (HH:MM format) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time if not closed (HH:MM format) required: - name - closed description: List of exceptions to set (replaces all existing exceptions) required: - weeklyHours required: true parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: locationId required: true description: Location ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: scheduleId: type: string nullable: true format: uuid description: ID of the underlying schedule (null if no hours defined) isOpenNow: type: boolean description: Whether the location is currently open based on these hours nextStatusChange: type: string nullable: true format: date-time description: ISO 8601 timestamp of when the open/closed status will next change weeklyHours: type: object description: Opening hours for each day of the week properties: monday: type: object properties: open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time in HH:MM format (e.g., 08:00) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time in HH:MM format (e.g., 22:00) closed: type: boolean description: Whether the location is closed on this day required: - closed tuesday: type: object properties: open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time in HH:MM format (e.g., 08:00) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time in HH:MM format (e.g., 22:00) closed: type: boolean description: Whether the location is closed on this day required: - closed wednesday: type: object properties: open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time in HH:MM format (e.g., 08:00) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time in HH:MM format (e.g., 22:00) closed: type: boolean description: Whether the location is closed on this day required: - closed thursday: type: object properties: open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time in HH:MM format (e.g., 08:00) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time in HH:MM format (e.g., 22:00) closed: type: boolean description: Whether the location is closed on this day required: - closed friday: type: object properties: open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time in HH:MM format (e.g., 08:00) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time in HH:MM format (e.g., 22:00) closed: type: boolean description: Whether the location is closed on this day required: - closed saturday: type: object properties: open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time in HH:MM format (e.g., 08:00) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time in HH:MM format (e.g., 22:00) closed: type: boolean description: Whether the location is closed on this day required: - closed sunday: type: object properties: open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time in HH:MM format (e.g., 08:00) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time in HH:MM format (e.g., 22:00) closed: type: boolean description: Whether the location is closed on this day required: - closed exceptions: type: array items: type: object description: Holiday or special hours exception properties: id: type: string format: uuid description: Unique exception ID (for existing exceptions) name: type: string description: Name of the exception (e.g., "Christmas Day") date: type: string format: date description: Single date in YYYY-MM-DD format (mutually exclusive with startDate/endDate) startDate: type: string format: date description: Start date for a date range (use with endDate) endDate: type: string format: date description: End date for a date range (use with startDate) closed: type: boolean description: Whether the location is closed during this exception open: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Opening time if not closed (HH:MM format) close: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$ description: Closing time if not closed (HH:MM format) required: - name - closed description: List of exceptions (holidays, special hours) required: - scheduleId - isOpenNow - nextStatusChange - weeklyHours - exceptions meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete location opening hours tags: - Locations description: |- Remove opening hours for a location (makes it always open) **Permissions:** 🔴 `schedules.delete` parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: locationId required: true description: Location ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: deleted: type: boolean message: type: string required: - deleted - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/locations/{locationId}/pickup-settings: get: summary: Get pickup settings for a location tags: - Locations description: >- Get pickup settings and exceptional sale times for a location. **Response includes:** - `pickupSettings`: Configuration for time slot selection (enabled, days in advance) - `exceptionalSaleTimes`: Special dates with modified hours or closures (holidays, events, etc.) **Use cases:** - Displaying time slot picker in checkout flow - Determining if pickup time selection is available - Showing modified hours for upcoming dates **Permissions:** 🔵 `locations.read` parameters: - schema: type: string in: path name: locationId required: true description: Location ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: exceptionalSaleTimes: type: array nullable: true items: type: object properties: id: type: number description: Unique identifier for the exceptional sale time name: type: string nullable: true description: Name/description of the exceptional period startDate: type: string format: date description: Start date (YYYY-MM-DD) endDate: type: string format: date description: End date (YYYY-MM-DD) closed: type: boolean description: Whether the location is closed during this period saleStartLocal: type: string description: Sale start time in local timezone (HH:MM:SS) saleEndLocal: type: string description: Sale end time in local timezone (HH:MM:SS) pickupStartLocal: type: string description: Pickup start time in local timezone (HH:MM:SS) pickupEndLocal: type: string description: Pickup end time in local timezone (HH:MM:SS) required: - id - startDate - endDate - closed - saleStartLocal - saleEndLocal - pickupStartLocal - pickupEndLocal description: List of exceptional sale times (holidays, special hours, closures) pickupSettings: type: object properties: pickupTimeEnabled: type: boolean description: Whether time slot selection is enabled pickupDaysInAdvanceAllowed: type: number description: Number of days in advance customers can select pickup time takeawayEnabled: type: boolean description: Whether takeaway is enabled defaultPreparationTimeSeconds: type: number description: Default preparation time in seconds autoacceptMinutesBeforePickup: type: number description: Minutes before pickup when orders are automatically accepted pickupInformation: type: string nullable: true description: Pickup information text defaultTakeawayVatId: type: number nullable: true description: Default VAT rate ID for takeaway orders required: - pickupTimeEnabled - pickupDaysInAdvanceAllowed - takeawayEnabled - defaultPreparationTimeSeconds - autoacceptMinutesBeforePickup - pickupInformation - defaultTakeawayVatId nullable: true description: Pickup time slot configuration required: - exceptionalSaleTimes - pickupSettings meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/locations/{locationId}/qr-codes: get: summary: Get QR codes for a location tags: - Locations description: |- Get all active QR codes (tables) for a location. **Response includes:** - Array of QR codes with uuid and name - Only active QR codes are returned - Sorted alphabetically by name **Use cases:** - Displaying table selection in storefront - Managing table orders - QR code scanning for dine-in orders **Permissions:** 🔵 `locations.read` parameters: - schema: type: string in: path name: locationId required: true description: Location ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: array items: type: object properties: uuid: type: string format: uuid description: Unique identifier for the QR code name: type: string description: Name/label for the QR code (e.g., table number) groupId: type: - "null" - integer description: Group/section id (e.g. "Fönsterbord") groupName: type: - "null" - string description: Group/section display name payment_flow: type: - "null" - string enum: - pay_upfront - open_tab - null description: Forced payment flow for this QR kiosk: type: - "null" - boolean description: Kiosk-mode QR (shared terminal) limitation: type: - "null" - string enum: - view - order - null description: Viewing-only vs. ordering QR joinTabLimitations: type: - "null" - string enum: - join_order_and_pay - join_pay_only - join_disabled - null menuLayoutId: type: - "null" - string description: Pin this QR to a specific menu layout (UUID) room: type: - "null" - string description: Room identifier (hotel room service) newTabPerGuest: type: - "null" - boolean description: Force a new tab per scan (shared QRs) terminal: type: - "null" - string description: Attached Adyen card reader UUID (kiosk only) printer: type: - "null" - string description: Attached receipt printer UUID (kiosk only) required: - uuid - name description: List of QR codes for the location meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/locations/{locationId}/set-parent: post: summary: Set parent location tags: - Locations description: >- Set or change the parent location for a location. This updates the location hierarchy and refreshes the materialized access view. **Permissions:** 🟠 `locations.update` requestBody: content: application/json: schema: type: object properties: parentLocationId: type: number nullable: true description: Parent location ID (null to make root location) required: - parentLocationId required: true parameters: - schema: type: string in: path name: locationId required: true description: Location ID to update responses: "200": description: Location parent updated successfully content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Location ID name: type: string description: Location name parentLocationId: type: number nullable: true description: New parent location ID hierarchyMetadata: type: object properties: level: type: number description: Hierarchy level path: type: array items: type: number description: Array of location IDs from root to this location is_root: type: boolean description: Whether this is a root location description: Updated hierarchy metadata required: - id - name meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta example: status: success data: id: 101 name: Kitchen 1 parentLocationId: 100 hierarchyMetadata: level: 1 path: - 100 - 101 is_root: false meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 25 "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/locations/{locationId}/settings: patch: summary: Update location settings tags: - Locations description: >- Update settings for a specific location. Supports partial updates - only provided fields will be updated. **Supported fields:** - `phone`: Phone number (set to null to clear) - `website`: Website URL (set to null to clear, max 248 chars) - `description`: Location description (set to null to clear, max 1000 chars) - `pickupInformation`: Pickup information text - `context`: Location context JSON (features, configuration, etc.) - `isItemCommentAllowed`: Whether item comments are allowed - `orderPlacements`: Order placement configuration per channel - `paymentFlow`: Default payment flow (`open_tab` or `pay_upfront`, set to null to clear) - `defaultPreparationTimeSeconds`: Default preparation time - `takeawayEnabled`: Whether takeaway is enabled - `autoacceptMinutesBeforePickup`: Minutes before pickup for auto-accept - `pickupTimeEnabled`: Whether time slot selection is enabled - `pickupDaysInAdvanceAllowed`: Days in advance for pickup time selection **Permissions:** 🟠 `locations.update` requestBody: content: application/json: schema: type: object properties: phone: type: string nullable: true description: Phone number website: type: string nullable: true maxLength: 248 description: Website URL description: type: string nullable: true maxLength: 1000 description: Location description pickupInformation: type: string nullable: true description: Pickup information text context: oneOf: - type: object description: Context JSON object - type: string description: Context as JSON string - type: "null" description: Location context (JSON) isItemCommentAllowed: type: boolean description: Whether item comments are allowed orderPlacements: type: object description: Order placement configuration per channel paymentFlow: oneOf: - type: string enum: - open_tab - pay_upfront - type: "null" description: Default payment flow for this location defaultPreparationTimeSeconds: type: number description: Default preparation time in seconds takeawayEnabled: type: boolean description: Whether takeaway is enabled autoacceptMinutesBeforePickup: type: number description: Minutes before pickup when orders are automatically accepted pickupTimeEnabled: type: boolean description: Whether time slot selection is enabled pickupDaysInAdvanceAllowed: type: number description: Number of days in advance customers can select pickup time defaultTakeawayVatId: oneOf: - type: number - type: "null" description: Default VAT rate ID for takeaway orders logoImageUrl: type: string nullable: true description: URL of the location logo image (empty string or null to clear) featureImageUrl: type: string nullable: true description: URL of the location feature/background image (empty string or null to clear) businessDayStartMinutes: oneOf: - type: integer minimum: 0 maximum: 1439 - type: "null" description: Analytics business-day rollover, in minutes from local-time midnight (Europe/Stockholm), 0-1439. null = midnight rollover. Affects /analytics display only — SIE, payouts, receipts use the legal calendar day. additionalProperties: false parameters: - schema: type: string in: path name: locationId required: true description: Location ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: success: type: boolean required: - success meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/locations/{locationId}/storefront: get: summary: Get location storefront data tags: - Locations description: >- Get comprehensive storefront data for a location by its ID. **Response includes:** - Location details (name, address, coordinates, contact info) - Current sale status and times - Opening hours (weekly hours, exceptions, schedule ID) - Theme and branding configuration - Feature flags and settings - Loyalty program information - Extended waiting time (if set) This returns the same enriched data as the slug-based endpoint, but uses the numeric location ID. **Permissions:** 🔵 `locations.read` parameters: - schema: type: string in: path name: locationId required: true description: Location ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: location: type: object properties: locationId: type: number description: Unique location identifier name: type: string description: Store name description: type: string nullable: true description: Store description latitude: type: number description: Latitude coordinate longitude: type: number description: Longitude coordinate streetAdress: type: string nullable: true description: Street address zip: type: string nullable: true description: ZIP/postal code city: type: string nullable: true description: City website: type: string nullable: true description: Website URL phone: type: string nullable: true description: Phone number currencyCode: type: string enum: - SEK - GBP - EUR - DKK - NOK - ISK - JPY description: Currency code logoImageUrl: type: string nullable: true description: Logo image URL featureImageUrl: type: string nullable: true description: Feature image URL pickupInformation: type: string nullable: true description: Pickup instructions averageRating: type: number nullable: true description: Average customer rating saleStatus: type: string enum: - open - closed - delivering - paused - undecided - waiting description: Current sale status saleStart: type: string nullable: true format: date-time description: Sale start time saleEnd: type: string nullable: true format: date-time description: Sale end time salePickupStart: type: string nullable: true format: date-time description: Pickup window start salePickupEnd: type: string nullable: true format: date-time description: Pickup window end defaultPreparationTimeSeconds: type: number description: Default order prep time in seconds timeSlotDurationInMinutes: type: number nullable: true description: Time slot duration psp: type: string enum: - adyen description: Payment service provider extendedWaitingTime: type: object nullable: true properties: id: type: number locationId: type: number endsAt: type: string format: date-time delayInMinutes: type: number nullable: true required: - id - locationId - endsAt isItemCommentAllowed: type: boolean description: Whether item comments are allowed takeawayEnabled: type: boolean description: Whether takeaway is enabled isMigratedToPurchase: type: boolean description: Whether migrated to purchase payments isDiscountsEnabled: type: boolean description: Whether discounts are enabled isScanToTabEnabled: type: boolean description: Whether scan-to-tab is enabled isSplitItemEnabled: type: boolean description: Whether split item is enabled isUserSessionsEnabled: type: boolean description: Whether user sessions are enabled defaultTakeawayVatValue: type: number nullable: true description: Default takeaway VAT rate for this location (basis points). When set and no item-specific takeaway VAT is defined, this rate applies to takeaway orders. orderPlacements: type: object additionalProperties: type: string description: Order placement configuration timezone: type: string description: Timezone (e.g., Europe/Stockholm) context: type: string nullable: true description: Location context JSON string smsNotifications: type: boolean description: Whether SMS notifications are enabled swishConfig: type: object nullable: true properties: number: type: number description: Swish number themes: type: array nullable: true items: type: object properties: id: type: number name: type: string nullable: true logo: type: string nullable: true brandPrimaryColor: type: string nullable: true brandColorTextOnPrimary: type: string nullable: true brandFontPath: type: string nullable: true brandFontFamily: type: string nullable: true required: - id description: Location themes locationCenters: type: array nullable: true items: type: object properties: id: type: number name: type: string logo: type: string nullable: true visibleMenuGroups: type: array items: type: number themeId: type: number nullable: true required: - id - name - visibleMenuGroups description: Location centers tip: type: boolean description: Whether tipping is enabled externalName: type: string nullable: true description: External display name externalTos: type: array nullable: true items: type: object properties: name: type: string link: type: string required: - name - link description: External terms of service links loyaltyProgram: type: object properties: programId: type: number name: type: string slug: type: string baseColor: type: string pointConversion: type: object nullable: true properties: everyXCents: type: number earnYPoints: type: number required: - programId - name - slug - baseColor description: Loyalty program information isOpenNow: type: boolean description: Whether the location is currently open based on opening hours schedule nextStatusChange: type: string nullable: true format: date-time description: ISO 8601 timestamp of when the open/closed status will next change scheduleId: type: string nullable: true description: Schedule ID for the location hours weeklyHours: type: object properties: monday: type: object properties: open: type: string description: Opening time (HH:MM) close: type: string description: Closing time (HH:MM) closed: type: boolean description: Whether closed on this day required: - closed tuesday: type: object properties: open: type: string description: Opening time (HH:MM) close: type: string description: Closing time (HH:MM) closed: type: boolean description: Whether closed on this day required: - closed wednesday: type: object properties: open: type: string description: Opening time (HH:MM) close: type: string description: Closing time (HH:MM) closed: type: boolean description: Whether closed on this day required: - closed thursday: type: object properties: open: type: string description: Opening time (HH:MM) close: type: string description: Closing time (HH:MM) closed: type: boolean description: Whether closed on this day required: - closed friday: type: object properties: open: type: string description: Opening time (HH:MM) close: type: string description: Closing time (HH:MM) closed: type: boolean description: Whether closed on this day required: - closed saturday: type: object properties: open: type: string description: Opening time (HH:MM) close: type: string description: Closing time (HH:MM) closed: type: boolean description: Whether closed on this day required: - closed sunday: type: object properties: open: type: string description: Opening time (HH:MM) close: type: string description: Closing time (HH:MM) closed: type: boolean description: Whether closed on this day required: - closed description: Weekly opening hours from the schedules system exceptions: type: array items: type: object properties: id: type: string name: type: string closed: type: boolean date: type: string description: YYYY-MM-DD for single date startDate: type: string description: YYYY-MM-DD for date range start endDate: type: string description: YYYY-MM-DD for date range end open: type: string description: HH:MM if not closed close: type: string description: HH:MM if not closed required: - name - closed description: Exceptions to regular hours (holidays, special hours) features: type: array items: type: string description: Enabled feature keys for this location (e.g. ["reservations", "pos"]). Storefronts gate optional UI on these — e.g. the booking page requires "reservations". pickupDaysInAdvanceAllowed: type: number description: Number of days in advance customers can select a pickup time slot for takeaway orders required: - locationId - name - latitude - longitude - currencyCode - averageRating - saleStatus - defaultPreparationTimeSeconds - psp - isItemCommentAllowed - takeawayEnabled - isMigratedToPurchase - isDiscountsEnabled - isScanToTabEnabled - isSplitItemEnabled - orderPlacements - timezone required: - location meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/locations/{locationId}/voucher-provider: get: summary: Get a location's voucher provider and display name tags: - Locations description: >- Returns the location's voucher provider type and a ready-to-render display name. **Behavior:** - `voucher_provider='trivec'` → `providerDisplayName: 'Trivec'` (hardcoded, never leaks voucherService) - `voucher_provider='custom'` with valid displayName → `providerDisplayName: ` - `voucher_provider='custom'` with displayName containing the forbidden third-party vendor substring (case-insensitive) → `providerDisplayName: null` - No integration_configs row OR `voucher_provider IS NULL` → `{ voucherProvider: 'karma', providerDisplayName: null }` **Permissions:** 🔵 `locations.read` parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: locationId required: true description: Location ID responses: "200": description: Default Response content: application/json: schema: type: object required: - status - data - meta properties: status: type: string enum: - success data: type: object required: - voucherProvider - providerDisplayName properties: voucherProvider: type: string enum: - karma - trivec - custom description: The location's voucher provider type providerDisplayName: type: - "null" - string description: Ready-to-render display name (null when unknown or filtered) meta: type: object put: summary: Update voucher provider configuration for a location tags: - Locations description: >- Upserts integration_configs.voucher_provider and settings in a single transaction. **Body is a tagged union by provider:** - `{ provider: 'karma' }` — switch back to native Karma vouchers (no settings) - `{ provider: 'trivec' }` — enable Trivec; credentials are provisioned out-of-band, never via merchant PUT (CRED-02) - `{ provider: 'custom', settings: {...} }` — configure a custom HTTP voucher provider **Server-side behaviour:** - Custom provider secrets are AES-256-CBC encrypted server-side; plaintext is expected in the request body over HTTPS. - Requests containing the forbidden third-party vendor substring (case-insensitive) in any string value are rejected with 400 before reaching the DB. - In-flight voucher reservations or a non-empty DLQ block provider switches with 409 to prevent double-spend. **Permissions:** 🟠 `locations.update` requestBody: content: application/json: schema: oneOf: - type: object properties: provider: type: string enum: - karma required: - provider additionalProperties: false - type: object properties: provider: type: string enum: - trivec required: - provider additionalProperties: false - type: object properties: provider: type: string enum: - custom settings: type: object properties: displayName: type: string checkUrl: type: string format: uri commitUrl: type: string format: uri reactivateUrl: type: string format: uri auth: oneOf: - type: object properties: type: type: string enum: - none required: - type additionalProperties: false - type: object properties: type: type: string enum: - basic username: type: string password: type: string description: Plaintext; server-side AES-256-CBC encrypts before storage. Omit to preserve stored ciphertext (D-03). required: - type - username additionalProperties: false - type: object properties: type: type: string enum: - headers headers: type: object additionalProperties: type: string description: Plaintext header map; each value encrypted server-side. Omit to preserve stored ciphertext (D-03). required: - type additionalProperties: false required: - displayName - checkUrl - commitUrl - reactivateUrl - auth additionalProperties: false required: - provider - settings additionalProperties: false description: Voucher provider write body — tagged union by provider. Karma and Trivec variants accept only { provider }; any settings field is rejected (CRED-02). Custom variant requires a settings object. description: Voucher provider write body — tagged union by provider. Karma and Trivec variants accept only { provider }; any settings field is rejected (CRED-02). Custom variant requires a settings object. parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: locationId required: true description: Location ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: provider: type: string enum: - karma - trivec - custom description: Voucher provider type displayName: type: - "null" - string description: Ready-to-render display name (null when unknown or filtered) checkUrl: type: string description: Custom provider check URL (custom only) commitUrl: type: string description: Custom provider commit URL (custom only) reactivateUrl: type: string description: Custom provider reactivate URL (custom only) auth: oneOf: - type: object properties: type: type: string enum: - none required: - type additionalProperties: false - type: object properties: type: type: string enum: - basic username: type: string passwordSet: type: boolean enum: - true required: - type - username - passwordSet additionalProperties: false - type: object properties: type: type: string enum: - headers passwordSet: type: boolean enum: - true required: - type - passwordSet additionalProperties: false lastTestedAt: type: - "null" - string format: date-time description: Timestamp of the most recent /test invocation (D-14). Null when never tested. lastTestReachable: type: - "null" - boolean description: Outcome of the most recent /test invocation (D-14). Null when never tested. required: - provider meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta "403": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta "409": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta "500": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta /api/v1/locations/{locationId}/voucher-provider/test: post: summary: Test connectivity to the configured Trivec voucher provider tags: - Locations description: >- Calls Trivec /voucher/services via integrations-service using the currently-saved config. **Behaviour:** - Persists `last_tested_at` and `last_test_reachable` on integration_configs. - Non-Trivec providers return 400 INVALID_PROVIDER_FOR_TEST. - Does not emit platform_events (D-08). **Permissions:** 🟠 `locations.update` parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: locationId required: true description: Location ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: reachable: type: boolean description: True if the provider responded successfully latencyMs: type: number description: Round-trip latency in milliseconds error: type: string description: Error message when reachable=false required: - reachable - latencyMs additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta "403": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta "500": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta /api/v1/locations/slug/{slug}: get: summary: Get location by slug tags: - Locations description: >- Get comprehensive location information by its URL slug. **Response includes:** - Location details (name, address, coordinates, contact info) - Current sale status and times - Opening hours (weekly hours, exceptions, schedule ID) - Theme and branding configuration - Feature flags and settings (discounts, scan-to-tab, split items, etc.) - Loyalty program information - Extended waiting time (if set) This is the primary endpoint for storefront applications to fetch location data. The slug is the URL-friendly identifier for the location (e.g., "joes-pizza"). **Permissions:** 🔵 `locations.read` parameters: - schema: type: string in: path name: slug required: true description: Location URL slug (e.g., "joes-pizza") responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: location: type: object properties: locationId: type: number description: Unique location identifier name: type: string description: Store name description: type: string nullable: true description: Store description latitude: type: number description: Latitude coordinate longitude: type: number description: Longitude coordinate streetAdress: type: string nullable: true description: Street address zip: type: string nullable: true description: ZIP/postal code city: type: string nullable: true description: City website: type: string nullable: true description: Website URL phone: type: string nullable: true description: Phone number currencyCode: type: string enum: - SEK - GBP - EUR - DKK - NOK - ISK - JPY description: Currency code logoImageUrl: type: string nullable: true description: Logo image URL featureImageUrl: type: string nullable: true description: Feature image URL pickupInformation: type: string nullable: true description: Pickup instructions averageRating: type: number nullable: true description: Average customer rating saleStatus: type: string enum: - open - closed - delivering - paused - undecided - waiting description: Current sale status saleStart: type: string nullable: true format: date-time description: Sale start time saleEnd: type: string nullable: true format: date-time description: Sale end time salePickupStart: type: string nullable: true format: date-time description: Pickup window start salePickupEnd: type: string nullable: true format: date-time description: Pickup window end defaultPreparationTimeSeconds: type: number description: Default order prep time in seconds timeSlotDurationInMinutes: type: number nullable: true description: Time slot duration psp: type: string enum: - adyen description: Payment service provider extendedWaitingTime: type: object nullable: true properties: id: type: number locationId: type: number endsAt: type: string format: date-time delayInMinutes: type: number nullable: true required: - id - locationId - endsAt isItemCommentAllowed: type: boolean description: Whether item comments are allowed takeawayEnabled: type: boolean description: Whether takeaway is enabled isMigratedToPurchase: type: boolean description: Whether migrated to purchase payments isDiscountsEnabled: type: boolean description: Whether discounts are enabled isScanToTabEnabled: type: boolean description: Whether scan-to-tab is enabled isSplitItemEnabled: type: boolean description: Whether split item is enabled isUserSessionsEnabled: type: boolean description: Whether user sessions are enabled defaultTakeawayVatValue: type: number nullable: true description: Default takeaway VAT rate for this location (basis points). When set and no item-specific takeaway VAT is defined, this rate applies to takeaway orders. orderPlacements: type: object additionalProperties: type: string description: Order placement configuration timezone: type: string description: Timezone (e.g., Europe/Stockholm) context: type: string nullable: true description: Location context JSON string smsNotifications: type: boolean description: Whether SMS notifications are enabled swishConfig: type: object nullable: true properties: number: type: number description: Swish number themes: type: array nullable: true items: type: object properties: id: type: number name: type: string nullable: true logo: type: string nullable: true brandPrimaryColor: type: string nullable: true brandColorTextOnPrimary: type: string nullable: true brandFontPath: type: string nullable: true brandFontFamily: type: string nullable: true required: - id description: Location themes locationCenters: type: array nullable: true items: type: object properties: id: type: number name: type: string logo: type: string nullable: true visibleMenuGroups: type: array items: type: number themeId: type: number nullable: true required: - id - name - visibleMenuGroups description: Location centers tip: type: boolean description: Whether tipping is enabled externalName: type: string nullable: true description: External display name externalTos: type: array nullable: true items: type: object properties: name: type: string link: type: string required: - name - link description: External terms of service links loyaltyProgram: type: object properties: programId: type: number name: type: string slug: type: string baseColor: type: string pointConversion: type: object nullable: true properties: everyXCents: type: number earnYPoints: type: number required: - programId - name - slug - baseColor description: Loyalty program information isOpenNow: type: boolean description: Whether the location is currently open based on opening hours schedule nextStatusChange: type: string nullable: true format: date-time description: ISO 8601 timestamp of when the open/closed status will next change scheduleId: type: string nullable: true description: Schedule ID for the location hours weeklyHours: type: object properties: monday: type: object properties: open: type: string description: Opening time (HH:MM) close: type: string description: Closing time (HH:MM) closed: type: boolean description: Whether closed on this day required: - closed tuesday: type: object properties: open: type: string description: Opening time (HH:MM) close: type: string description: Closing time (HH:MM) closed: type: boolean description: Whether closed on this day required: - closed wednesday: type: object properties: open: type: string description: Opening time (HH:MM) close: type: string description: Closing time (HH:MM) closed: type: boolean description: Whether closed on this day required: - closed thursday: type: object properties: open: type: string description: Opening time (HH:MM) close: type: string description: Closing time (HH:MM) closed: type: boolean description: Whether closed on this day required: - closed friday: type: object properties: open: type: string description: Opening time (HH:MM) close: type: string description: Closing time (HH:MM) closed: type: boolean description: Whether closed on this day required: - closed saturday: type: object properties: open: type: string description: Opening time (HH:MM) close: type: string description: Closing time (HH:MM) closed: type: boolean description: Whether closed on this day required: - closed sunday: type: object properties: open: type: string description: Opening time (HH:MM) close: type: string description: Closing time (HH:MM) closed: type: boolean description: Whether closed on this day required: - closed description: Weekly opening hours from the schedules system exceptions: type: array items: type: object properties: id: type: string name: type: string closed: type: boolean date: type: string description: YYYY-MM-DD for single date startDate: type: string description: YYYY-MM-DD for date range start endDate: type: string description: YYYY-MM-DD for date range end open: type: string description: HH:MM if not closed close: type: string description: HH:MM if not closed required: - name - closed description: Exceptions to regular hours (holidays, special hours) features: type: array items: type: string description: Enabled feature keys for this location (e.g. ["reservations", "pos"]). Storefronts gate optional UI on these — e.g. the booking page requires "reservations". pickupDaysInAdvanceAllowed: type: number description: Number of days in advance customers can select a pickup time slot for takeaway orders required: - locationId - name - latitude - longitude - currencyCode - averageRating - saleStatus - defaultPreparationTimeSeconds - psp - isItemCommentAllowed - takeawayEnabled - isMigratedToPurchase - isDiscountsEnabled - isScanToTabEnabled - isSplitItemEnabled - orderPlacements - timezone required: - location meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/{programId}/import: post: summary: Import members from CSV data tags: - Loyalty Programs description: >- Import multiple members into a loyalty program from parsed CSV data. Supports name, email, phone, initial points, and enrolled date. Creates users if they do not exist. **Permissions:** 🟢 `loyalty.create` requestBody: content: application/json: schema: type: object required: - members properties: members: type: array minItems: 1 maxItems: 5000 items: type: object properties: name: type: string description: Member name email: type: string description: Email address phone: type: string description: Phone number points: type: number minimum: 0 description: Initial points balance enrolledAt: type: string description: Enrollment date (ISO 8601 or date string) tier: type: string description: Tier name to assign (case-insensitive, must match a program tier) description: Array of member objects to import required: true parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: programId required: true description: Loyalty program ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: totalProcessed: type: number description: Total rows processed enrolled: type: number description: Number of new members enrolled alreadyEnrolled: type: number description: Number already enrolled (points still adjusted if provided) failed: type: number description: Number of failed imports results: type: array items: type: object properties: row: type: number description: Row number (1-based) success: type: boolean email: type: string nullable: true phone: type: string nullable: true error: type: string nullable: true userId: type: number nullable: true pointsSet: type: number nullable: true isNew: type: boolean description: Whether this was a newly created enrollment meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/{programId}/members: get: summary: List loyalty members tags: - Loyalty Programs description: |- Get all members of a loyalty program with pagination and search **Permissions:** 🔵 `loyalty.read` parameters: - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: number minimum: 1 maximum: 1000 default: 50 in: query name: limit required: false description: Items per page - schema: type: string in: query name: sort required: false description: Sort field (created_at, current_balance, lifetime_earned, lifetime_redeemed, user_name, user_email, tier_name) - schema: type: string enum: - asc - desc default: asc in: query name: order required: false description: Sort order - schema: type: string in: query name: search required: false description: Search by name, email, or phone - schema: type: string in: query name: tierId required: false description: Filter by tier ID, or "none" for members without a tier - schema: type: string format: date-time in: query name: startDate required: false description: Filter members enrolled on or after this date (ISO 8601) - schema: type: string format: date-time in: query name: endDate required: false description: Filter members enrolled on or before this date (ISO 8601) - schema: type: number in: query name: minBalance required: false description: Minimum current balance - schema: type: number in: query name: maxBalance required: false description: Maximum current balance - schema: type: number in: query name: minLifetimeEarned required: false description: Minimum lifetime earned points - schema: type: number in: query name: maxLifetimeEarned required: false description: Maximum lifetime earned points - schema: type: number in: query name: minLifetimeRedeemed required: false description: Minimum lifetime redeemed points - schema: type: number in: query name: maxLifetimeRedeemed required: false description: Maximum lifetime redeemed points - schema: type: string pattern: ^[0-9]+$ in: path name: programId required: true description: Loyalty program ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: members: type: array items: type: object additionalProperties: true pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/{programId}/members/{userId}: get: summary: Get member details tags: - Loyalty Programs description: >- Get detailed member information including account, user info, tier, and program details **Permissions:** 🔵 `loyalty.read` parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: programId required: true description: Loyalty program ID - schema: type: string pattern: ^[0-9]+$ in: path name: userId required: true description: User ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object additionalProperties: true meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/{programId}/members/{userId}/adjust-points: post: summary: Adjust member points tags: - Loyalty Programs description: |- Manually adjust a member's points balance (add or remove points) **Permissions:** 🟠 `loyalty.update` requestBody: content: application/json: schema: type: object required: - points - reason properties: points: type: number description: Points to add (positive) or remove (negative) reason: type: string description: Human-readable reason for the adjustment required: true parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: programId required: true description: Loyalty program ID - schema: type: string pattern: ^[0-9]+$ in: path name: userId required: true description: User ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Transaction UUID pointsAccountId: type: number description: Points account ID transactionType: type: string enum: - EARNED_PURCHASE - EARNED_ITEM - EARNED_VISIT - EARNED_ACTION - REDEEMED - EXPIRED - ADJUSTED - REVOKED description: Transaction type points: type: number description: Points amount (positive for earned, negative for redeemed/expired) balanceAfter: type: number description: Balance after this transaction purchaseId: type: number nullable: true description: Related purchase ID earningRuleId: type: number nullable: true description: Earning rule that triggered this transaction rewardRedemptionId: type: number nullable: true description: Reward redemption that caused this transaction description: type: string nullable: true description: Human-readable description metadata: type: object nullable: true additionalProperties: true description: Additional context expiresAt: type: string format: date nullable: true description: When these points expire createdAt: type: string format: date-time updatedAt: type: string format: date-time user: type: object nullable: true properties: email: type: string nullable: true name: type: string nullable: true phone: type: string nullable: true description: Member who made this transaction additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/{programId}/members/{userId}/redemptions: get: summary: Get member redemptions tags: - Loyalty Programs description: |- Get a member's reward redemption history **Permissions:** 🔵 `loyalty.read` parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: programId required: true description: Loyalty program ID - schema: type: string pattern: ^[0-9]+$ in: path name: userId required: true description: User ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: redemptions: type: array items: type: object properties: id: type: number pointsAccountId: type: number rewardId: type: number pointsSpent: type: number generatedDiscountId: type: number nullable: true description: Cloned discount with unique code generatedCode: type: string nullable: true description: Generated voucher code status: type: string enum: - active - used - expired - revoked usedAt: type: string format: date-time nullable: true usedInPurchaseId: type: number nullable: true expiresAt: type: string format: date-time nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/{programId}/members/{userId}/tier: put: summary: Assign tier to member tags: - Loyalty Programs description: >- Manually assign a tier override to a loyalty program member. Assignment type is inferred from auth context (manual for staff JWT, campaign for API key). Optional expiration date. **Permissions:** ⚪ `loyalty.tier.assign` requestBody: content: application/json: schema: type: object required: - tierId properties: tierId: type: number description: Tier ID to assign expiresAt: type: string format: date-time nullable: true description: Optional expiration date (ISO 8601) required: true parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: programId required: true description: Loyalty program ID - schema: type: string pattern: ^[0-9]+$ in: path name: userId required: true description: User ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Account ID loyaltyProgramId: type: number description: Loyalty program ID userId: type: number description: User ID currentBalance: type: number description: Current available points lifetimeEarned: type: number description: Total points earned (never decreases) lifetimeRedeemed: type: number description: Total points redeemed lifetimeExpired: type: number description: Total points expired currentTierId: type: number nullable: true description: Current tier ID tierAchievedAt: type: string format: date-time nullable: true description: When current tier was achieved createdAt: type: string format: date-time updatedAt: type: string format: date-time additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Remove tier override from member tags: - Loyalty Programs description: >- Remove a manual/campaign tier override from a loyalty program member, reverting to automatic point-calculated tier. **Permissions:** ⚪ `loyalty.tier.assign` parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: programId required: true description: Loyalty program ID - schema: type: string pattern: ^[0-9]+$ in: path name: userId required: true description: User ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Account ID loyaltyProgramId: type: number description: Loyalty program ID userId: type: number description: User ID currentBalance: type: number description: Current available points lifetimeEarned: type: number description: Total points earned (never decreases) lifetimeRedeemed: type: number description: Total points redeemed lifetimeExpired: type: number description: Total points expired currentTierId: type: number nullable: true description: Current tier ID tierAchievedAt: type: string format: date-time nullable: true description: When current tier was achieved createdAt: type: string format: date-time updatedAt: type: string format: date-time additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/{programId}/members/{userId}/wallet-pass: get: summary: Generate wallet pass tags: - Loyalty Programs description: Generate Apple or Google Wallet pass for loyalty member parameters: - schema: type: string enum: - apple - google in: query name: platform required: false description: apple (default) returns a .pkpass binary; google returns JSON { saveUrl } - schema: type: string in: path name: programId required: true description: Loyalty program ID - schema: type: string in: path name: userId required: true description: User ID responses: "200": description: Apple Wallet Pass file (.pkpass) content: application/vnd.apple.pkpass: schema: type: string format: binary "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/{programId}/redeem/{rewardId}: post: summary: Redeem a reward tags: - Loyalty Programs description: >- Redeem a reward for a user, deducting points and generating a voucher code **Permissions:** 🟢 `loyalty.create` requestBody: content: application/json: schema: type: object required: - userId properties: userId: type: number description: User ID redeeming the reward required: true parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: programId required: true description: Loyalty program ID - schema: type: string pattern: ^[0-9]+$ in: path name: rewardId required: true description: Reward catalog item ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number pointsAccountId: type: number rewardId: type: number pointsSpent: type: number generatedDiscountId: type: number nullable: true description: Cloned discount with unique code generatedCode: type: string nullable: true description: Generated voucher code status: type: string enum: - active - used - expired - revoked usedAt: type: string format: date-time nullable: true usedInPurchaseId: type: number nullable: true expiresAt: type: string format: date-time nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/earning-rules: post: summary: Create earning rule tags: - Loyalty Programs description: |- Create a new earning rule for a loyalty program **Permissions:** 🟢 `loyalty.create` requestBody: content: application/json: schema: type: object required: - loyaltyProgramId - name - ruleType properties: loyaltyProgramId: type: number name: type: string minLength: 1 description: type: string ruleType: type: string enum: - SPEND_BASED - ITEM_BASED - VISIT_BASED - ACTION_BASED isActive: type: boolean default: true minTierId: type: number pointsPerCurrencyUnit: type: number minPurchaseAmount: type: number itemId: type: number pointsMode: type: string enum: - FIXED - MULTIPLIER pointsPerItem: type: number pointsMultiplier: type: number pointsPerVisit: type: number minPurchaseForVisit: type: number actionType: type: string pointsPerAction: type: number maxActionsPerPeriod: type: number actionPeriod: type: string validFrom: type: string nullable: true format: date validUntil: type: string nullable: true format: date priority: type: number default: 0 required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number loyaltyProgramId: type: number name: type: string description: type: string nullable: true ruleType: type: string enum: - SPEND_BASED - ITEM_BASED - VISIT_BASED - ACTION_BASED isActive: type: boolean minTierId: type: number nullable: true description: Minimum tier required to earn from this rule pointsPerCurrencyUnit: type: number nullable: true description: Points per SEK/currency unit minPurchaseAmount: type: number nullable: true description: Minimum purchase to qualify itemId: type: number nullable: true description: Specific item that earns points pointsMode: type: string enum: - FIXED - MULTIPLIER nullable: true description: FIXED or MULTIPLIER pointsPerItem: type: number nullable: true description: Fixed points per item pointsMultiplier: type: number nullable: true description: Multiplier (e.g., 2.0 = 2x base points) pointsPerVisit: type: number nullable: true description: Points per visit/check-in minPurchaseForVisit: type: number nullable: true description: Minimum purchase to qualify as visit actionType: type: string nullable: true description: signup, referral, social_share, review, etc. pointsPerAction: type: number nullable: true description: Points per action maxActionsPerPeriod: type: number nullable: true description: Max times action can earn points actionPeriod: type: string nullable: true description: daily, weekly, monthly, lifetime validFrom: type: string format: date nullable: true validUntil: type: string format: date nullable: true priority: type: number description: Rule evaluation priority (higher = evaluated first) createdAt: type: string format: date-time updatedAt: type: string format: date-time additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/earning-rules/{id}: put: summary: Update earning rule tags: - Loyalty Programs description: |- Update an existing earning rule **Permissions:** 🟠 `loyalty.update` requestBody: content: application/json: schema: type: object properties: name: type: string description: type: string ruleType: type: string enum: - SPEND_BASED - ITEM_BASED - VISIT_BASED - ACTION_BASED isActive: type: boolean minTierId: type: number pointsPerCurrencyUnit: type: number minPurchaseAmount: type: number itemId: type: number pointsMode: type: string enum: - FIXED - MULTIPLIER pointsPerItem: type: number pointsMultiplier: type: number pointsPerVisit: type: number minPurchaseForVisit: type: number actionType: type: string pointsPerAction: type: number maxActionsPerPeriod: type: number actionPeriod: type: string validFrom: type: string nullable: true format: date validUntil: type: string nullable: true format: date priority: type: number parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: id required: true description: Earning rule ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number loyaltyProgramId: type: number name: type: string description: type: string nullable: true ruleType: type: string enum: - SPEND_BASED - ITEM_BASED - VISIT_BASED - ACTION_BASED isActive: type: boolean minTierId: type: number nullable: true description: Minimum tier required to earn from this rule pointsPerCurrencyUnit: type: number nullable: true description: Points per SEK/currency unit minPurchaseAmount: type: number nullable: true description: Minimum purchase to qualify itemId: type: number nullable: true description: Specific item that earns points pointsMode: type: string enum: - FIXED - MULTIPLIER nullable: true description: FIXED or MULTIPLIER pointsPerItem: type: number nullable: true description: Fixed points per item pointsMultiplier: type: number nullable: true description: Multiplier (e.g., 2.0 = 2x base points) pointsPerVisit: type: number nullable: true description: Points per visit/check-in minPurchaseForVisit: type: number nullable: true description: Minimum purchase to qualify as visit actionType: type: string nullable: true description: signup, referral, social_share, review, etc. pointsPerAction: type: number nullable: true description: Points per action maxActionsPerPeriod: type: number nullable: true description: Max times action can earn points actionPeriod: type: string nullable: true description: daily, weekly, monthly, lifetime validFrom: type: string format: date nullable: true validUntil: type: string format: date nullable: true priority: type: number description: Rule evaluation priority (higher = evaluated first) createdAt: type: string format: date-time updatedAt: type: string format: date-time additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete earning rule tags: - Loyalty Programs description: |- Delete an earning rule **Permissions:** 🔴 `loyalty.delete` parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: id required: true description: Earning rule ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: message: type: string id: type: number meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/enroll: post: summary: Enroll user in program tags: - Loyalty Programs description: >- Enroll a single user in a loyalty program. Supports userId, email, or phone identification. **Permissions:** 🟢 `loyalty.create` requestBody: content: application/json: schema: type: object required: - programId properties: programId: type: number description: Loyalty program ID userId: type: number description: User ID (priority 1) email: type: string format: email description: Email address (priority 2) phone: type: string description: Phone number (priority 3) tierId: type: number description: Optional tier ID to assign at enrollment (requires loyalty.tier.assign permission) required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Account ID loyaltyProgramId: type: number description: Loyalty program ID userId: type: number description: User ID currentBalance: type: number description: Current available points lifetimeEarned: type: number description: Total points earned (never decreases) lifetimeRedeemed: type: number description: Total points redeemed lifetimeExpired: type: number description: Total points expired currentTierId: type: number nullable: true description: Current tier ID tierAchievedAt: type: string format: date-time nullable: true description: When current tier was achieved createdAt: type: string format: date-time updatedAt: type: string format: date-time additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/enroll/bulk: post: summary: Bulk enroll users tags: - Loyalty Programs description: >- Enroll multiple users in a loyalty program at once. When tierId is provided, the tier is applied to ALL users (new and already-enrolled). **Permissions:** 🟢 `loyalty.create` requestBody: content: application/json: schema: type: object required: - programId - userIds properties: programId: type: number description: Loyalty program ID userIds: type: array items: type: number description: Array of user IDs to enroll tierId: type: number description: Optional tier ID to assign to ALL users (requires loyalty.tier.assign permission) required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: enrolled: type: number description: Number of users enrolled alreadyEnrolled: type: number description: Number already enrolled (skipped) accounts: type: array items: type: object properties: id: type: number description: Account ID loyaltyProgramId: type: number description: Loyalty program ID userId: type: number description: User ID currentBalance: type: number description: Current available points lifetimeEarned: type: number description: Total points earned (never decreases) lifetimeRedeemed: type: number description: Total points redeemed lifetimeExpired: type: number description: Total points expired currentTierId: type: number nullable: true description: Current tier ID tierAchievedAt: type: string format: date-time nullable: true description: When current tier was achieved createdAt: type: string format: date-time updatedAt: type: string format: date-time additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/points/award: post: summary: Award points tags: - Loyalty Programs description: >- Award points to a user manually. Used for promotional points, customer service adjustments, or manual corrections. **Permissions:** 🟢 `loyalty.create` requestBody: content: application/json: schema: type: object properties: userId: type: number description: User ID to award points to loyaltyProgramId: type: number description: Loyalty program ID points: type: number minimum: 1 description: Number of points to award (must be positive) description: type: string description: Reason for awarding points metadata: type: object additionalProperties: true description: Optional metadata for tracking required: - userId - loyaltyProgramId - points - description required: true responses: "201": description: Points awarded successfully content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: transactionId: type: string description: Transaction ID (UUID) points: type: number description: Points involved in the transaction description: type: string description: Transaction description createdAt: type: string format: date-time description: Transaction creation timestamp required: - transactionId - points - description - createdAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/points/claim-purchase: post: summary: Claim loyalty points for a past purchase tags: - Loyalty Programs description: Retroactively claim loyalty points for a purchase made within the last 30 days. requestBody: content: application/json: schema: type: object properties: userId: type: number description: User ID of the loyalty program member loyaltyProgramId: type: number description: Loyalty program ID purchaseIntentId: type: string description: Purchase intent ID from the completed purchase required: - userId - loyaltyProgramId - purchaseIntentId required: true responses: "200": description: Points claimed or no points to award content: application/json: schema: type: object properties: transactionId: type: string nullable: true pointsAwarded: type: number message: type: string nullable: true createdAt: type: string nullable: true "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/points/deduct: post: summary: Deduct points tags: - Loyalty Programs description: >- Deduct points from a user. Used for manual adjustments or corrections. For redemptions, use the redemption endpoints. **Permissions:** 🟢 `loyalty.create` requestBody: content: application/json: schema: type: object properties: userId: type: number description: User ID to deduct points from loyaltyProgramId: type: number description: Loyalty program ID points: type: number minimum: 1 description: Number of points to deduct (must be positive) description: type: string description: Reason for deducting points metadata: type: object additionalProperties: true description: Optional metadata for tracking required: - userId - loyaltyProgramId - points - description required: true responses: "200": description: Points deducted successfully content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: transactionId: type: string description: Transaction ID (UUID) points: type: number description: Points involved in the transaction description: type: string description: Transaction description createdAt: type: string format: date-time description: Transaction creation timestamp required: - transactionId - points - description - createdAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/points/estimate: post: summary: Estimate points for purchase tags: - Loyalty Programs description: Estimate points that would be earned from a purchase. Used to display earning preview at checkout before the purchase is committed. No authentication required - called from storefront. requestBody: content: application/json: schema: type: object properties: loyaltyProgramId: type: number description: Loyalty program ID purchaseAmountCents: type: number minimum: 0 description: Estimated purchase amount in cents itemIds: type: array items: type: number description: Array of item IDs in the cart (for item-based earning rules) userTierId: type: number nullable: true description: User tier ID for tier-specific multipliers (optional) required: - loyaltyProgramId - purchaseAmountCents required: true responses: "200": description: Points estimate calculated content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: estimatedPoints: type: number description: Total estimated points (with multipliers) basePoints: type: number description: Base points before multipliers appliedRules: type: array items: type: object properties: id: type: number description: Rule ID name: type: string description: Rule name ruleType: type: string enum: - SPEND_BASED - ITEM_BASED description: Type of earning rule pointsAwarded: type: number description: Points from this rule description: List of earning rules applied activeMultiplier: type: number nullable: true description: Active multiplier (if any double points promotion is active) required: - estimatedPoints - basePoints - appliedRules meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/points/process-purchase: post: summary: Process purchase points tags: - Loyalty Programs description: >- Process points from a purchase. Called after a purchase is completed to calculate and award earned points based on earning rules. **Permissions:** 🟢 `loyalty.create` requestBody: content: application/json: schema: type: object properties: userId: type: number description: User ID who made the purchase loyaltyProgramId: type: number description: Loyalty program ID purchaseId: type: number description: Purchase ID to process purchaseAmountCents: type: number description: Total purchase amount in cents itemIds: type: array items: type: number description: Array of item IDs in the purchase (for item-based earning rules) required: - userId - loyaltyProgramId - purchaseId - purchaseAmountCents required: true responses: "200": description: Purchase processed (no points earned) content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: pointsAwarded: type: number description: Points awarded (0 if none earned) message: type: string description: Explanation message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "201": description: Points awarded for purchase content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: transactionId: type: string description: Transaction ID (UUID) pointsAwarded: type: number description: Points awarded createdAt: type: string format: date-time description: Transaction timestamp meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/programs: get: summary: List loyalty programs tags: - Loyalty Programs description: |- List loyalty programs with optional filtering **Permissions:** 🔵 `loyalty.read` parameters: - schema: type: number in: query name: locationId required: false description: Filter by location ID - schema: type: boolean in: query name: isActive required: false description: Filter by active status - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: number minimum: 1 maximum: 1000 default: 50 in: query name: limit required: false description: Items per page responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: programs: type: array items: type: object properties: id: type: number description: Loyalty program ID locationId: type: number description: Location ID name: type: string description: Program name description: type: string nullable: true description: Program description currency: type: string description: Currency code (e.g., SEK, USD) isActive: type: boolean description: Whether program is active startDate: type: string format: date nullable: true description: Program start date endDate: type: string format: date nullable: true description: Program end date createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp additionalProperties: false pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages required: - programs - pagination meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: summary: Create loyalty program tags: - Loyalty Programs description: |- Create a new loyalty program **Permissions:** 🟢 `loyalty.create` requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 description: Program name description: type: string nullable: true description: Program description currency: type: string default: SEK description: Currency code isActive: type: boolean default: true description: Whether program is active startDate: type: string format: date nullable: true description: Program start date endDate: type: string format: date nullable: true description: Program end date loyaltyCardImage: type: string nullable: true description: Loyalty card image URL loyaltyColor: type: string nullable: true description: Loyalty card color (hex) required: - name required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Loyalty program ID locationId: type: number description: Location ID name: type: string description: Program name description: type: string nullable: true description: Program description currency: type: string description: Currency code (e.g., SEK, USD) isActive: type: boolean description: Whether program is active startDate: type: string format: date nullable: true description: Program start date endDate: type: string format: date nullable: true description: Program end date createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/programs/{id}: get: summary: Get loyalty program tags: - Loyalty Programs description: |- Get a single loyalty program by ID **Permissions:** 🔵 `loyalty.read` parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: id required: true description: Loyalty program ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Loyalty program ID locationId: type: number description: Location ID name: type: string description: Program name description: type: string nullable: true description: Program description currency: type: string description: Currency code (e.g., SEK, USD) isActive: type: boolean description: Whether program is active startDate: type: string format: date nullable: true description: Program start date endDate: type: string format: date nullable: true description: Program end date createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: summary: Update loyalty program tags: - Loyalty Programs description: |- Update an existing loyalty program **Permissions:** 🟠 `loyalty.update` requestBody: content: application/json: schema: type: object properties: name: type: string description: Program name description: type: string nullable: true description: Program description currency: type: string description: Currency code isActive: type: boolean description: Whether program is active startDate: type: string format: date nullable: true description: Program start date endDate: type: string format: date nullable: true description: Program end date loyaltyCardImage: type: string nullable: true description: Loyalty card image URL loyaltyColor: type: string nullable: true description: Loyalty card color (hex) parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: id required: true description: Loyalty program ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Loyalty program ID locationId: type: number description: Location ID name: type: string description: Program name description: type: string nullable: true description: Program description currency: type: string description: Currency code (e.g., SEK, USD) isActive: type: boolean description: Whether program is active startDate: type: string format: date nullable: true description: Program start date endDate: type: string format: date nullable: true description: Program end date createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete loyalty program tags: - Loyalty Programs description: >- Soft-delete a loyalty program (sets deleted_at, preserves data). Requires loyalty.admin permission. **Permissions:** ⚪ `loyalty.admin` parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: id required: true description: Loyalty program ID responses: "204": description: Program soft-deleted successfully "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/programs/{programId}/accounts: get: summary: List points accounts tags: - Loyalty Programs description: |- Get all points accounts for a loyalty program with pagination **Permissions:** 🔵 `loyalty.read` parameters: - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: number minimum: 1 maximum: 1000 default: 50 in: query name: limit required: false description: Items per page - schema: type: string pattern: ^[0-9]+$ in: path name: programId required: true description: Loyalty program ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: accounts: type: array items: type: object properties: id: type: number description: Account ID loyaltyProgramId: type: number description: Loyalty program ID userId: type: number description: User ID currentBalance: type: number description: Current available points lifetimeEarned: type: number description: Total points earned (never decreases) lifetimeRedeemed: type: number description: Total points redeemed lifetimeExpired: type: number description: Total points expired currentTierId: type: number nullable: true description: Current tier ID tierAchievedAt: type: string format: date-time nullable: true description: When current tier was achieved createdAt: type: string format: date-time updatedAt: type: string format: date-time additionalProperties: false pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages required: - accounts meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/programs/{programId}/earning-rules: get: summary: List earning rules tags: - Loyalty Programs description: |- Get all earning rules for a loyalty program **Permissions:** 🔵 `loyalty.read` parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: programId required: true description: Loyalty program ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: earningRules: type: array items: type: object properties: id: type: number loyaltyProgramId: type: number name: type: string description: type: string nullable: true ruleType: type: string enum: - SPEND_BASED - ITEM_BASED - VISIT_BASED - ACTION_BASED isActive: type: boolean minTierId: type: number nullable: true description: Minimum tier required to earn from this rule pointsPerCurrencyUnit: type: number nullable: true description: Points per SEK/currency unit minPurchaseAmount: type: number nullable: true description: Minimum purchase to qualify itemId: type: number nullable: true description: Specific item that earns points pointsMode: type: string enum: - FIXED - MULTIPLIER nullable: true description: FIXED or MULTIPLIER pointsPerItem: type: number nullable: true description: Fixed points per item pointsMultiplier: type: number nullable: true description: Multiplier (e.g., 2.0 = 2x base points) pointsPerVisit: type: number nullable: true description: Points per visit/check-in minPurchaseForVisit: type: number nullable: true description: Minimum purchase to qualify as visit actionType: type: string nullable: true description: signup, referral, social_share, review, etc. pointsPerAction: type: number nullable: true description: Points per action maxActionsPerPeriod: type: number nullable: true description: Max times action can earn points actionPeriod: type: string nullable: true description: daily, weekly, monthly, lifetime validFrom: type: string format: date nullable: true validUntil: type: string format: date nullable: true priority: type: number description: Rule evaluation priority (higher = evaluated first) createdAt: type: string format: date-time updatedAt: type: string format: date-time additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/programs/{programId}/rewards: get: summary: List rewards catalog tags: - Loyalty Programs description: |- Get the rewards catalog for a loyalty program **Permissions:** 🔵 `loyalty.read` parameters: - schema: type: string pattern: ^[0-9]+$ in: query name: userId required: false description: Optional user ID. When provided, rewards the user has already hit their max_redemptions_per_user for are filtered out. - schema: type: string pattern: ^[0-9]+$ in: path name: programId required: true description: Loyalty program ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: rewards: type: array items: type: object properties: id: type: number loyaltyProgramId: type: number name: type: string description: type: string nullable: true pointsCost: type: number description: Points required to redeem minTierId: type: number nullable: true description: Minimum tier required to redeem discountId: type: number description: Reference to voucher in discounts table isActive: type: boolean stockQuantity: type: number nullable: true description: Available quantity (NULL = unlimited) maxRedemptionsPerUser: type: number nullable: true description: Max redemptions per user availableFrom: type: string format: date nullable: true availableUntil: type: string format: date nullable: true displayOrder: type: number expirationDays: type: number nullable: true description: Days until redemption expires createdAt: type: string format: date-time updatedAt: type: string format: date-time displayTitle: type: string nullable: true description: Customer-facing title from linked voucher displayDescription: type: string nullable: true description: Customer-facing description from linked voucher additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/programs/{programId}/tiers: get: summary: List loyalty tiers tags: - Loyalty Programs description: |- Get all tiers for a loyalty program **Permissions:** 🔵 `loyalty.read` parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: programId required: true description: Loyalty program ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: tiers: type: array items: type: object properties: id: type: number description: Tier ID loyaltyProgramId: type: number description: Loyalty program ID name: type: string description: Tier name (e.g., Bronze, Silver, Gold) description: type: string nullable: true description: Tier description pointsThreshold: type: number description: Points required for this tier thresholdType: type: string enum: - LIFETIME_POINTS - ROLLING_PERIOD - MANUAL description: LIFETIME_POINTS = based on lifetime_earned, ROLLING_PERIOD = based on points in last X months, MANUAL = manually assigned rollingPeriodMonths: type: number nullable: true description: Required when thresholdType = ROLLING_PERIOD. Points earned in last X months. order: type: number description: Display order (lower = higher tier) createdAt: type: string format: date-time updatedAt: type: string format: date-time additionalProperties: false required: - tiers meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/programs/{programId}/users/{userId}/account: get: summary: Get user points account tags: - Loyalty Programs description: |- Get or create a points account for a specific user in a loyalty program **Permissions:** 🔵 `loyalty.read` parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: programId required: true description: Loyalty program ID - schema: type: string pattern: ^[0-9]+$ in: path name: userId required: true description: User ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Account ID loyaltyProgramId: type: number description: Loyalty program ID userId: type: number description: User ID currentBalance: type: number description: Current available points lifetimeEarned: type: number description: Total points earned (never decreases) lifetimeRedeemed: type: number description: Total points redeemed lifetimeExpired: type: number description: Total points expired currentTierId: type: number nullable: true description: Current tier ID tierAchievedAt: type: string format: date-time nullable: true description: When current tier was achieved createdAt: type: string format: date-time updatedAt: type: string format: date-time additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/programs/{programId}/users/{userId}/redemptions: get: summary: Get user redemptions tags: - Loyalty Programs description: |- Get reward redemption history for a user in a loyalty program **Permissions:** 🔵 `loyalty.read` parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: programId required: true description: Loyalty program ID - schema: type: string pattern: ^[0-9]+$ in: path name: userId required: true description: User ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: redemptions: type: array items: type: object properties: id: type: number pointsAccountId: type: number rewardId: type: number pointsSpent: type: number generatedDiscountId: type: number nullable: true description: Cloned discount with unique code generatedCode: type: string nullable: true description: Generated voucher code status: type: string enum: - active - used - expired - revoked usedAt: type: string format: date-time nullable: true usedInPurchaseId: type: number nullable: true expiresAt: type: string format: date-time nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/rewards: post: summary: Create reward tags: - Loyalty Programs description: |- Create a new reward in the catalog **Permissions:** 🟢 `loyalty.create` requestBody: content: application/json: schema: type: object required: - loyaltyProgramId - name - pointsCost - discountId properties: loyaltyProgramId: type: number name: type: string minLength: 1 description: type: string pointsCost: type: number minimum: 1 minTierId: type: number discountId: type: number isActive: type: boolean default: true stockQuantity: type: number maxRedemptionsPerUser: type: number availableFrom: type: string format: date nullable: true availableUntil: type: string format: date nullable: true displayOrder: type: number default: 0 expirationDays: type: number required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number loyaltyProgramId: type: number name: type: string description: type: string nullable: true pointsCost: type: number description: Points required to redeem minTierId: type: number nullable: true description: Minimum tier required to redeem discountId: type: number description: Reference to voucher in discounts table isActive: type: boolean stockQuantity: type: number nullable: true description: Available quantity (NULL = unlimited) maxRedemptionsPerUser: type: number nullable: true description: Max redemptions per user availableFrom: type: string format: date nullable: true availableUntil: type: string format: date nullable: true displayOrder: type: number expirationDays: type: number nullable: true description: Days until redemption expires createdAt: type: string format: date-time updatedAt: type: string format: date-time displayTitle: type: string nullable: true description: Customer-facing title from linked voucher displayDescription: type: string nullable: true description: Customer-facing description from linked voucher additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/rewards/{id}: put: summary: Update reward tags: - Loyalty Programs description: |- Update an existing reward in the catalog **Permissions:** 🟠 `loyalty.update` requestBody: content: application/json: schema: type: object properties: name: type: string description: type: string pointsCost: type: number minimum: 1 minTierId: type: number discountId: type: number isActive: type: boolean stockQuantity: type: number maxRedemptionsPerUser: type: number availableFrom: type: string format: date nullable: true availableUntil: type: string format: date nullable: true displayOrder: type: number expirationDays: type: number parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: id required: true description: Reward ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number loyaltyProgramId: type: number name: type: string description: type: string nullable: true pointsCost: type: number description: Points required to redeem minTierId: type: number nullable: true description: Minimum tier required to redeem discountId: type: number description: Reference to voucher in discounts table isActive: type: boolean stockQuantity: type: number nullable: true description: Available quantity (NULL = unlimited) maxRedemptionsPerUser: type: number nullable: true description: Max redemptions per user availableFrom: type: string format: date nullable: true availableUntil: type: string format: date nullable: true displayOrder: type: number expirationDays: type: number nullable: true description: Days until redemption expires createdAt: type: string format: date-time updatedAt: type: string format: date-time displayTitle: type: string nullable: true description: Customer-facing title from linked voucher displayDescription: type: string nullable: true description: Customer-facing description from linked voucher additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete reward tags: - Loyalty Programs description: |- Delete a reward from the catalog **Permissions:** 🔴 `loyalty.delete` parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: id required: true description: Reward ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: message: type: string id: type: number meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/tiers: post: summary: Create loyalty tier tags: - Loyalty Programs description: |- Create a new tier for a loyalty program **Permissions:** 🟢 `loyalty.create` requestBody: content: application/json: schema: type: object properties: loyaltyProgramId: type: number name: type: string minLength: 1 description: type: string nullable: true pointsThreshold: type: number minimum: 0 thresholdType: type: string enum: - LIFETIME_POINTS - ROLLING_PERIOD - MANUAL default: LIFETIME_POINTS rollingPeriodMonths: type: number nullable: true minimum: 1 description: Required when thresholdType = ROLLING_PERIOD tierCardImageUrl: type: string nullable: true description: Tier card image URL tierColor: type: string nullable: true description: Tier card color (hex) order: type: number default: 0 required: - loyaltyProgramId - name required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Tier ID loyaltyProgramId: type: number description: Loyalty program ID name: type: string description: Tier name (e.g., Bronze, Silver, Gold) description: type: string nullable: true description: Tier description pointsThreshold: type: number description: Points required for this tier thresholdType: type: string enum: - LIFETIME_POINTS - ROLLING_PERIOD - MANUAL description: LIFETIME_POINTS = based on lifetime_earned, ROLLING_PERIOD = based on points in last X months, MANUAL = manually assigned rollingPeriodMonths: type: number nullable: true description: Required when thresholdType = ROLLING_PERIOD. Points earned in last X months. order: type: number description: Display order (lower = higher tier) createdAt: type: string format: date-time updatedAt: type: string format: date-time additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/tiers/{id}: put: summary: Update loyalty tier tags: - Loyalty Programs description: |- Update an existing loyalty tier **Permissions:** 🟠 `loyalty.update` requestBody: content: application/json: schema: type: object properties: name: type: string description: Tier name description: type: string nullable: true description: Tier description pointsThreshold: type: number minimum: 0 description: Points required for this tier thresholdType: type: string enum: - LIFETIME_POINTS - ROLLING_PERIOD - MANUAL rollingPeriodMonths: type: number nullable: true minimum: 1 tierCardImageUrl: type: string nullable: true description: Tier card image URL tierColor: type: string nullable: true description: Tier card color (hex) order: type: number parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: id required: true description: Tier ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Tier ID loyaltyProgramId: type: number description: Loyalty program ID name: type: string description: Tier name (e.g., Bronze, Silver, Gold) description: type: string nullable: true description: Tier description pointsThreshold: type: number description: Points required for this tier thresholdType: type: string enum: - LIFETIME_POINTS - ROLLING_PERIOD - MANUAL description: LIFETIME_POINTS = based on lifetime_earned, ROLLING_PERIOD = based on points in last X months, MANUAL = manually assigned rollingPeriodMonths: type: number nullable: true description: Required when thresholdType = ROLLING_PERIOD. Points earned in last X months. order: type: number description: Display order (lower = higher tier) createdAt: type: string format: date-time updatedAt: type: string format: date-time additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete loyalty tier tags: - Loyalty Programs description: |- Delete a loyalty tier **Permissions:** 🔴 `loyalty.delete` parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: id required: true description: Tier ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: message: type: string id: type: number meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/transactions: get: summary: List points transactions tags: - Loyalty Programs description: >- Get points transactions with optional filters (account, user, type, date range) **Permissions:** 🔵 `loyalty.read` parameters: - schema: type: number in: query name: pointsAccountId required: false description: Filter by points account ID - schema: type: number in: query name: programId required: false description: Filter by loyalty program ID - schema: type: number in: query name: userId required: false description: Filter by user ID - schema: type: string in: query name: transactionType required: false description: Filter by transaction type - schema: type: string format: date in: query name: startDate required: false description: Filter by start date - schema: type: string format: date in: query name: endDate required: false description: Filter by end date - schema: type: number minimum: 1 default: 1 in: query name: page required: false - schema: type: number minimum: 1 maximum: 1000 default: 50 in: query name: limit required: false responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: transactions: type: array items: type: object properties: id: type: string format: uuid description: Transaction UUID pointsAccountId: type: number description: Points account ID transactionType: type: string enum: - EARNED_PURCHASE - EARNED_ITEM - EARNED_VISIT - EARNED_ACTION - REDEEMED - EXPIRED - ADJUSTED - REVOKED description: Transaction type points: type: number description: Points amount (positive for earned, negative for redeemed/expired) balanceAfter: type: number description: Balance after this transaction purchaseId: type: number nullable: true description: Related purchase ID earningRuleId: type: number nullable: true description: Earning rule that triggered this transaction rewardRedemptionId: type: number nullable: true description: Reward redemption that caused this transaction description: type: string nullable: true description: Human-readable description metadata: type: object nullable: true additionalProperties: true description: Additional context expiresAt: type: string format: date nullable: true description: When these points expire createdAt: type: string format: date-time updatedAt: type: string format: date-time user: type: object nullable: true properties: email: type: string nullable: true name: type: string nullable: true phone: type: string nullable: true description: Member who made this transaction additionalProperties: false pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/users/{userId}/programs: get: summary: Get user enrolled programs tags: - Loyalty Programs description: >- Get all loyalty programs a user is enrolled in with account details and current tier. Users can only view their own enrollments. API keys with 'loyalty.read' permission can view any user's enrollments. **Permissions:** 🔵 `loyalty.read` parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: userId required: true description: User ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: programs: type: array items: type: object properties: id: type: number description: Loyalty program ID locationId: type: number description: Location ID locationSlug: type: string nullable: true description: Active location slug for storefront URL name: type: string description: Program name description: type: string nullable: true description: Program description currency: type: string description: Currency code (e.g., SEK, USD) isActive: type: boolean description: Whether program is active startDate: type: string format: date nullable: true description: Program start date endDate: type: string format: date nullable: true description: Program end date loyaltyCardImage: type: string nullable: true description: Loyalty card image URL loyaltyColor: type: string nullable: true description: Loyalty card color (hex) createdAt: type: string format: date-time description: Program creation timestamp updatedAt: type: string format: date-time description: Program last update timestamp enrollment: type: object properties: accountId: type: number description: Points account ID cardId: type: string description: Loyalty card identifier currentBalance: type: number description: Current points balance lifetimeEarned: type: number description: Total points earned all-time lifetimeRedeemed: type: number description: Total points redeemed all-time lifetimeExpired: type: number description: Total points expired all-time enrolledAt: type: string format: date-time description: Enrollment timestamp updatedAt: type: string format: date-time description: Account last update timestamp required: - accountId - cardId - currentBalance - lifetimeEarned - lifetimeRedeemed - lifetimeExpired - enrolledAt - updatedAt currentTier: oneOf: - type: object properties: id: type: number description: Tier ID name: type: string description: Tier name description: type: string nullable: true description: Tier description pointsThreshold: type: number description: Points required for this tier thresholdType: type: string description: LIFETIME_POINTS or ROLLING_PERIOD benefits: description: Tier benefits (JSON) tierCardImageUrl: type: string nullable: true description: Tier card image URL tierColor: type: string nullable: true description: Tier color required: - id - name - pointsThreshold - thresholdType additionalProperties: false - type: "null" description: Current tier information, or null if no tier required: - id - locationId - name - currency - isActive - createdAt - updatedAt - enrollment - currentTier additionalProperties: false description: List of loyalty programs the user is enrolled in required: - programs meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/validate: post: summary: Validate loyalty members tags: - Loyalty Programs description: Validate loyalty membership for multiple users by userId, email, phone, or cardId requestBody: content: application/json: schema: type: object properties: users: type: array description: Array of user identifiers to validate items: type: object properties: userId: type: number description: User ID (optional if email, phone, or cardId provided) email: type: string description: User email (optional if userId, phone, or cardId provided) phone: type: string description: User phone (optional if userId, email, or cardId provided) cardId: type: string description: Loyalty card ID (optional if userId, email, or phone provided) minProperties: 1 required: - users required: true responses: "200": description: Loyalty validation results content: application/json: schema: description: Loyalty validation results type: object properties: status: type: string enum: - success data: type: object properties: hasLoyaltyProgram: type: boolean description: Whether this location has an active loyalty program programId: type: number nullable: true description: Loyalty program ID (null if no program) programName: type: string nullable: true description: Loyalty program name (null if no program) users: type: array description: Enrollment status for each requested user items: type: object properties: userId: type: number nullable: true description: User ID if found email: type: string nullable: true description: User email if found phone: type: string nullable: true description: User phone if found cardId: type: string nullable: true description: Loyalty card ID if found isEnrolled: type: boolean description: Whether user is enrolled in loyalty program currentBalance: type: number nullable: true description: Current loyalty points balance (null if not enrolled) lifetimeEarned: type: number nullable: true description: Total points earned all time (null if not enrolled) lifetimeRedeemed: type: number nullable: true description: Total points redeemed all time (null if not enrolled) currentTier: type: string nullable: true description: Current tier name (null if not enrolled or no tiers) accountId: type: number nullable: true description: Loyalty account ID (null if not enrolled) required: - userId - email - phone - cardId - isEnrolled - currentBalance - lifetimeEarned - lifetimeRedeemed - currentTier - accountId required: - hasLoyaltyProgram - programId - programName - users meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/enrollment-token-preview: get: summary: Preview enrollment token tags: - Loyalty Self-Service description: Verify an enrollment JWT token and return card details without consuming (marking as used) the token. parameters: - schema: type: string in: query name: token required: true description: JWT enrollment token from QR code responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success - error data: type: object properties: valid: type: boolean reason: type: string nullable: true purchaseIntentId: type: string nullable: true locationId: type: number nullable: true last4: type: string nullable: true brand: type: string nullable: true pointsAlreadyAwarded: type: boolean nullable: true meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/self-service-enroll: post: summary: Self-service card enrollment tags: - Loyalty Self-Service description: "Link a payment card to a user account via self-service. Supports two modes: (1) QR flow with enrollment token, (2) confirmation page flow with purchaseIntentId + userId." requestBody: content: application/json: schema: type: object required: - userId properties: token: type: string description: JWT enrollment token (QR flow). Mutually exclusive with purchaseIntentId. purchaseIntentId: type: string description: Purchase intent ID (confirmation page flow). Mutually exclusive with token. userId: type: number description: Guest user ID (passed in body — API key auth has no guest identity) required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: cardLinked: type: boolean enrolled: type: boolean pointsAwarded: type: number pointsAlreadyAwarded: type: boolean nullable: true newBalance: type: number nullable: true meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/{programId}/wallet-pass/broadcast-marketing: post: tags: - Loyalty Wallet Passes description: Send a marketing push (headline + body) to every saved Apple/Google Wallet card for this loyalty program requestBody: content: application/json: schema: type: object required: - headline - body properties: headline: type: string minLength: 1 maxLength: 120 body: type: string minLength: 1 maxLength: 280 url: type: string format: uri required: true parameters: - schema: type: string in: path name: programId required: true description: Loyalty program ID responses: "200": description: Default Response /api/v1/loyalty/{programId}/wallet-pass/broadcast-push: post: tags: - Loyalty Wallet Passes description: Broadcast wallet pass push notification to all registered devices for a loyalty program parameters: - schema: type: string in: path name: programId required: true description: Loyalty program ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string data: type: object properties: notified: type: number serialNumbers: type: array items: type: string /api/v1/menu-layouts: get: summary: List menu layouts tags: - Menu Layouts description: >- List menu layouts with optional filtering by location, schedule, and channels **Permissions:** 🔵 `menu_layouts.read` parameters: - schema: type: number in: query name: locationId required: false description: Filter by location ID - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: number minimum: 1 maximum: 100 default: 20 in: query name: limit required: false description: Items per page - schema: type: string in: query name: availableOnly required: false description: Filter by schedule availability (ISO timestamp or "true") - schema: type: string in: query name: channels required: false description: Filter by channels (comma-separated channel types) - schema: type: string enum: - "true" - "false" in: query name: templatesOnly required: false description: Filter to only return templates - schema: type: string enum: - "true" - "false" in: query name: excludeTemplates required: false description: Exclude templates from results - schema: type: string enum: - "true" - "false" in: query name: resolveReferences required: false description: Resolve linked template references in the context - schema: type: string enum: - "true" - "false" in: query name: excludeUnmapped required: false description: Drop product nodes whose item lacks a POS integration_resource_mappings row. Used by storefront to hide items that would silently fail at the POS. No-op when the location has no active POS integration. responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: layouts: type: array items: type: object properties: id: type: string description: Unique menu layout ID locationId: type: number description: Location ID this layout belongs to context: type: object description: JSON object storing the POS screen configuration and layout structure additionalProperties: true createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time nullable: true description: Last update timestamp sortOrder: type: number nullable: true description: Display order for menu layouts (lower values first) isTemplate: type: boolean nullable: true description: Whether this layout is a reusable template templateName: type: string nullable: true description: Display name for the template usageCount: type: number description: Number of menus using this template (only for templates) scheduleRules: type: array description: Schedule rules for time-based availability items: type: object properties: id: type: string description: Rule ID dayOfWeek: type: number minimum: 0 maximum: 6 description: Day of week (0=Sunday, 6=Saturday) startTime: type: string pattern: ^[0-2][0-9]:[0-5][0-9]$ description: Start time (HH:MM) endTime: type: string pattern: ^[0-2][0-9]:[0-5][0-9]$ description: End time (HH:MM) active: type: boolean description: Whether item is available during this time channelAvailability: type: object description: Channel availability flags properties: online: type: boolean description: Available on online channel qr: type: boolean description: Available on QR channel kiosk: type: boolean description: Available on kiosk channel pos: type: boolean description: Available on POS channel required: - id - locationId - context - createdAt pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages required: - layouts - pagination meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: summary: Create menu layout tags: - Menu Layouts description: |- Create a new menu layout **Permissions:** 🟢 `menu_layouts.create` requestBody: content: application/json: schema: type: object properties: locationId: type: number description: Location ID context: type: object description: JSON object with POS screen layout configuration additionalProperties: true isTemplate: type: boolean description: Whether this layout should be a reusable template templateName: type: string description: Display name for the template (required if isTemplate is true) required: - locationId - context required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string description: Unique menu layout ID locationId: type: number description: Location ID this layout belongs to context: type: object description: JSON object storing the POS screen configuration and layout structure additionalProperties: true createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time nullable: true description: Last update timestamp sortOrder: type: number nullable: true description: Display order for menu layouts (lower values first) isTemplate: type: boolean nullable: true description: Whether this layout is a reusable template templateName: type: string nullable: true description: Display name for the template usageCount: type: number description: Number of menus using this template (only for templates) scheduleRules: type: array description: Schedule rules for time-based availability items: type: object properties: id: type: string description: Rule ID dayOfWeek: type: number minimum: 0 maximum: 6 description: Day of week (0=Sunday, 6=Saturday) startTime: type: string pattern: ^[0-2][0-9]:[0-5][0-9]$ description: Start time (HH:MM) endTime: type: string pattern: ^[0-2][0-9]:[0-5][0-9]$ description: End time (HH:MM) active: type: boolean description: Whether item is available during this time channelAvailability: type: object description: Channel availability flags properties: online: type: boolean description: Available on online channel qr: type: boolean description: Available on QR channel kiosk: type: boolean description: Available on kiosk channel pos: type: boolean description: Available on POS channel required: - id - locationId - context - createdAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/menu-layouts/{id}: get: summary: Get menu layout tags: - Menu Layouts description: >- Get a single menu layout by ID. Use resolveReferences=true to expand linked template references. **Permissions:** 🔵 `menu_layouts.read` parameters: - schema: type: string enum: - "true" - "false" in: query name: resolveReferences required: false description: Resolve linked template references in the context - schema: type: string enum: - "true" - "false" in: query name: excludeUnmapped required: false description: Drop product nodes whose item lacks a POS integration_resource_mappings row. No-op when the location has no active POS integration. - schema: type: string format: uuid in: path name: id required: true description: Menu layout ID (UUID) responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string description: Unique menu layout ID locationId: type: number description: Location ID this layout belongs to context: type: object description: JSON object storing the POS screen configuration and layout structure additionalProperties: true createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time nullable: true description: Last update timestamp sortOrder: type: number nullable: true description: Display order for menu layouts (lower values first) isTemplate: type: boolean nullable: true description: Whether this layout is a reusable template templateName: type: string nullable: true description: Display name for the template usageCount: type: number description: Number of menus using this template (only for templates) scheduleRules: type: array description: Schedule rules for time-based availability items: type: object properties: id: type: string description: Rule ID dayOfWeek: type: number minimum: 0 maximum: 6 description: Day of week (0=Sunday, 6=Saturday) startTime: type: string pattern: ^[0-2][0-9]:[0-5][0-9]$ description: Start time (HH:MM) endTime: type: string pattern: ^[0-2][0-9]:[0-5][0-9]$ description: End time (HH:MM) active: type: boolean description: Whether item is available during this time channelAvailability: type: object description: Channel availability flags properties: online: type: boolean description: Available on online channel qr: type: boolean description: Available on QR channel kiosk: type: boolean description: Available on kiosk channel pos: type: boolean description: Available on POS channel required: - id - locationId - context - createdAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: summary: Update menu layout tags: - Menu Layouts description: |- Update an existing menu layout **Permissions:** 🟠 `menu_layouts.update` requestBody: content: application/json: schema: type: object properties: context: type: object description: Updated JSON object with POS screen layout configuration additionalProperties: true isTemplate: type: boolean description: Whether this layout should be a reusable template templateName: type: string description: Display name for the template parameters: - schema: type: string format: uuid in: path name: id required: true description: Menu layout ID (UUID) responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string description: Unique menu layout ID locationId: type: number description: Location ID this layout belongs to context: type: object description: JSON object storing the POS screen configuration and layout structure additionalProperties: true createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time nullable: true description: Last update timestamp sortOrder: type: number nullable: true description: Display order for menu layouts (lower values first) isTemplate: type: boolean nullable: true description: Whether this layout is a reusable template templateName: type: string nullable: true description: Display name for the template usageCount: type: number description: Number of menus using this template (only for templates) scheduleRules: type: array description: Schedule rules for time-based availability items: type: object properties: id: type: string description: Rule ID dayOfWeek: type: number minimum: 0 maximum: 6 description: Day of week (0=Sunday, 6=Saturday) startTime: type: string pattern: ^[0-2][0-9]:[0-5][0-9]$ description: Start time (HH:MM) endTime: type: string pattern: ^[0-2][0-9]:[0-5][0-9]$ description: End time (HH:MM) active: type: boolean description: Whether item is available during this time channelAvailability: type: object description: Channel availability flags properties: online: type: boolean description: Available on online channel qr: type: boolean description: Available on QR channel kiosk: type: boolean description: Available on kiosk channel pos: type: boolean description: Available on POS channel required: - id - locationId - context - createdAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete menu layout tags: - Menu Layouts description: >- Delete a menu layout. If the layout is a template that is being used, set force=true to delete anyway. **Permissions:** 🔴 `menu_layouts.delete` parameters: - schema: type: string enum: - "true" - "false" in: query name: force required: false description: Force delete a template even if it is being used in menus - schema: type: string format: uuid in: path name: id required: true description: Menu layout ID (UUID) responses: "200": description: Menu layout successfully deleted content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: deleted: type: boolean meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/menu-layouts/{id}/usage: get: summary: Get template usage tags: - Menu Layouts description: |- Get information about which menus are using a template **Permissions:** 🔵 `menu_layouts.read` parameters: - schema: type: string format: uuid in: path name: id required: true description: Menu layout ID (UUID) responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: templateId: type: string description: The template ID usageCount: type: number description: Number of menus using this template usedIn: type: array items: type: object properties: menuId: type: string description: Menu ID menuTitle: type: string description: Menu title linked: type: boolean description: Whether the reference is linked (auto-updates) or copied description: List of menus using this template required: - templateId - usageCount - usedIn meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/menu-layouts/reorder: post: summary: Reorder menu layouts tags: - Menu Layouts description: |- Reorder menu layouts by updating their sort order **Permissions:** 🟠 `menu_layouts.update` requestBody: content: application/json: schema: type: object properties: layoutIds: type: array items: type: string description: Array of menu layout IDs in the desired display order required: - layoutIds required: true responses: "200": description: Menu layouts successfully reordered content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: success: type: boolean layoutIds: type: array items: type: string meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/notes: get: summary: List notes for an entity tags: - Notes description: >- List all notes attached to a specific entity (tab or user). Notes are returned in sort order (lowest sortOrder first). **Permissions:** 🔵 `notes.read` parameters: - schema: type: string enum: - tab - user - booking in: query name: entityType required: true description: Type of entity to fetch notes for - schema: type: string in: query name: entityId required: true description: ID of the entity (tab UUID or user ID) responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: notes: type: array items: type: object properties: uuid: type: string format: uuid description: Note UUID entityType: type: string enum: - tab - user - booking description: Type of entity this note is attached to entityId: type: string description: ID of the entity (tab UUID or user ID) note: type: string description: Note content locationId: type: number description: Location ID sortOrder: type: number description: Sort order for displaying notes (lower = first) createdByRetailerUserId: type: number nullable: true description: Retailer user ID who created the note createdByName: type: string nullable: true description: Name of the user who created the note updatedByRetailerUserId: type: number nullable: true description: Retailer user ID who last updated the note updatedByName: type: string nullable: true description: Name of the user who last updated the note createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - entityType - entityId - note - locationId - sortOrder - createdAt - updatedAt required: - notes meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: summary: Create a note tags: - Notes description: >- Create a new note attached to an entity (tab or user). The note will be associated with the current location and the authenticated user (if using JWT auth). **Permissions:** 🟢 `notes.create` requestBody: content: application/json: schema: type: object properties: entityType: type: string enum: - tab - user - booking description: Type of entity to attach the note to entityId: type: string description: ID of the entity (tab UUID or user ID) note: type: string minLength: 1 description: Note content required: - entityType - entityId - note additionalProperties: false required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: uuid: type: string format: uuid description: Note UUID entityType: type: string enum: - tab - user - booking description: Type of entity this note is attached to entityId: type: string description: ID of the entity (tab UUID or user ID) note: type: string description: Note content locationId: type: number description: Location ID sortOrder: type: number description: Sort order for displaying notes (lower = first) createdByRetailerUserId: type: number nullable: true description: Retailer user ID who created the note createdByName: type: string nullable: true description: Name of the user who created the note updatedByRetailerUserId: type: number nullable: true description: Retailer user ID who last updated the note updatedByName: type: string nullable: true description: Name of the user who last updated the note createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - entityType - entityId - note - locationId - sortOrder - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/notes/{uuid}: get: summary: Get a note tags: - Notes description: |- Get a single note by UUID **Permissions:** 🔵 `notes.read` parameters: - schema: type: string format: uuid in: path name: uuid required: true description: Note UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: uuid: type: string format: uuid description: Note UUID entityType: type: string enum: - tab - user - booking description: Type of entity this note is attached to entityId: type: string description: ID of the entity (tab UUID or user ID) note: type: string description: Note content locationId: type: number description: Location ID sortOrder: type: number description: Sort order for displaying notes (lower = first) createdByRetailerUserId: type: number nullable: true description: Retailer user ID who created the note createdByName: type: string nullable: true description: Name of the user who created the note updatedByRetailerUserId: type: number nullable: true description: Retailer user ID who last updated the note updatedByName: type: string nullable: true description: Name of the user who last updated the note createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - entityType - entityId - note - locationId - sortOrder - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 patch: summary: Update a note tags: - Notes description: >- Update an existing note. The updated_by fields will be set to the authenticated user. **Permissions:** 🟠 `notes.update` requestBody: content: application/json: schema: type: object properties: note: type: string minLength: 1 description: Updated note content required: - note additionalProperties: false required: true parameters: - schema: type: string format: uuid in: path name: uuid required: true description: Note UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: uuid: type: string format: uuid description: Note UUID entityType: type: string enum: - tab - user - booking description: Type of entity this note is attached to entityId: type: string description: ID of the entity (tab UUID or user ID) note: type: string description: Note content locationId: type: number description: Location ID sortOrder: type: number description: Sort order for displaying notes (lower = first) createdByRetailerUserId: type: number nullable: true description: Retailer user ID who created the note createdByName: type: string nullable: true description: Name of the user who created the note updatedByRetailerUserId: type: number nullable: true description: Retailer user ID who last updated the note updatedByName: type: string nullable: true description: Name of the user who last updated the note createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - entityType - entityId - note - locationId - sortOrder - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete a note tags: - Notes description: |- Delete a note by UUID **Permissions:** 🔴 `notes.delete` parameters: - schema: type: string format: uuid in: path name: uuid required: true description: Note UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: deleted: type: boolean enum: - true required: - deleted meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/notes/reorder: post: summary: Reorder notes tags: - Notes description: >- Reorder notes for an entity. Pass an array of note UUIDs in the desired order. Each note will have its sortOrder updated to match its position in the array. **Permissions:** 🟠 `notes.update` requestBody: content: application/json: schema: type: object properties: noteUuids: type: array items: type: string format: uuid minItems: 1 description: Array of note UUIDs in the desired order required: - noteUuids additionalProperties: false required: true parameters: - schema: type: string enum: - tab - user - booking in: query name: entityType required: true description: Type of entity to fetch notes for - schema: type: string in: query name: entityId required: true description: ID of the entity (tab UUID or user ID) responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: notes: type: array items: type: object properties: uuid: type: string format: uuid description: Note UUID entityType: type: string enum: - tab - user - booking description: Type of entity this note is attached to entityId: type: string description: ID of the entity (tab UUID or user ID) note: type: string description: Note content locationId: type: number description: Location ID sortOrder: type: number description: Sort order for displaying notes (lower = first) createdByRetailerUserId: type: number nullable: true description: Retailer user ID who created the note createdByName: type: string nullable: true description: Name of the user who created the note updatedByRetailerUserId: type: number nullable: true description: Retailer user ID who last updated the note updatedByName: type: string nullable: true description: Name of the user who last updated the note createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - entityType - entityId - note - locationId - sortOrder - createdAt - updatedAt required: - notes meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/kitchen-dispatch-items/{id}: delete: summary: Delete kitchen dispatch item tags: - Orders description: Remove a single item from an order. Disallowed when the item is already paid or has a settlement in progress. parameters: - schema: type: string format: uuid in: path name: id required: true description: Kitchen dispatch item UUID responses: "200": description: Successfully deleted item content: application/json: schema: description: Successfully deleted item type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid kitchenDispatchId: type: string format: uuid tabId: type: string format: uuid kitchenDispatchEmptied: type: boolean deleted: type: boolean required: - id - kitchenDispatchId - tabId - kitchenDispatchEmptied - deleted meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/kitchen-dispatch-items/{id}/split: get: summary: Get split order items tags: - Orders description: Get all items that were split from an order item for bill splitting parameters: - schema: type: string format: uuid in: path name: id required: true description: Kitchen dispatch item UUID (the split_of_kitchen_dispatch_item reference) responses: "200": description: Successfully retrieved split items content: application/json: schema: description: Successfully retrieved split items type: object properties: status: type: string enum: - success data: type: object properties: items: type: array items: type: object properties: uuid: type: string format: uuid description: Split item UUID basePrice: type: number description: Base price in cents modificationPrice: type: number description: Total modification price in cents price: type: number description: Final price in cents title: type: string description: Item title currencyCode: type: string description: Currency code (e.g., SEK) modifications: type: array items: type: object properties: title: type: string variantId: type: number variantGroupId: type: number type: type: string enum: - variant - extra amount: type: number description: Price in cents required: - uuid - basePrice - modificationPrice - price - title - currencyCode - modifications originalItemId: type: string format: uuid description: The original item UUID that was split required: - items - originalItemId meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: summary: Split order item tags: - Orders description: Split an order item into multiple parts for bill splitting with equal pricing requestBody: content: application/json: schema: type: object properties: numberOfParts: type: number minimum: 2 maximum: 10 description: Number of parts to split the item into (2-10) tabId: type: string format: uuid description: Tab UUID that the item belongs to required: - numberOfParts - tabId required: true parameters: - schema: type: string format: uuid in: path name: id required: true description: Kitchen dispatch item UUID responses: "200": description: Successfully split the item content: application/json: schema: description: Successfully split the item type: object properties: status: type: string enum: - success data: type: object properties: splitItemIds: type: array items: type: string format: uuid description: UUIDs of the newly created split items originalItemId: type: string format: uuid description: UUID of the original item (now deleted) required: - splitItemIds - originalItemId meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/kitchen-dispatch-items/{id}/takeaway: patch: summary: Toggle takeaway status tags: - Orders description: Toggle takeaway status on a kitchen dispatch item requestBody: content: application/json: schema: type: object properties: is_takeaway: type: boolean description: Whether the item is takeaway required: - is_takeaway required: true parameters: - schema: type: string format: uuid in: path name: id required: true description: Kitchen dispatch item UUID responses: "200": description: Successfully toggled takeaway status content: application/json: schema: description: Successfully toggled takeaway status type: object properties: status: type: string data: type: object properties: uuid: type: string isTakeaway: type: boolean meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/kitchen-dispatch-items/{id}/void: post: summary: Void a kitchen dispatch item tags: - Orders description: Set item_state to "aborted" on a kitchen dispatch item. Requires orders.void permission. Rejects when the parent tab has any purchases. When reasonCode is "other", reasonNote is required. requestBody: content: application/json: schema: type: object properties: reasonCode: type: string enum: - staff_mistake - customer_change - wrong_make - quality_issue - out_of_stock - allergy - other description: Reason code from the locked enum reasonNote: type: - string - "null" maxLength: 500 description: Optional free-text note; REQUIRED when reasonCode is "other" quantityCents: type: - integer - "null" minimum: 1 description: Optional partial-void quantity in basis-points (null = full quantity). Stored only in audit. suppressKorrbong: type: boolean description: When true, suppress the order.reversed webhook so printer-service does not print a KORRBONG correction ticket. Used by cafe-mode void-and-replace flows. required: - reasonCode additionalProperties: false required: true parameters: - schema: type: string format: uuid in: path name: id required: true description: Kitchen dispatch item UUID responses: "200": description: Successfully voided the item content: application/json: schema: description: Successfully voided the item type: object properties: status: type: string enum: - success data: type: object properties: kitchenDispatchItemId: type: string format: uuid previousItemState: type: - "null" - string newItemState: type: string enum: - aborted reasonCode: type: string enum: - staff_mistake - customer_change - wrong_make - quality_issue - out_of_stock - allergy - other reasonNote: type: - "null" - string dispatchAborted: type: boolean required: - kitchenDispatchItemId - previousItemState - newItemState - reasonCode - reasonNote - dispatchAborted meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/kitchen-dispatch-items/void-batch: post: summary: Void one or more kitchen dispatch items tags: - Orders description: Set item_state to "aborted" on multiple kitchen dispatch items in one request. Items may span multiple parent dispatches; one `order.reversed` event is emitted per affected KD. Requires orders.void permission. Rejects when ANY affected tab has purchases. When reasonCode is "other", reasonNote is required. requestBody: content: application/json: schema: type: object properties: reasonCode: type: string enum: - staff_mistake - customer_change - wrong_make - quality_issue - out_of_stock - allergy - other description: Reason code from the locked enum, applied to every item in the batch reasonNote: type: - string - "null" maxLength: 500 description: Optional free-text note; REQUIRED when reasonCode is "other" items: type: array minItems: 1 maxItems: 100 description: Kitchen dispatch items to void items: type: object properties: id: type: string format: uuid quantityCents: type: - integer - "null" minimum: 1 description: Optional partial-void quantity (null = full). required: - id additionalProperties: false suppressKorrbong: type: boolean description: When true, suppress the order.reversed webhook so printer-service does not print a KORRBONG per affected dispatch. Used by cafe-mode void-and-replace flows. required: - reasonCode - items additionalProperties: false required: true responses: "200": description: Successfully voided all items in the batch content: application/json: schema: description: Successfully voided all items in the batch type: object properties: status: type: string enum: - success data: type: object properties: reasonCode: type: string enum: - staff_mistake - customer_change - wrong_make - quality_issue - out_of_stock - allergy - other reasonNote: type: - "null" - string results: type: array items: type: object properties: kitchenDispatchItemId: type: string format: uuid kitchenDispatchId: type: string format: uuid previousItemState: type: - "null" - string newItemState: type: string enum: - aborted dispatchAborted: type: boolean required: - kitchenDispatchItemId - kitchenDispatchId - previousItemState - newItemState - dispatchAborted affectedDispatchIds: type: array items: type: string format: uuid required: - reasonCode - reasonNote - results - affectedDispatchIds meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/orders: get: summary: List orders tags: - Orders description: >- Retrieve a paginated list of orders with filtering capabilities. **Hybrid Dual-Fetch Architecture:** - PostgreSQL for recent orders (<30 minutes old) - ensures freshness - BigQuery for historical orders (>30 minutes old) - scalability - Automatic merge when date range spans both sources **KDS/Real-Time Mode:** - Use `forcePostgres=true` to always query PostgreSQL only - This ensures fresh state data for Kitchen Display Systems - Recommended for any real-time display needing immediate state updates **Default Behavior:** - Returns last 24 hours if no date filters specified - Sorted by created_at descending (newest first) - Items not included by default (use includeItems=true) **Performance Notes:** - BigQuery queries typically take 1-3 seconds - For real-time displays, use forcePostgres=true or /api/v1/orders/stream endpoint **Permissions:** 🔵 `orders.read` parameters: - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: number minimum: 1 maximum: 1000 default: 50 in: query name: limit required: false description: Items per page (max 1000) - schema: type: boolean default: false in: query name: includeItems required: false description: Include order items in response. Items are returned FLAT with parentKitchenDispatchItemId for hierarchy building. - schema: type: boolean default: false in: query name: includeNotes required: false description: Include tab notes attached to each order (notes are polymorphic, keyed by tab uuid). Used by the KDS. - schema: type: boolean default: false in: query name: forcePostgres required: false description: Force PostgreSQL only (skip BigQuery). Use for KDS/real-time displays where state must be fresh. - schema: type: boolean default: false in: query name: excludeAbortedTabs required: false description: Hide KDs whose parent tab was force-closed (aborted). Use for the active KDS so staff don't see orphan tickets they cannot advance. Leave off for order history and audit views. - schema: type: number in: query name: dailyOrderNumber required: false description: Filter by daily order number - schema: anyOf: - type: string - type: array items: type: string in: query name: state required: false description: Filter by state(s) - schema: anyOf: - type: string - type: array items: type: string in: query name: tabType required: false description: Filter by tab type(s) - schema: type: string in: query name: tableId required: false description: Filter by table/QR code ID - schema: type: string in: query name: tabMemberEmail required: false description: Filter by tab member email (partial match) - schema: type: number in: query name: minPrice required: false description: Minimum total price in cents - schema: type: number in: query name: maxPrice required: false description: Maximum total price in cents - schema: anyOf: - type: string - type: array items: type: string in: query name: source required: false description: Filter by order source/channel (POS, ONLINE, QR, KIOSK) - schema: type: number in: query name: itemId required: false description: Filter orders containing a specific inventory item ID - schema: anyOf: - type: string - type: array items: type: string in: query name: printerGroupIds required: false description: Filter by prep group (printer group) IDs - schema: type: string format: date-time in: query name: startDate required: false description: "Filter orders created after this date (default: 24 hours ago)" - schema: type: string format: date-time in: query name: endDate required: false description: "Filter orders created before this date (default: now)" - schema: type: string enum: - created_at - daily_ordinal_number - updated_at default: created_at in: query name: sort required: false description: Field to sort by - schema: type: string enum: - asc - desc default: desc in: query name: order required: false description: Sort order responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: items: type: array items: type: object properties: uuid: type: string format: uuid description: Unique order ID (kitchen_dispatch.uuid) locationId: type: number description: Location ID tabId: type: string format: uuid nullable: true description: Associated tab ID dailyOrderNumber: type: number nullable: true description: Daily order number for the location state: type: string enum: - not_sent - pending - accepted - in_preparation - ready_to_deliver - delivered - rejected - rejected_and_acknowledged - staged_awaiting_payment - scheduled - aborted description: Current order state orderType: type: string enum: - TAKEAWAY - OTC - QR - TABLE nullable: true description: Order type orderChannel: type: string enum: - ONLINE - QR - KIOSK - POS nullable: true description: Order channel createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp completedAt: type: string format: date-time nullable: true description: Completion timestamp tabType: type: string nullable: true description: Tab type (table, takeaway, etc.) storefrontQrCodeId: type: string nullable: true description: Table UUID (storefront QR code ID) - frontend maps to name tabMemberEmail: type: string format: email nullable: true description: Tab member email tabMemberName: type: string nullable: true description: Tab member name memberCount: type: number nullable: true description: Guest count on the tab (party size) totalPrice: type: number nullable: true description: Total price in cents itemCount: type: number nullable: true description: Number of items in order message: type: string nullable: true description: Order message/notes source: type: string nullable: true description: Order source items: type: array nullable: true items: type: object additionalProperties: true properties: uuid: type: string format: uuid description: Unique order item ID itemId: type: number nullable: true description: Inventory item ID title: type: string nullable: true description: Item title titlePrep: type: string nullable: true description: Kitchen prep title for KDS display - use instead of title if set quantity: type: number description: Quantity (integer) quantityCents: type: number description: Quantity in cents (e.g., 200 = 2x) price: type: number description: Total price in cents basePrice: type: number description: Base price in cents before discounts discount: type: number nullable: true description: Discount amount in cents status: type: string nullable: true description: Item status comments: {} variants: type: array nullable: true description: Variant/modification data for this item items: type: object properties: id: type: number description: Variant ID name: type: string description: Variant name price: type: number nullable: true description: Variant price in cents quantityCents: type: number nullable: true description: Quantity in cents priceCents: type: number nullable: true description: Price in cents modification_id: type: number description: Modification ID for completion tracking status: type: string nullable: true description: Modification status tabMemberId: type: string format: uuid nullable: true description: Tab member who owns this item createdAt: type: string format: date-time description: Creation timestamp servingCenterId: type: number nullable: true description: Serving center ID for this item printerGroupId: type: string format: uuid nullable: true description: Prep group (printer group) ID for this item tabMemberEmail: type: string format: email nullable: true description: Tab member email tabMemberName: type: string nullable: true description: Tab member name parentKitchenDispatchItemId: type: string format: uuid nullable: true description: Parent item UUID - if set, this is a child/modifier item. Use this to build hierarchy in frontend. itemState: type: string nullable: true description: Item-level state (not_sent, pending, accepted, in_preparation, ready_to_deliver, delivered, rejected) salesItemType: type: string nullable: true description: 'How the line was sold: "regular" or "surplus". Drives the KDS surplus badge.' surplusEntryId: type: number nullable: true description: item_ministock.id this surplus line was sold against (null for regular lines). isTakeaway: type: boolean description: Whether this specific line item is takeaway (independent of the tab-level tabType). Drives the KDS bag indicator. required: - uuid - quantity - quantityCents - price - basePrice - createdAt description: Order items (only when includeItems=true) notes: type: array nullable: true description: Tab notes attached to this order (only when includeNotes=true) items: type: object additionalProperties: true properties: uuid: type: string entityType: type: string entityId: type: string note: type: string locationId: type: number sortOrder: type: number createdByRetailerUserId: type: number nullable: true createdByName: type: string nullable: true updatedByRetailerUserId: type: number nullable: true updatedByName: type: string nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time events: type: array description: Order state change history items: type: object properties: event: type: string description: Event/state name created_at: type: string format: date-time description: Event timestamp required: - event - created_at desiredPickupTime: type: string format: date-time nullable: true description: Desired pickup time for scheduled orders storeCommitmentTimeout: type: string format: date-time nullable: true description: Store commitment timeout for acceptance required: - uuid - locationId - state - createdAt - updatedAt pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages required: - items - pagination meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/orders/{kitchenDispatchId}/cancel: post: summary: Cancel order tags: - Orders description: >- Cancel a kitchen dispatch (order) by setting its state to aborted. Only early-stage orders can be cancelled. **Permissions:** 🟠 `inventory.update` requestBody: content: application/json: schema: type: object properties: reason: type: string description: Optional cancellation reason (for audit trail) parameters: - schema: type: string format: uuid in: path name: kitchenDispatchId required: true description: Kitchen dispatch UUID to cancel responses: "200": description: Order cancelled successfully content: application/json: schema: description: Order cancelled successfully type: object properties: status: type: string enum: - success data: type: object properties: kitchenDispatchId: type: string format: uuid description: Kitchen dispatch UUID previousState: type: string description: State before cancellation newState: type: string enum: - aborted description: New state after cancellation cancelledAt: type: string format: date-time description: ISO 8601 timestamp of cancellation cancelledBy: type: number description: User ID who cancelled the order reason: type: string nullable: true description: Cancellation reason (if provided) tabId: type: string format: uuid description: Tab UUID that the order belongs to required: - kitchenDispatchId - previousState - newState - cancelledAt - cancelledBy - reason - tabId meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Invalid state - Order cannot be cancelled in current state content: application/json: schema: description: Invalid state - Order cannot be cancelled in current state type: object properties: status: type: string enum: - error error: type: object properties: code: type: string enum: - INVALID_STATE message: type: string details: type: object properties: currentState: type: string cancellableStates: type: array items: type: string meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "401": description: Unauthorized - Missing or invalid authentication content: application/json: schema: description: Unauthorized - Missing or invalid authentication type: object properties: status: type: string enum: - error error: type: object properties: code: type: string enum: - MISSING_AUTH_CONTEXT - INVALID_API_KEY message: type: string meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "403": description: Forbidden - Insufficient permissions or scope violation content: application/json: schema: description: Forbidden - Insufficient permissions or scope violation type: object properties: status: type: string enum: - error error: type: object properties: code: type: string enum: - INSUFFICIENT_PERMISSIONS - SCOPE_VIOLATION message: type: string meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "404": description: Kitchen dispatch not found content: application/json: schema: description: Kitchen dispatch not found type: object properties: status: type: string enum: - error error: type: object properties: code: type: string enum: - RESOURCE_NOT_FOUND message: type: string meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "500": description: Internal Server Error content: application/json: schema: description: Internal Server Error type: object properties: status: type: string enum: - error error: type: object properties: code: type: string enum: - INTERNAL_SERVER_ERROR message: type: string meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs /api/v1/orders/{kitchenDispatchId}/sync: post: summary: Sync (atomic void + insert) lines on a kitchen dispatch tags: - Orders description: >- Atomically void a set of existing kitchen_dispatch_items AND insert a set of new ones in ONE transaction, ONE webhook fan-out. Cafe-mode "edit committed items" primitive. The earlier two-call shape (POST /void-batch + POST /append-to-dispatch in parallel) is replaced — clients describe the diff, the server applies it atomically. **Maps cleanly to actions:** - `+` on a committed line → `{ voids: [], inserts: [oneItem] }` - `−` on a committed line → `{ voids: [kdiId], inserts: [] }` - Variant edit → `{ voids: [originalKdiId], inserts: [newSpec] }` **Guards:** - Dispatch must exist, belong to the supplied tab + location, and be in an appendable state (`pending`/`accepted`/`in_preparation`/`ready_to_deliver`). - Tab must not be closed/abandoned. - Voids: any tab purchase rejects with 422 `TAB_HAS_PAYMENTS`. Already-aborted items pass through (idempotent, `wasAlreadyAborted: true` in the response). - Voided items not on this dispatch reject with 404 `KITCHEN_DISPATCH_ITEM_NOT_FOUND`. - Inserts: items + variants validated identically to `/orders/create`. **Side effects (one fan-out):** - `order.reversed` webhook (printer KORRBONG) — skipped when `suppressKorrbong: true` (cafe mode). - `order.updated` webhook with `changes.syncedLines` (KDS / cross-device refetch). - `tab.updated` webhook with `changes.kitchenDispatchSynced` (cashier tab refetch). - `inventory.updated` per ministock change. - Per-item `kitchen_dispatch_item.voided` platform_event for the audit trail. **Permissions:** 🟢 `inventory.create` requestBody: content: application/json: schema: type: object required: - tabId - locationId - order_channel - voids - inserts properties: tabId: type: string format: uuid description: UUID of the tab the dispatch belongs to (validated server-side) locationId: type: number order_channel: type: string enum: - ONLINE - QR - KIOSK - POS voids: type: array description: KDI UUIDs to set to item_state=aborted. Already-aborted ids pass through. items: type: string format: uuid inserts: type: array description: New items to insert into the dispatch (same shape as /orders/create items[]). items: type: object required: - id - quantity_cents - variants - comments properties: id: type: number quantity_cents: type: number minimum: 1 price_cents: type: number nullable: true variants: type: array items: type: object required: - id properties: id: type: number quantity_cents: type: number price_cents: type: number nullable: true comments: type: array items: type: string comments: type: array items: type: string tab_member_id: type: string format: uuid nullable: true coursing_order: type: number nullable: true upsell_source: type: string enum: - ai - manual nullable: true upsell_session_id: type: string format: uuid nullable: true upsell_recommendation_id: type: string format: uuid nullable: true suppressKorrbong: type: boolean description: When true, skip the order.reversed webhook so printer-functions does not print a KORRBONG. Cafe-mode locations pass this; merchant locations omit it. voidReasonCode: type: string enum: - staff_mistake - customer_change - wrong_make - quality_issue - out_of_stock - allergy - other description: Reason for the voids. Defaults to "customer_change". voidReasonNote: type: - string - "null" maxLength: 500 description: Required when voidReasonCode === "other". required: true parameters: - schema: type: string format: uuid in: path name: kitchenDispatchId required: true description: UUID of the kitchen dispatch to sync responses: "200": description: Lines synced successfully content: application/json: schema: description: Lines synced successfully type: object properties: status: type: string enum: - success data: type: object properties: kitchenDispatchId: type: string format: uuid tabId: type: string format: uuid inheritedItemState: type: string dispatchAborted: type: boolean voided: type: array items: type: object properties: kitchenDispatchItemId: type: string format: uuid previousItemState: type: - "null" - string newItemState: type: string enum: - aborted wasAlreadyAborted: type: boolean inserted: type: array items: type: object properties: kitchen_dispatch_item_id: type: string format: uuid item_id: type: number quantity: type: number quantity_cents: type: number price_cents: type: number status: type: string nullable: true meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/orders/{orderId}: get: summary: Get order by ID tags: - Orders description: >- Retrieve detailed information about a specific order including all items. Items are always included in the response for single order queries. **Permissions:** 🔵 `orders.read` parameters: - schema: type: string format: uuid in: path name: orderId required: true description: Order ID (kitchen_dispatch.uuid) responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: uuid: type: string format: uuid description: Unique order ID (kitchen_dispatch.uuid) locationId: type: number description: Location ID tabId: type: string format: uuid nullable: true description: Associated tab ID dailyOrderNumber: type: number nullable: true description: Daily order number for the location state: type: string enum: - not_sent - pending - accepted - in_preparation - ready_to_deliver - delivered - rejected - rejected_and_acknowledged - staged_awaiting_payment - scheduled - aborted description: Current order state orderType: type: string enum: - TAKEAWAY - OTC - QR - TABLE nullable: true description: Order type orderChannel: type: string enum: - ONLINE - QR - KIOSK - POS nullable: true description: Order channel createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp completedAt: type: string format: date-time nullable: true description: Completion timestamp tabType: type: string nullable: true description: Tab type (table, takeaway, etc.) storefrontQrCodeId: type: string nullable: true description: Table UUID (storefront QR code ID) - frontend maps to name tabMemberEmail: type: string format: email nullable: true description: Tab member email tabMemberName: type: string nullable: true description: Tab member name memberCount: type: number nullable: true description: Guest count on the tab (party size) totalPrice: type: number nullable: true description: Total price in cents itemCount: type: number nullable: true description: Number of items in order message: type: string nullable: true description: Order message/notes source: type: string nullable: true description: Order source items: type: array nullable: true items: type: object additionalProperties: true properties: uuid: type: string format: uuid description: Unique order item ID itemId: type: number nullable: true description: Inventory item ID title: type: string nullable: true description: Item title titlePrep: type: string nullable: true description: Kitchen prep title for KDS display - use instead of title if set quantity: type: number description: Quantity (integer) quantityCents: type: number description: Quantity in cents (e.g., 200 = 2x) price: type: number description: Total price in cents basePrice: type: number description: Base price in cents before discounts discount: type: number nullable: true description: Discount amount in cents status: type: string nullable: true description: Item status comments: {} variants: type: array nullable: true description: Variant/modification data for this item items: type: object properties: id: type: number description: Variant ID name: type: string description: Variant name price: type: number nullable: true description: Variant price in cents quantityCents: type: number nullable: true description: Quantity in cents priceCents: type: number nullable: true description: Price in cents modification_id: type: number description: Modification ID for completion tracking status: type: string nullable: true description: Modification status tabMemberId: type: string format: uuid nullable: true description: Tab member who owns this item createdAt: type: string format: date-time description: Creation timestamp servingCenterId: type: number nullable: true description: Serving center ID for this item printerGroupId: type: string format: uuid nullable: true description: Prep group (printer group) ID for this item tabMemberEmail: type: string format: email nullable: true description: Tab member email tabMemberName: type: string nullable: true description: Tab member name parentKitchenDispatchItemId: type: string format: uuid nullable: true description: Parent item UUID - if set, this is a child/modifier item. Use this to build hierarchy in frontend. itemState: type: string nullable: true description: Item-level state (not_sent, pending, accepted, in_preparation, ready_to_deliver, delivered, rejected) salesItemType: type: string nullable: true description: 'How the line was sold: "regular" or "surplus". Drives the KDS surplus badge.' surplusEntryId: type: number nullable: true description: item_ministock.id this surplus line was sold against (null for regular lines). isTakeaway: type: boolean description: Whether this specific line item is takeaway (independent of the tab-level tabType). Drives the KDS bag indicator. required: - uuid - quantity - quantityCents - price - basePrice - createdAt description: Order items (only when includeItems=true) notes: type: array nullable: true description: Tab notes attached to this order (only when includeNotes=true) items: type: object additionalProperties: true properties: uuid: type: string entityType: type: string entityId: type: string note: type: string locationId: type: number sortOrder: type: number createdByRetailerUserId: type: number nullable: true createdByName: type: string nullable: true updatedByRetailerUserId: type: number nullable: true updatedByName: type: string nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time events: type: array description: Order state change history items: type: object properties: event: type: string description: Event/state name created_at: type: string format: date-time description: Event timestamp required: - event - created_at desiredPickupTime: type: string format: date-time nullable: true description: Desired pickup time for scheduled orders storeCommitmentTimeout: type: string format: date-time nullable: true description: Store commitment timeout for acceptance required: - uuid - locationId - state - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/orders/{orderId}/advance-items: post: summary: Advance order item states tags: - Orders description: >- Advance item-level states for a kitchen dispatch (order). **Item-Level State Tracking:** - Each item independently tracks its own state - The overall order state is automatically derived as the earliest non-not_sent item state - Forward-only: items can only advance forward, never backward **Filtering Options:** - No filter: advance ALL items in the order - printerGroupId: advance only items in a specific prep group - coursingOrder: advance only items in a specific course **Valid Target States:** - pending, accepted, in_preparation, ready_to_deliver, delivered, rejected **Webhook:** - Emits order.updated with targetItemState and optional printerGroupId **Permissions:** 🟠 `inventory.update` requestBody: content: application/json: schema: type: object properties: state: type: string enum: - pending - accepted - in_preparation - ready_to_deliver - delivered - rejected description: Target state to advance items to printerGroupId: type: string format: uuid description: "Optional: advance only items in this prep group (printer group)" coursingOrder: type: integer description: "Optional: advance only items in this course" required: - state required: true parameters: - schema: type: string format: uuid in: path name: orderId required: true description: Order ID (kitchen_dispatch.uuid) responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: orderId: type: string format: uuid description: Order ID (kitchen_dispatch.uuid) targetState: type: string description: Target state items were advanced to itemsAdvanced: type: number description: Number of items that were advanced derivedOrderState: type: string description: Derived overall order state after advancement previousOrderState: type: string description: Order state before advancement heldItems: type: object additionalProperties: type: integer description: Counts of items targeted by the filter that were skipped because they are in a held state (not_sent, staged_awaiting_payment, waiting_for_merge). These items must exit their held state via the dedicated flow (coursing fire, payment confirmation, merge resolution) — bulk advance is intentionally a no-op for them. required: - orderId - targetState - itemsAdvanced - derivedOrderState - previousOrderState meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/orders/{orderId}/edit-items: patch: summary: Edit items on a staged order tags: - Orders description: >- Edit item quantities on a kitchen dispatch in `staged_awaiting_payment` state. Replaces the cancel→re-commit pattern previously used for storefront-web pay_upfront tab editing. **Per item:** - `quantityCents > 0` — UPDATE quantity, adjust ministock delta - `quantityCents === 0` — DELETE the item (and its children), restore ministock **Guards:** - Dispatch must be in `staged_awaiting_payment` state - No item on the dispatch may have `paid_amount > 0` - Ministock checked for quantity increases - Location access validated **Side effects:** - Tab total recalculated - Emits `order.updated` webhook **Permissions:** 🟠 `inventory.update` requestBody: content: application/json: schema: type: object properties: items: type: array minItems: 1 description: Items to edit. Set quantityCents to 0 to remove an item. items: type: object properties: kitchenDispatchItemId: type: string format: uuid description: UUID of the kitchen_dispatch_item to update quantityCents: type: number minimum: 0 description: New quantity in cents (e.g. 300 = 3x). 0 removes the item. required: - kitchenDispatchItemId - quantityCents required: - items required: true parameters: - schema: type: string format: uuid in: path name: orderId required: true description: Kitchen dispatch UUID to edit responses: "200": description: Items edited successfully content: application/json: schema: description: Items edited successfully type: object properties: status: type: string enum: - success data: type: object properties: orderId: type: string format: uuid updated: type: number description: Number of items updated removed: type: number description: Number of items removed meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/orders/{orderId}/items/{itemId}/status: post: summary: Update item status tags: - Orders description: Update the status of a kitchen dispatch item or modification. Requires staff authentication (JWT). User ID for audit trail is extracted from the auth token. requestBody: content: application/json: schema: type: object required: - status properties: status: oneOf: - type: string enum: - COMPLETED - UNAVAILABLE - type: "null" description: "Item status: COMPLETED, UNAVAILABLE, or null (reset)" modificationId: type: number description: If provided, update this modification (variant) instead of the item required: true parameters: - schema: type: string format: uuid in: path name: orderId required: true description: Kitchen dispatch (order) UUID - schema: type: string format: uuid in: path name: itemId required: true description: Kitchen dispatch item UUID responses: "200": description: Status updated successfully content: application/json: schema: description: Status updated successfully type: object properties: status: type: string enum: - success data: type: object properties: success: type: boolean itemId: type: string format: uuid status: oneOf: - type: string enum: - COMPLETED - UNAVAILABLE - type: "null" description: "Item status: COMPLETED, UNAVAILABLE, or null (reset)" meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/orders/{orderId}/items/{itemId}/status/logs: get: summary: Get item status logs tags: - Orders description: Get the status change history for a kitchen dispatch item parameters: - schema: type: string format: uuid in: path name: orderId required: true description: Kitchen dispatch (order) UUID - schema: type: string format: uuid in: path name: itemId required: true description: Kitchen dispatch item UUID responses: "200": description: Status logs retrieved successfully content: application/json: schema: description: Status logs retrieved successfully type: object properties: status: type: string enum: - success data: type: object properties: logs: type: array items: type: object properties: id: type: number description: Log entry ID itemId: type: string description: Item or modification ID status: oneOf: - type: string enum: - COMPLETED - UNAVAILABLE - type: "null" description: "Item status: COMPLETED, UNAVAILABLE, or null (reset)" isModification: type: boolean description: True if this was a modification update retailerUserId: type: string nullable: true description: User who made the change createdAt: type: string format: date-time description: When the status was changed updatedAt: type: string format: date-time nullable: true meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/orders/{orderId}/items/status: post: summary: Batch update item statuses tags: - Orders description: Batch update the status of multiple kitchen dispatch items and/or modifications. Requires staff authentication (JWT). User ID for audit trail is extracted from the auth token. requestBody: content: application/json: schema: type: object required: - updates properties: updates: type: array minItems: 1 description: Array of status updates items: type: object required: - id - status properties: id: type: string description: Item UUID or modification ID (as string) status: oneOf: - type: string enum: - COMPLETED - UNAVAILABLE - type: "null" description: "Item status: COMPLETED, UNAVAILABLE, or null (reset)" isModification: type: boolean description: True if this is a modification (variant), not an item required: true parameters: - schema: type: string format: uuid in: path name: orderId required: true description: Kitchen dispatch (order) UUID responses: "200": description: Batch update completed content: application/json: schema: description: Batch update completed type: object properties: status: type: string enum: - success data: type: object properties: success: type: boolean description: True if all updates succeeded updatedCount: type: number description: Number of successfully updated items failedItems: type: array items: type: object properties: id: type: string description: Item or modification ID isModification: type: boolean description: True if this is a modification (variant) error: type: string description: Error message description: Items that failed to update meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/orders/{orderId}/serving-center-state: post: summary: Update serving center state tags: - Orders description: >- Update the state of a specific serving center for an order. **Serving Center State Management:** - Each serving center independently tracks its state for each order - The overall order state is derived as the earliest (most backward) state across all serving centers - When all serving centers advance, the overall order state advances too **Valid Serving Center States (forward-only):** - pending → accepted → in_preparation → ready_to_deliver → delivered - rejected (terminal) **Constraints:** - Cannot set serving center state earlier than the overall order state - Forward-only transitions (can't go backward) **Webhook:** - Emits order.updated with servingCenterId and servingCenterState - Used by common-functions to send serving center SMS notifications **Replaces:** GraphQL mutation `updateServingCenterKitchenDispatchState` from Karma-Merchant-API **Permissions:** 🟠 `inventory.update` requestBody: content: application/json: schema: type: object properties: servingCenterId: type: number description: The serving center ID to update state for state: type: string enum: - pending - accepted - in_preparation - ready_to_deliver - delivered - rejected description: The new serving center state required: - servingCenterId - state required: true parameters: - schema: type: string format: uuid in: path name: orderId required: true description: Order ID (kitchen_dispatch.uuid) responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: orderId: type: string format: uuid description: Order ID (kitchen_dispatch.uuid) servingCenterId: type: number description: Serving center ID previousServingCenterState: type: string nullable: true description: Previous serving center state newServingCenterState: type: string description: New serving center state orderState: type: string description: Overall order state (may have advanced) orderStateChanged: type: boolean description: Whether the overall order state changed tabId: type: string format: uuid description: Associated tab ID updatedAt: type: string format: date-time description: Update timestamp updatedBy: type: number description: User ID who made the update required: - orderId - servingCenterId - newServingCenterState - orderState - orderStateChanged meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/orders/{orderId}/state: post: summary: Update order state tags: - Orders description: >- Update the state of an order (kitchen dispatch). **Event Sourcing:** - Inserts an event into kitchen_dispatch_events table - PostgreSQL trigger automatically updates kitchen_dispatches.latest_state - Emits order.updated webhook for real-time UI updates **Valid State Transitions:** - `not_sent` → pending, delivered, aborted - `pending` → accepted, rejected, aborted - `scheduled` → accepted, pending, aborted - `accepted` → in_preparation, ready_to_deliver, aborted - `in_preparation` → ready_to_deliver - `ready_to_deliver` → delivered - `rejected` → rejected_and_acknowledged - `aborted` → rejected_and_acknowledged (KDS bump on voided dispatch) - `staged_awaiting_payment` → pending, aborted **Terminal States (no transitions):** - delivered, rejected_and_acknowledged **Idempotency:** - Calling with current state returns 200 success (no-op) - Safe for retries in distributed systems **Permissions:** 🟠 `orders.update` requestBody: content: application/json: schema: type: object properties: state: type: string enum: - not_sent - pending - accepted - in_preparation - ready_to_deliver - delivered - rejected - rejected_and_acknowledged - staged_awaiting_payment - scheduled - aborted description: The new state to transition to required: - state required: true parameters: - schema: type: string format: uuid in: path name: orderId required: true description: Order ID (kitchen_dispatch.uuid) responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: orderId: type: string format: uuid description: Order ID (kitchen_dispatch.uuid) previousState: type: string description: State before the update newState: type: string description: State after the update tabId: type: string format: uuid description: Associated tab ID updatedAt: type: string format: date-time description: Update timestamp updatedBy: type: number description: User ID who made the update required: - orderId - previousState - newState - tabId meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/orders/append-to-dispatch: post: summary: Append items to an existing kitchen dispatch tags: - Orders description: >- Append items to an EXISTING kitchen_dispatch so they show up on the same KDS card the barista is already on. Used by the cafe-mode "edit committed items" flow — instead of a void creating a fresh ticket, the cashier voids the original line and appends the replacement against the same dispatch ID. **Guards:** - Dispatch must exist and belong to the supplied tab. - Dispatch state must be one of: `pending`, `accepted`, `in_preparation`, `ready_to_deliver`. Any other state (terminal, held, merged, staged) is rejected with 409 `DISPATCH_NOT_APPENDABLE`. - Tab must not be closed/abandoned. - Items + variants validated via the same path as `/orders/create`. **Side effects:** - New `kitchen_dispatch_items` inserted under the existing dispatch. - Ministock decremented for items that track it. - `order.items_added` webhook emitted (resource id = dispatch id). - `tab.updated` webhook emitted with `kitchenDispatchUpdated: { dispatchId, itemCount }`. **Permissions:** 🟢 `inventory.create` requestBody: content: application/json: schema: type: object required: - kitchenDispatchId - tabId - locationId - order_channel - items properties: kitchenDispatchId: type: string format: uuid description: UUID of the kitchen dispatch to append to tabId: type: string format: uuid description: UUID of the tab the dispatch belongs to (validated server-side) locationId: type: number description: Location ID (validated against dispatch) order_channel: type: string enum: - ONLINE - QR - KIOSK - POS description: Source channel (POS-only flows pass POS so price-override gating works) items: type: array minItems: 1 description: Items to append (same shape as /orders/create items) items: type: object required: - id - quantity_cents - variants - comments properties: id: type: number description: Inventory item ID quantity_cents: type: number minimum: 1 description: Quantity in cents (e.g., 250 = 2.5 items) price_cents: type: number nullable: true description: Price override in cents (POS only) variants: type: array description: Variant modifications (recursive) items: type: object required: - id properties: id: type: number quantity_cents: type: number default: 100 price_cents: type: number nullable: true comments: type: array items: type: string comments: type: array items: type: string tab_member_id: type: string format: uuid nullable: true description: "Optional: who this item is for (defaults to the dispatch tab_member_id)" coursing_order: type: number nullable: true description: Coursing level (kept on the appended row; not used to fire courses) upsell_source: type: string enum: - ai - manual nullable: true upsell_session_id: type: string format: uuid nullable: true upsell_recommendation_id: type: string format: uuid nullable: true required: true responses: "200": description: Items appended successfully content: application/json: schema: description: Items appended successfully type: object properties: status: type: string enum: - success data: type: object properties: kitchenDispatchId: type: string format: uuid tabId: type: string format: uuid dailyOrderNumber: type: number nullable: true inheritedItemState: type: string description: State the new items were stamped with (mirrors the dispatch latest_state) appendedItems: type: array items: type: object properties: kitchen_dispatch_item_id: type: string format: uuid item_id: type: number quantity: type: number quantity_cents: type: number price_cents: type: number status: type: string nullable: true meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/orders/create: post: summary: Create order tags: - Orders description: >- Unified Order Creation API - handles all order creation from POS, Storefront, Kiosk, and QR code orders **Permissions:** 🟢 `inventory.create` requestBody: content: application/json: schema: type: object required: - locationId - order_channel - order_type - order_destination - items properties: locationId: type: number description: Location ID order_channel: type: string enum: - ONLINE - QR - KIOSK - POS description: Source of the order order_type: type: string enum: - TAKEAWAY - OTC - QR - TABLE - SURPLUS description: Service model - TAKEAWAY (pickup, fresh prep), OTC (over the counter), QR (customer scanned QR code or POS table order), TABLE (waiter service), SURPLUS (pre-prepared discounted item, anytime pickup). order_destination: type: string enum: - QR - TAB - KD - NONE description: Where the order should be routed order_destination_id: type: string nullable: true format: uuid description: UUID of the destination (QR code, tab, or kitchen dispatch) tab_member: type: object nullable: true description: User identification for the order properties: id: type: number description: User ID (highest priority) email: type: string description: Email address phone: type: string description: Phone number identifier: type: string description: Device identifier items: type: array minItems: 1 description: Items to include in the order items: type: object required: - id - quantity_cents - variants - comments properties: id: type: number description: Inventory item ID quantity_cents: type: number minimum: 1 description: Quantity in cents (e.g., 250 = 2.5 items) price_cents: type: number nullable: true description: Price override in cents (POS only) variants: type: array description: Variant modifications items: type: object required: - id properties: id: type: number description: Variant ID quantity_cents: type: number description: "Quantity in cents (default: 100 = 1x)" default: 100 price_cents: type: number nullable: true description: Price override in cents (POS only) comments: type: array items: type: string description: Variant-specific comments comments: type: array items: type: string description: Special instructions upsell_source: type: string enum: - ai - manual nullable: true description: 'Source of upsell recommendation: "ai" for AI-powered recommendations, "manual" for merchant-configured upsells' upsell_session_id: type: string format: uuid nullable: true description: Links to upsell session for funnel analytics tracking upsell_recommendation_id: type: string format: uuid nullable: true description: ID of the specific recommendation that generated this item (from upsell_recommendations cache) gift_card_context: type: object nullable: true description: Gift card context for send-as-gift functionality properties: send_as_gift: type: boolean description: Whether the gift card is being sent as a gift recipient_name: type: string description: Gift recipient name recipient_email: type: string format: email description: Gift recipient email address personal_message: type: string description: Personal message for the gift card code: type: string description: Pre-assigned gift card code design_id: type: string description: UUID of the selected gift card design from gift_card_designs table vouchers: type: array items: type: string description: Voucher codes to apply desiredPickupTime: type: number nullable: true description: Unix timestamp for desired pickup time hold: type: boolean description: If true, order will be held (not_sent) and not sent to kitchen automatically required: true responses: "200": description: Order created successfully content: application/json: schema: description: Order created successfully type: object properties: status: type: string enum: - success data: type: object properties: kitchenDispatchId: type: string format: uuid dailyOrderNumber: type: number tabId: type: string format: uuid tabMemberId: type: string format: uuid items: type: array items: type: object properties: kitchen_dispatch_item_id: type: string format: uuid item_id: type: number quantity_cents: type: number description: Quantity in cents (100 = 1x) price_cents: type: number description: Total price for this item in cents variants: type: array description: Variants applied to this item items: type: object properties: id: type: number description: Variant ID quantity_cents: type: number description: Variant quantity in cents price_cents: type: number nullable: true description: Price override in cents status: type: string nullable: true description: Item status (null for new items) totalAmount: type: number discountAmount: type: number finalAmount: type: number appliedVouchers: type: array items: type: object properties: voucherCode: type: string discountAmountCents: type: number discountType: type: string invalidVouchers: type: array items: type: string estimatedReadyTime: type: number nullable: true paymentRequired: type: boolean description: True for INSTANT flow — guest must pay before kitchen receives items orderFlow: type: string description: Order flow used by backend (INSTANT, OPEN_TAB, etc.) kitchenDispatchItemIds: type: array items: type: string format: uuid description: Dispatch item UUIDs for payment processing minCommittedCoursingOrder: type: number nullable: true description: Lowest coursing_order across all just-committed KDIs (includes variant children resolved from inventory). null when nothing was coursed. meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/orders/stream: get: summary: Stream orders (SSE) tags: - Orders description: >- Stream orders using Server-Sent Events for real-time displays. **Use Case:** Kitchen Display Systems (KDS) and real-time dashboards where latency matters. **How It Works:** 1. PostgreSQL results are sent first (~100ms) - recent orders 2. BigQuery results follow when ready (~1-3 seconds) - historical orders 3. Completion event sent when all data is received **SSE Events:** - `postgres`: Orders from PostgreSQL (recent data) - `bigquery`: Orders from BigQuery (historical data) - `error`: Error from a specific source - `complete`: All data has been sent **Client Example:** ```javascript const eventSource = new EventSource('/api/v1/orders/stream?limit=1000') eventSource.addEventListener('postgres', (e) => { const { orders } = JSON.parse(e.data) // Show recent orders immediately! setOrders(prev => mergeAndSort([...prev, ...orders])) }) eventSource.addEventListener('bigquery', (e) => { const { orders } = JSON.parse(e.data) // Fill in historical orders setOrders(prev => mergeAndSort([...prev, ...orders])) }) eventSource.addEventListener('complete', () => { eventSource.close() }) ``` **Headers Required:** - `Accept: text/event-stream` - `X-Location-Id: {locationId}` **Permissions:** 🔵 `orders.read` parameters: - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: number minimum: 1 maximum: 1000 default: 50 in: query name: limit required: false description: Items per page (max 1000) - schema: type: boolean default: false in: query name: includeItems required: false description: Include order items in response. Items are returned FLAT with parentKitchenDispatchItemId for hierarchy building. - schema: type: boolean default: false in: query name: includeNotes required: false description: Include tab notes attached to each order (notes are polymorphic, keyed by tab uuid). Used by the KDS. - schema: type: boolean default: false in: query name: forcePostgres required: false description: Force PostgreSQL only (skip BigQuery). Use for KDS/real-time displays where state must be fresh. - schema: type: boolean default: false in: query name: excludeAbortedTabs required: false description: Hide KDs whose parent tab was force-closed (aborted). Use for the active KDS so staff don't see orphan tickets they cannot advance. Leave off for order history and audit views. - schema: type: number in: query name: dailyOrderNumber required: false description: Filter by daily order number - schema: anyOf: - type: string - type: array items: type: string in: query name: state required: false description: Filter by state(s) - schema: anyOf: - type: string - type: array items: type: string in: query name: tabType required: false description: Filter by tab type(s) - schema: type: string in: query name: tableId required: false description: Filter by table/QR code ID - schema: type: string in: query name: tabMemberEmail required: false description: Filter by tab member email (partial match) - schema: type: number in: query name: minPrice required: false description: Minimum total price in cents - schema: type: number in: query name: maxPrice required: false description: Maximum total price in cents - schema: anyOf: - type: string - type: array items: type: string in: query name: source required: false description: Filter by order source/channel (POS, ONLINE, QR, KIOSK) - schema: type: number in: query name: itemId required: false description: Filter orders containing a specific inventory item ID - schema: anyOf: - type: string - type: array items: type: string in: query name: printerGroupIds required: false description: Filter by prep group (printer group) IDs - schema: type: string format: date-time in: query name: startDate required: false description: "Filter orders created after this date (default: 24 hours ago)" - schema: type: string format: date-time in: query name: endDate required: false description: "Filter orders created before this date (default: now)" - schema: type: string enum: - created_at - daily_ordinal_number - updated_at default: created_at in: query name: sort required: false description: Field to sort by - schema: type: string enum: - asc - desc default: desc in: query name: order required: false description: Sort order responses: "200": description: Server-Sent Events stream (text/event-stream) content: application/json: schema: type: string description: Server-Sent Events stream (text/event-stream) "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/adyen-card-session: post: summary: Create Adyen zero-value auth session for self-service card linking tags: - Payment Methods - Loyalty description: >- Creates an Adyen checkout session with amount=0 and storePaymentMethodMode=enabled. The client initialises Adyen Drop-in with the returned `sessionId` and `sessionData`. After the user enters their card details, Adyen tokenises the card and issues a webhook. The resulting token is stored in `user_payment_methods` for future card-linked loyalty recognition. **Requires authenticated user session.** **Permissions:** 🟢 `payment-methods.create` requestBody: content: application/json: schema: type: object properties: returnUrl: type: string description: Return URL after Adyen Drop-in completes channel: type: string enum: - Web - iOS - Android description: Client channel — defaults to Web required: - returnUrl required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: sessionId: type: string description: Adyen session ID for Drop-in initialisation sessionData: type: string description: Adyen session data for Drop-in initialisation required: - sessionId - sessionData meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/link-payment-method: post: summary: Link payment card to user account tags: - Payment Methods - Loyalty description: >- Links a payment card (from a purchase) to a user account. This endpoint: 1. Extracts card data from the purchase 2. Finds or creates a user by email/phone 3. Links the card to the user for future recognition 4. Optionally enrolls the user in the loyalty program 5. Awards retroactive points for the triggering purchase **Use case**: After a guest makes a purchase and enters their email/phone, their card is linked so future purchases automatically earn loyalty points. **Permissions:** 🟢 `loyalty.create` requestBody: content: application/json: schema: type: object properties: purchaseIntentId: type: string description: Purchase intent ID containing card data email: type: string format: email description: User email (required if no phone) phone: type: string description: User phone number (required if no email) enrollInProgram: type: boolean description: Whether to also enroll in loyalty program locationId: type: number description: Location ID for enrollment (required if enrollInProgram) required: - purchaseIntentId required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: user: type: object properties: id: type: number description: User ID isNewUser: type: boolean description: Whether a new user was created required: - id - isNewUser paymentMethod: type: object properties: linked: type: boolean description: Whether card was successfully linked id: type: string format: uuid nullable: true description: Payment method UUID brand: type: string nullable: true description: Card brand last4: type: string nullable: true description: Last 4 digits required: - linked - id - brand - last4 enrollment: type: object nullable: true properties: enrolled: type: boolean description: Whether user was enrolled pointsAwarded: type: number nullable: true description: Retroactive points awarded newBalance: type: number nullable: true description: New points balance required: - user - paymentMethod - enrollment meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/staff-link-payment-method: post: summary: Staff-assisted card link with verbal consent tags: - Payment Methods - Loyalty - Staff description: >- Links a payment card to a user account using verbal consent captured by a staff member. This endpoint: 1. Extracts card data from the purchase 2. Links the card to the specified user with verbal consent 3. Records a consent event with the staff member's retailerUserId 4. Auto-enrolls the user in the location's loyalty program if not already enrolled 5. Awards retroactive points for the triggering purchase **Use case**: When a guest doesn't scan the QR code, staff can look up the user and link their card manually after verbal confirmation. **Permissions:** 🟢 `loyalty.create` requestBody: content: application/json: schema: type: object properties: purchaseIntentId: type: string description: Purchase intent ID containing card data userId: type: number description: User ID to link the card to locationId: type: number description: Location ID for enrollment context consentMethod: type: string enum: - verbal description: Must be verbal for staff-assisted flow retailerUserId: type: number description: Staff member who captured verbal consent required: - purchaseIntentId - userId - locationId - consentMethod - retailerUserId required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: cardLinked: type: boolean description: Whether card was successfully linked enrolled: type: boolean description: Whether user is enrolled in the loyalty program pointsAwarded: type: number description: Points awarded (welcome + retroactive) required: - cardLinked - enrolled - pointsAwarded meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/loyalty/user-search: get: summary: Search users by name, email, or phone (staff) tags: - Payment Methods - Loyalty - Staff description: >- Search for users matching a query string. Used by staff during the fallback enrollment flow. Query parameters: - **q**: Search term (minimum 2 characters) — matched against email, name, and phone - **purchaseIntentId**: Optional — if provided, the tab member for that purchase is auto-suggested Results are sorted by relevance. Maximum 10 results returned. **Permissions:** 🔵 `users.read` parameters: - schema: type: string minLength: 2 in: query name: q required: true description: Search term (name, email, or phone) - schema: type: string in: query name: purchaseIntentId required: false description: Optional purchase intent ID for tab member auto-suggest responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: users: type: array items: type: object properties: id: type: number description: User ID email: type: string nullable: true description: User email firstName: type: string nullable: true description: First name lastName: type: string nullable: true description: Last name phone: type: string nullable: true description: Phone number required: - id description: Matching users (max 10) autoSuggested: type: object nullable: true description: Tab member auto-suggested for the purchase (if purchaseIntentId provided) properties: userId: type: number firstName: type: string nullable: true lastName: type: string nullable: true email: type: string nullable: true autoSuggested: type: boolean enum: - true required: - users - autoSuggested meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/payment-methods: get: summary: List Adyen-configured payment methods for anonymous storefront guests tags: - Payment Methods description: Phase 39 — Returns Adyen-configured payment methods for a location so anonymous storefront-web guests can see Klarna / Swish / scheme rows on the v3 upfront flow. Authenticates via X-API-Key. Saved-method/enrichment fields are always empty/null (no user context). parameters: - schema: type: integer minimum: 1 in: query name: locationId required: true - schema: type: integer minimum: 0 in: query name: amountCents required: true - schema: type: string minLength: 3 maxLength: 3 in: query name: currencyCode required: true - schema: type: string minLength: 2 maxLength: 2 in: query name: countryCode required: false responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: paymentMethods: type: array items: type: object additionalProperties: true description: Always empty for anonymous callers (no user-bound saved methods). paymentMethodsResponse: type: object additionalProperties: true description: Adyen /paymentMethods response — used by storefront to render method rows (Klarna, Swish, scheme). clientKey: type: string nullable: true environment: type: string enum: - live - test defaultStoredMethodId: type: string nullable: true lastUsedStoredMethodId: type: string nullable: true lastUsedKind: type: string enum: - card - swish nullable: true savedSwish: type: object nullable: true additionalProperties: true required: - paymentMethods - paymentMethodsResponse - environment meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/purchases/{purchaseIntentId}/loyalty-status: get: summary: Get loyalty status for a purchase tags: - Payment Methods - Loyalty description: >- Returns the loyalty scenario after a purchase completes. Used by the frontend to determine what modal/action to show: - **POINTS_EARNED**: User is enrolled, points were awarded automatically - **ENROLLMENT_AVAILABLE**: Card is linked to user, but not enrolled at this location - **CARD_LINK_AVAILABLE**: Card is not linked to any user, prompt for email/phone - **NO_LOYALTY_PROGRAM**: Location has no loyalty program - **PROCESSING**: Still processing (retry later) **Permissions:** 🔵 `loyalty.read` parameters: - schema: type: string in: path name: purchaseIntentId required: true description: Purchase intent ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: loyaltyScenario: type: string enum: - POINTS_EARNED - ENROLLMENT_AVAILABLE - CARD_LINK_AVAILABLE - NO_LOYALTY_PROGRAM - PROCESSING description: The loyalty scenario based on card/user recognition pointsEarned: type: object nullable: true properties: points: type: number description: Points earned from this purchase newBalance: type: number description: New total points balance enrollmentOffer: type: object nullable: true properties: programId: type: number description: Loyalty program ID programName: type: string description: Loyalty program name potentialPoints: type: number description: Points user would earn by enrolling cardLinkOffer: type: object nullable: true properties: programId: type: number description: Loyalty program ID programName: type: string description: Loyalty program name potentialPoints: type: number description: Points user would earn by linking card brand: type: string nullable: true description: Card brand last4: type: string nullable: true description: Last 4 digits of card user: type: object nullable: true properties: id: type: number description: User ID email: type: string nullable: true description: User email location: type: object properties: id: type: number description: Location ID name: type: string description: Location name hasLoyaltyProgram: type: boolean description: Whether location has an active loyalty program required: - id - name - hasLoyaltyProgram required: - loyaltyScenario - pointsEarned - enrollmentOffer - cardLinkOffer - user - location meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/retailer/users/{userId}/payment-methods: get: summary: List payment methods for a specific user (staff view) tags: - Payment Methods description: >- Returns all saved payment methods for a specific user. Used by staff to view linked payment cards on the loyalty member detail page. This is a read-only view — staff cannot modify user payment methods through this endpoint. **Permissions:** 🔵 `users.read` parameters: - schema: type: string in: path name: userId required: true description: User ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: paymentMethods: type: array items: type: object properties: id: type: string format: uuid description: Payment method UUID nickname: type: string nullable: true description: User-defined nickname or auto-generated (e.g., "Visa ***4242") brand: type: string nullable: true description: Card brand (visa, mastercard, etc.) last4: type: string nullable: true description: Last 4 digits of card number expiryMonth: type: number nullable: true description: Card expiry month (1-12) expiryYear: type: number nullable: true description: Card expiry year (4 digits) isDefault: type: boolean description: Whether this is the default payment method isTokenized: type: boolean description: Whether this card is tokenized for recurring payments lastUsedAt: type: string format: date-time nullable: true description: Last time this payment method was used createdAt: type: string format: date-time description: When the payment method was saved additionalProperties: false description: List of saved payment methods defaultStoredMethodId: type: string nullable: true description: Adyen storedPaymentMethodId of the user's default card, or null lastUsedStoredMethodId: type: string nullable: true description: Adyen storedPaymentMethodId of the most recently used method, or null lastUsedKind: type: string enum: - card - swish nullable: true description: Kind of the most recently used active method, or null when no usage history savedSwish: type: object nullable: true properties: uuid: type: string format: uuid description: user_payment_methods.uuid for the kind=swish row payerAlias: type: string description: Verified phone alias in E.164 lastUsedAt: type: string format: date-time nullable: true required: - uuid - payerAlias - lastUsedAt required: - paymentMethods meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/users/me/payment-methods: get: summary: List saved payment methods tags: - Payment Methods description: |- Returns all saved payment methods for the authenticated user. Payment methods are sorted by: 1. Default payment method first 2. Most recently used 3. Creation date **Permissions:** 🔵 `payment-methods.read` responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: paymentMethods: type: array items: type: object properties: id: type: string format: uuid description: Payment method UUID nickname: type: string nullable: true description: User-defined nickname or auto-generated (e.g., "Visa ***4242") brand: type: string nullable: true description: Card brand (visa, mastercard, etc.) last4: type: string nullable: true description: Last 4 digits of card number expiryMonth: type: number nullable: true description: Card expiry month (1-12) expiryYear: type: number nullable: true description: Card expiry year (4 digits) isDefault: type: boolean description: Whether this is the default payment method isTokenized: type: boolean description: Whether this card is tokenized for recurring payments lastUsedAt: type: string format: date-time nullable: true description: Last time this payment method was used createdAt: type: string format: date-time description: When the payment method was saved additionalProperties: false description: List of saved payment methods defaultStoredMethodId: type: string nullable: true description: Adyen storedPaymentMethodId of the user's default card, or null lastUsedStoredMethodId: type: string nullable: true description: Adyen storedPaymentMethodId of the most recently used method, or null lastUsedKind: type: string enum: - card - swish nullable: true description: Kind of the most recently used active method, or null when no usage history savedSwish: type: object nullable: true properties: uuid: type: string format: uuid description: user_payment_methods.uuid for the kind=swish row payerAlias: type: string description: Verified phone alias in E.164 lastUsedAt: type: string format: date-time nullable: true required: - uuid - payerAlias - lastUsedAt required: - paymentMethods meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/users/me/payment-methods/{id}: delete: summary: Remove saved payment method tags: - Payment Methods description: >- Removes a saved payment method (soft delete). The card will no longer be recognized for loyalty purposes. **Permissions:** 🔴 `payment-methods.delete` parameters: - schema: type: string format: uuid in: path name: id required: true description: Payment method UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: message: type: string meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 patch: summary: Update payment method tags: - Payment Methods description: |- Updates a payment method's nickname. **Permissions:** 🟠 `payment-methods.update` requestBody: content: application/json: schema: type: object properties: nickname: type: string minLength: 1 maxLength: 100 description: Custom nickname for the card required: - nickname required: true parameters: - schema: type: string format: uuid in: path name: id required: true description: Payment method UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Payment method UUID nickname: type: string nullable: true description: User-defined nickname or auto-generated (e.g., "Visa ***4242") brand: type: string nullable: true description: Card brand (visa, mastercard, etc.) last4: type: string nullable: true description: Last 4 digits of card number expiryMonth: type: number nullable: true description: Card expiry month (1-12) expiryYear: type: number nullable: true description: Card expiry year (4 digits) isDefault: type: boolean description: Whether this is the default payment method isTokenized: type: boolean description: Whether this card is tokenized for recurring payments lastUsedAt: type: string format: date-time nullable: true description: Last time this payment method was used createdAt: type: string format: date-time description: When the payment method was saved additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/users/me/payment-methods/{id}/default: post: summary: Set default payment method tags: - Payment Methods description: |- Sets a payment method as the default for the authenticated user. **Permissions:** 🟠 `payment-methods.update` parameters: - schema: type: string format: uuid in: path name: id required: true description: Payment method UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: message: type: string meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/permissions: get: summary: List permissions tags: - Permissions description: |- List all permissions in the system with optional filters **Permissions:** 🔵 `permissions.read` parameters: - schema: type: string in: query name: category required: false description: Filter by category - schema: type: string in: query name: search required: false description: Search by key, name, or description - schema: type: number minimum: 1 default: 1 in: query name: page required: false - schema: type: number minimum: 1 maximum: 1000 default: 50 in: query name: limit required: false responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string example: success data: type: object properties: permissions: type: array items: type: object properties: id: type: number key: type: string example: inventory.read name: type: string example: Read Inventory description: type: string nullable: true category: type: string nullable: true example: Inventory createdAt: type: string format: date-time updatedAt: type: string format: date-time pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: summary: Create permission tags: - Permissions description: |- Create a new permission in the system INTERNAL: Only accessible to specific Karmeleon user IDs **Permissions:** 🟢 `permissions.create` requestBody: content: application/json: schema: type: object required: - key - name properties: key: type: string pattern: ^[a-z]+\.[a-z]+$ description: Dot notation permission key (e.g., resource.action) name: type: string description: type: string nullable: true category: type: string nullable: true required: true x-internal: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string example: success data: type: object properties: id: type: number key: type: string example: inventory.read name: type: string example: Read Inventory description: type: string nullable: true category: type: string nullable: true example: Inventory createdAt: type: string format: date-time updatedAt: type: string format: date-time meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/permissions/{id}: get: summary: Get permission tags: - Permissions description: |- Get a single permission by ID **Permissions:** 🔵 `permissions.read` parameters: - schema: type: number in: path name: id required: true description: Permission ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string example: success data: type: object properties: id: type: number key: type: string example: inventory.read name: type: string example: Read Inventory description: type: string nullable: true category: type: string nullable: true example: Inventory createdAt: type: string format: date-time updatedAt: type: string format: date-time meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: summary: Update permission tags: - Permissions description: |- Update an existing permission INTERNAL: Only accessible to specific Karmeleon user IDs Note: Cannot update permission key **Permissions:** 🟠 `permissions.update` requestBody: content: application/json: schema: type: object properties: name: type: string description: type: string nullable: true category: type: string nullable: true parameters: - schema: type: number in: path name: id required: true description: Permission ID x-internal: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string example: success data: type: object properties: id: type: number key: type: string example: inventory.read name: type: string example: Read Inventory description: type: string nullable: true category: type: string nullable: true example: Inventory createdAt: type: string format: date-time updatedAt: type: string format: date-time meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete permission tags: - Permissions description: |- Delete a permission INTERNAL: Only accessible to specific Karmeleon user IDs Note: Cannot delete permissions in use by roles or users **Permissions:** 🔴 `permissions.delete` parameters: - schema: type: number in: path name: id required: true description: Permission ID x-internal: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string example: success data: type: object properties: success: type: boolean id: type: number meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/permissions/matrix: get: summary: Get permission matrix tags: - Permissions description: |- Get all permissions grouped by resource for display in a matrix **Permissions:** 🔵 `permissions.read` responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string example: success data: type: object properties: resources: type: array items: type: object properties: resource: type: string permissions: type: array items: type: object properties: id: type: number key: type: string example: inventory.read name: type: string example: Read Inventory description: type: string nullable: true category: type: string nullable: true example: Inventory createdAt: type: string format: date-time updatedAt: type: string format: date-time meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/locations/{locationId}/print-settings: get: summary: Get location print settings tags: - Print Templates description: Get print settings for a specific location parameters: - schema: type: number in: path name: locationId required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string data: type: object properties: id: type: string format: uuid locationId: type: number fontSize: type: number nullable: true minimum: 1 maximum: 4 fontFamily: type: string nullable: true enum: - a - b lineSpacing: type: number nullable: true minimum: 1 maximum: 5 logoUrl: type: string nullable: true headerText: type: string nullable: true footerText: type: string nullable: true showLogo: type: boolean nullable: true printQrCode: type: boolean nullable: true printVatBreakdown: type: boolean nullable: true kitchenTicketBeep: type: boolean nullable: true language: type: string nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: summary: Save location print settings tags: - Print Templates description: Create or update print settings for a location requestBody: content: application/json: schema: type: object properties: fontSize: type: number minimum: 1 maximum: 4 nullable: true fontFamily: type: string enum: - a - b nullable: true lineSpacing: type: number minimum: 1 maximum: 5 nullable: true logoUrl: type: string nullable: true headerText: type: string nullable: true footerText: type: string nullable: true showLogo: type: boolean nullable: true printQrCode: type: boolean nullable: true printVatBreakdown: type: boolean nullable: true kitchenTicketBeep: type: boolean nullable: true language: type: string nullable: true parameters: - schema: type: number in: path name: locationId required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string data: type: object properties: id: type: string format: uuid locationId: type: number fontSize: type: number nullable: true minimum: 1 maximum: 4 fontFamily: type: string nullable: true enum: - a - b lineSpacing: type: number nullable: true minimum: 1 maximum: 5 logoUrl: type: string nullable: true headerText: type: string nullable: true footerText: type: string nullable: true showLogo: type: boolean nullable: true printQrCode: type: boolean nullable: true printVatBreakdown: type: boolean nullable: true kitchenTicketBeep: type: boolean nullable: true language: type: string nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete location print settings tags: - Print Templates description: Delete print settings for a location (reset to defaults) parameters: - schema: type: number in: path name: locationId required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string data: type: object properties: success: type: boolean locationId: type: number meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/locations/{locationId}/template-overrides: get: summary: List location template overrides tags: - Print Templates description: Get all template overrides for a specific location parameters: - schema: type: number in: path name: locationId required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string data: type: object properties: overrides: type: array items: type: object properties: id: type: string format: uuid locationId: type: number templateType: type: string enum: - kitchen_ticket - purchase_receipt - pre_check - order_confirmation - custom overrideScope: type: string enum: - full - section - settings customTemplateContent: type: object nullable: true additionalProperties: true sectionOverrides: type: object nullable: true additionalProperties: true settingsOverrides: type: object nullable: true additionalProperties: true isActive: type: boolean createdAt: type: string format: date-time updatedAt: type: string format: date-time meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/locations/{locationId}/template-overrides/{templateType}: get: summary: Get location template override tags: - Print Templates description: Get a specific template override for a location parameters: - schema: type: number in: path name: locationId required: true - schema: type: string enum: - kitchen_ticket - purchase_receipt - pre_check - order_confirmation - custom in: path name: templateType required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string data: type: object properties: id: type: string format: uuid locationId: type: number templateType: type: string enum: - kitchen_ticket - purchase_receipt - pre_check - order_confirmation - custom overrideScope: type: string enum: - full - section - settings customTemplateContent: type: object nullable: true additionalProperties: true sectionOverrides: type: object nullable: true additionalProperties: true settingsOverrides: type: object nullable: true additionalProperties: true isActive: type: boolean createdAt: type: string format: date-time updatedAt: type: string format: date-time meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: summary: Save location template override tags: - Print Templates description: Create or update a template override for a location requestBody: content: application/json: schema: type: object required: - overrideScope properties: overrideScope: type: string enum: - full - section - settings customTemplateContent: type: object nullable: true additionalProperties: true sectionOverrides: type: object nullable: true additionalProperties: true settingsOverrides: type: object nullable: true additionalProperties: true required: true parameters: - schema: type: number in: path name: locationId required: true - schema: type: string enum: - kitchen_ticket - purchase_receipt - pre_check - order_confirmation - custom in: path name: templateType required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string data: type: object properties: id: type: string format: uuid locationId: type: number templateType: type: string enum: - kitchen_ticket - purchase_receipt - pre_check - order_confirmation - custom overrideScope: type: string enum: - full - section - settings customTemplateContent: type: object nullable: true additionalProperties: true sectionOverrides: type: object nullable: true additionalProperties: true settingsOverrides: type: object nullable: true additionalProperties: true isActive: type: boolean createdAt: type: string format: date-time updatedAt: type: string format: date-time meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/print-templates: get: summary: List print templates tags: - Print Templates description: Get a list of all print templates with optional filtering parameters: - schema: type: string enum: - kitchen_ticket - purchase_receipt - pre_check - order_confirmation - custom in: query name: type required: false description: Filter by template type - schema: type: boolean in: query name: isActive required: false description: Filter by active status - schema: type: boolean in: query name: isSystem required: false description: Filter by system template status - schema: type: number minimum: 1 maximum: 100 default: 50 in: query name: limit required: false - schema: type: number minimum: 0 default: 0 in: query name: offset required: false responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string data: type: object properties: templates: type: array items: type: object properties: id: type: string format: uuid type: type: string enum: - kitchen_ticket - purchase_receipt - pre_check - order_confirmation - custom name: type: string description: type: string nullable: true version: type: number isActive: type: boolean isSystem: type: boolean content: type: object additionalProperties: true createdAt: type: string format: date-time updatedAt: type: string format: date-time createdBy: type: number nullable: true pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: summary: Create print template tags: - Print Templates description: Create a new custom print template requestBody: content: application/json: schema: type: object required: - type - name - content properties: type: type: string enum: - kitchen_ticket - purchase_receipt - pre_check - order_confirmation - custom name: type: string minLength: 1 maxLength: 100 description: type: string maxLength: 500 content: type: object additionalProperties: true required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string data: type: object properties: id: type: string format: uuid type: type: string enum: - kitchen_ticket - purchase_receipt - pre_check - order_confirmation - custom name: type: string description: type: string nullable: true version: type: number isActive: type: boolean isSystem: type: boolean content: type: object additionalProperties: true createdAt: type: string format: date-time updatedAt: type: string format: date-time createdBy: type: number nullable: true meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/print-templates/{id}: get: summary: Get print template tags: - Print Templates description: Get a single print template by ID parameters: - schema: type: string format: uuid in: path name: id required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string data: type: object properties: id: type: string format: uuid type: type: string enum: - kitchen_ticket - purchase_receipt - pre_check - order_confirmation - custom name: type: string description: type: string nullable: true version: type: number isActive: type: boolean isSystem: type: boolean content: type: object additionalProperties: true createdAt: type: string format: date-time updatedAt: type: string format: date-time createdBy: type: number nullable: true meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 patch: summary: Update print template tags: - Print Templates description: Update an existing custom print template (system templates cannot be modified) requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 100 description: type: string maxLength: 500 content: type: object additionalProperties: true isActive: type: boolean parameters: - schema: type: string format: uuid in: path name: id required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string data: type: object properties: id: type: string format: uuid type: type: string enum: - kitchen_ticket - purchase_receipt - pre_check - order_confirmation - custom name: type: string description: type: string nullable: true version: type: number isActive: type: boolean isSystem: type: boolean content: type: object additionalProperties: true createdAt: type: string format: date-time updatedAt: type: string format: date-time createdBy: type: number nullable: true meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete print template tags: - Print Templates description: Delete a custom print template (system templates cannot be deleted) parameters: - schema: type: string format: uuid in: path name: id required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string data: type: object properties: success: type: boolean id: type: string format: uuid meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/print-templates/type/{type}: get: summary: Get active print template by type tags: - Print Templates description: Get the currently active print template for a specific type parameters: - schema: type: string enum: - kitchen_ticket - purchase_receipt - pre_check - order_confirmation - custom in: path name: type required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string data: type: object properties: id: type: string format: uuid type: type: string enum: - kitchen_ticket - purchase_receipt - pre_check - order_confirmation - custom name: type: string description: type: string nullable: true version: type: number isActive: type: boolean isSystem: type: boolean content: type: object additionalProperties: true createdAt: type: string format: date-time updatedAt: type: string format: date-time createdBy: type: number nullable: true meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/template-overrides/{id}: patch: summary: Update location template override tags: - Print Templates description: Update an existing template override requestBody: content: application/json: schema: type: object properties: overrideScope: type: string enum: - full - section - settings customTemplateContent: type: object nullable: true additionalProperties: true sectionOverrides: type: object nullable: true additionalProperties: true settingsOverrides: type: object nullable: true additionalProperties: true isActive: type: boolean parameters: - schema: type: string format: uuid in: path name: id required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string data: type: object properties: id: type: string format: uuid locationId: type: number templateType: type: string enum: - kitchen_ticket - purchase_receipt - pre_check - order_confirmation - custom overrideScope: type: string enum: - full - section - settings customTemplateContent: type: object nullable: true additionalProperties: true sectionOverrides: type: object nullable: true additionalProperties: true settingsOverrides: type: object nullable: true additionalProperties: true isActive: type: boolean createdAt: type: string format: date-time updatedAt: type: string format: date-time meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete location template override tags: - Print Templates description: Delete a template override for a location parameters: - schema: type: string format: uuid in: path name: id required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string data: type: object properties: success: type: boolean id: type: string format: uuid meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/print-jobs/custom: post: tags: - Printers description: >- Create a custom print job with Star Micronics Markdown. This endpoint allows sending raw Star Micronics Markdown content directly to a printer. Use this for custom receipt formats, promotional prints, or testing. **Star Micronics Markdown Reference:** - `[C]` - Center alignment - `[L]` - Left alignment - `[R]` - Right alignment - `[D:1]` to `[D:4]` - Font size (1 is normal, 4 is largest) - `[CUT]` - Cut paper - `---` - Horizontal line **Example:** ``` [C][D:2]Welcome to Karma! [C][D:1]--- [L]Your custom content here [CUT] ``` requestBody: content: application/json: schema: type: object properties: printerGroupId: type: string format: uuid description: ID of the printer group to print to content: type: string description: Star Micronics Markdown content to print minLength: 1 maxLength: 10000 required: - printerGroupId - content required: true responses: "201": description: Custom print job created successfully content: application/json: schema: description: Custom print job created successfully type: object properties: status: type: string enum: - success data: type: object properties: correlationId: type: string format: uuid description: Unique correlation ID for tracking the print job type: type: string enum: - custom printerGroupId: type: string format: uuid description: ID of the printer group the job was sent to required: - correlationId - type - printerGroupId meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/print-jobs/kiosk-order-confirmation: post: summary: Print kiosk order confirmation tags: - Printers description: >- Print an order confirmation slip on the kiosk's printer. Guest-facing endpoint fired by the storefront confirmation page. Resolves the purchase's kitchen dispatch and prints an order confirmation (order number + QR code) to the specified printer group. **Flow:** 1. Resolves `purchaseIntentId` → kitchen dispatch ID via the purchase's order. 2. Validates the printer group belongs to the location. 3. Sends an `order_confirmation` print job to the group. requestBody: content: application/json: schema: type: object properties: purchaseIntentId: type: string format: uuid description: Purchase intent ID from the storefront payment flow printerId: type: string format: uuid description: Printer ID from qrCode.printer — resolved to its group server-side required: - purchaseIntentId - printerId required: true responses: "201": description: Print job created successfully content: application/json: schema: description: Print job created successfully type: object properties: status: type: string enum: - success data: type: object properties: correlationId: type: string format: uuid type: type: string enum: - order_confirmation printerGroupId: type: string format: uuid required: - correlationId - type - printerGroupId meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/print-jobs/kiosk-receipt: post: summary: Print kiosk receipt tags: - Printers description: >- Auto-print an order receipt on a kiosk's attached printer. Fired by the storefront on the confirmation page when the kiosk's QR code has a `printer` UUID configured. The storefront only knows the `purchaseIntentId`; this endpoint resolves the underlying purchase plus the printer's group and issues a targeted print job so only the kiosk's printer produces the receipt. **Flow:** 1. Resolves `purchase.id` from the given `purchaseIntentId` (scoped to the location). 2. Resolves the printer's group (scoped to the location) so the wrong kiosk can't be targeted. 3. Publishes a `purchase_receipt` print job with `targetPrinterId` set so only that physical printer picks it up. 4. Returns the correlation ID for tracking. requestBody: content: application/json: schema: type: object properties: purchaseIntentId: type: string format: uuid description: Purchase intent ID from the storefront payment flow printerId: type: string format: uuid description: UUID of the kiosk-attached printer (read from qrCode.printer) required: - purchaseIntentId - printerId required: true responses: "201": description: Print job created successfully content: application/json: schema: description: Print job created successfully type: object properties: status: type: string enum: - success data: type: object properties: correlationId: type: string format: uuid type: type: string enum: - purchase_receipt printerGroupId: type: string format: uuid printerId: type: string format: uuid purchaseId: type: string required: - correlationId - type - printerGroupId - printerId - purchaseId meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/print-jobs/kitchen-ticket-reprint: post: tags: - Printers description: >- Reprint a kitchen ticket for an existing order. This endpoint reprints kitchen tickets for a kitchen dispatch (order). Items are automatically routed to the correct printer groups based on printer group item configuration. **Important:** Unlike the original print, this is a reprint operation that bypasses idempotency checks. Each call will create new print jobs. **Flow:** 1. Fetches kitchen dispatch with items, events, and comments 2. Fetches printer groups for the location 3. Routes items to correct printer groups based on printer_group_items configuration 4. Sends print jobs for each printer group with relevant items requestBody: content: application/json: schema: type: object properties: kitchenDispatchId: type: string format: uuid description: ID of the kitchen dispatch (order) to reprint tickets for required: - kitchenDispatchId required: true responses: "201": description: Kitchen ticket reprint jobs created successfully content: application/json: schema: description: Kitchen ticket reprint jobs created successfully type: object properties: status: type: string enum: - success data: type: object properties: correlationId: type: string format: uuid description: Unique correlation ID for tracking the print jobs type: type: string enum: - kitchen_ticket kitchenDispatchId: type: string format: uuid description: ID of the kitchen dispatch message: type: string description: Status message indicating the print request was submitted required: - correlationId - type - kitchenDispatchId meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/print-jobs/order-confirmation: post: tags: - Printers description: >- Create an order confirmation print job. This endpoint prints an order confirmation slip for a kitchen dispatch (order). Used by POS when "print order confirmation" is enabled. **Order Confirmation Contents:** - Order number (daily ordinal) - Order date/time - QR code for order tracking - Table name (if applicable) **Flow:** 1. Validates printer group belongs to location 2. Fetches kitchen dispatch data 3. Sends print job to printer service via Pub/Sub requestBody: content: application/json: schema: type: object properties: printerGroupId: type: string format: uuid description: ID of the printer group to print to kitchenDispatchId: type: string format: uuid description: ID of the kitchen dispatch (order) to print confirmation for required: - printerGroupId - kitchenDispatchId required: true responses: "201": description: Order confirmation print job created successfully content: application/json: schema: description: Order confirmation print job created successfully type: object properties: status: type: string enum: - success data: type: object properties: correlationId: type: string format: uuid description: Unique correlation ID for tracking the print job type: type: string enum: - order_confirmation printerGroupId: type: string format: uuid description: ID of the printer group the job was sent to kitchenDispatchId: type: string format: uuid description: ID of the kitchen dispatch required: - correlationId - type - printerGroupId - kitchenDispatchId meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/print-jobs/pre-check: post: tags: - Printers description: >- Create a pre-check (pro forma bill) print job for a table. This endpoint prints a pre-check showing all items on a table's tab with totals and a payment QR code. Used when guests want to see their bill before paying. **Flow:** 1. Validates printer group belongs to location 2. Fetches tab with all items, prices, and table info 3. Generates QR code URL for payment 4. Sends complete data to printer service via Pub/Sub requestBody: content: application/json: schema: type: object properties: printerGroupId: type: string format: uuid description: ID of the printer group to print to tabId: type: string format: uuid description: ID of the tab (QR code/table) to print pre-check for selectedKdiItemIds: type: array items: type: string format: uuid description: Optional kitchen_dispatch_items UUIDs to restrict the pro forma to. When set, only these items (and their children) are printed; otherwise the entire unpaid tab is printed. required: - printerGroupId - tabId required: true responses: "201": description: Pre-check print job created successfully content: application/json: schema: description: Pre-check print job created successfully type: object properties: status: type: string enum: - success data: type: object properties: correlationId: type: string format: uuid description: Unique correlation ID for tracking the print job type: type: string enum: - pre_check printerGroupId: type: string format: uuid description: ID of the printer group the job was sent to tabId: type: string format: uuid description: ID of the tab required: - correlationId - type - printerGroupId - tabId meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/print-jobs/purchase-receipt: post: tags: - Printers description: >- Create a purchase receipt print job. This endpoint fetches the purchase data from the database and sends a complete print job to the printer service via Pub/Sub. The printer service will render the receipt using the appropriate template. **Flow:** 1. Validates printer group belongs to location 2. Fetches purchase data with line items, VAT breakdown, and location info 3. Sends complete data to printer service via Pub/Sub 4. Returns correlation ID for tracking requestBody: content: application/json: schema: type: object properties: printerGroupId: type: string format: uuid description: ID of the printer group to print to purchaseId: type: string description: ID of the purchase to print receipt for required: - printerGroupId - purchaseId required: true responses: "201": description: Print job created successfully content: application/json: schema: description: Print job created successfully type: object properties: status: type: string enum: - success data: type: object properties: correlationId: type: string format: uuid description: Unique correlation ID for tracking the print job type: type: string enum: - purchase_receipt - kitchen_ticket - pre_check - order_confirmation - test_print - custom description: Type of print job printerGroupId: type: string format: uuid description: ID of the printer group the job was sent to purchaseId: type: string description: ID of the purchase (for purchase_receipt type) required: - correlationId - type - printerGroupId meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/print-jobs/refund-receipt: post: tags: - Printers description: >- Create a refund receipt print job. This endpoint prints a refund receipt for a completed purchase refund. Used from the merchant dashboard when staff want to print a physical refund receipt. **Flow:** 1. Validates printer group belongs to location 2. Sends refund receipt print job to printer service via Pub/Sub 3. Printer service fetches refund data and renders the receipt 4. Returns correlation ID for tracking requestBody: content: application/json: schema: type: object properties: printerGroupId: type: string format: uuid description: ID of the printer group to print to purchaseRefundId: type: string description: ID of the purchase refund to print receipt for required: - printerGroupId - purchaseRefundId required: true responses: "201": description: Refund receipt print job created successfully content: application/json: schema: description: Refund receipt print job created successfully type: object properties: status: type: string enum: - success data: type: object properties: correlationId: type: string format: uuid description: Unique correlation ID for tracking the print job type: type: string enum: - refund_receipt printerGroupId: type: string format: uuid description: ID of the printer group the job was sent to purchaseRefundId: type: string description: ID of the purchase refund required: - correlationId - type - printerGroupId - purchaseRefundId meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/print-jobs/terminal-receipt: post: tags: - Printers description: >- Print a receipt on the Adyen terminal. Called from the POS receipt dialog after payment completes. The actual printing is fire-and-forget — this returns 202 immediately. **Flow:** 1. Proxies request to payment-service 2. Payment-service fetches receipt data and sends print command to terminal 3. Returns 202 Accepted immediately requestBody: content: application/json: schema: type: object properties: purchaseIntentId: type: string format: uuid description: ID of the purchase intent to print receipt for terminalId: type: string format: uuid description: ID of the Adyen terminal to print on required: - purchaseIntentId - terminalId required: true responses: "202": description: Terminal receipt print initiated content: application/json: schema: description: Terminal receipt print initiated type: object properties: status: type: string enum: - success data: type: object properties: type: type: string enum: - terminal_receipt purchaseIntentId: type: string format: uuid terminalId: type: string format: uuid required: - type - purchaseIntentId - terminalId meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/print-jobs/test: post: tags: - Printers description: >- Create a test print job. This endpoint sends a test page to the specified printer group. Use this to verify printer connectivity and configuration. **Test Page Contents:** - Service name and timestamp - Custom message (if provided) - Printer configuration info requestBody: content: application/json: schema: type: object properties: printerGroupId: type: string format: uuid description: ID of the printer group to send test print to message: type: string description: Optional custom message to include on the test print maxLength: 500 required: - printerGroupId required: true responses: "201": description: Test print job created successfully content: application/json: schema: description: Test print job created successfully type: object properties: status: type: string enum: - success data: type: object properties: correlationId: type: string format: uuid description: Unique correlation ID for tracking the print job type: type: string enum: - test_print printerGroupId: type: string format: uuid description: ID of the printer group the job was sent to required: - correlationId - type - printerGroupId meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/printer-dashboard: get: tags: - Printers description: Get printer dashboard with summary stats and recent activity parameters: - schema: type: integer in: query name: locationId required: false description: Location ID. If not provided, uses X-Location-Id header or default location. responses: "200": description: Successfully retrieved printer dashboard content: application/json: schema: description: Successfully retrieved printer dashboard type: object properties: status: type: string enum: - success data: type: object properties: summary: type: object properties: activePrinters: type: integer pendingJobs: type: integer printingJobs: type: integer failedJobs24h: type: integer completedJobs24h: type: integer required: - activePrinters - pendingJobs - printingJobs - failedJobs24h - completedJobs24h recentActivity: type: array items: type: object properties: jobId: type: string jobNumber: type: string createdAt: type: string format: date-time completedAt: type: string format: date-time nullable: true printer: type: object nullable: true properties: id: type: string name: type: string macAddress: type: string nullable: true isOnline: type: boolean printerGroup: type: object properties: id: type: string name: type: string type: type: string locationId: type: integer locationName: type: string currentStatus: type: string statusChangedAt: type: string format: date-time retries: type: integer duration: type: integer nullable: true contentType: type: string contentPreview: type: string nullable: true errorMessage: type: string nullable: true errorCode: type: string nullable: true kitchenDispatch: type: object nullable: true properties: orderNumber: type: string tableNumber: type: string nullable: true totalAmount: type: number nullable: true itemCount: type: integer required: - summary - recentActivity meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/printer-groups: get: tags: - Printers description: List all printer groups (prep groups) for a location with their printers parameters: - schema: type: integer in: query name: locationId required: false description: Location ID to filter printer groups. If not provided, uses X-Location-Id header or default location. responses: "200": description: Successfully retrieved printer groups content: application/json: schema: description: Successfully retrieved printer groups type: object properties: status: type: string enum: - success data: type: object properties: printerGroups: type: array items: type: object properties: id: type: string format: uuid description: Unique printer group identifier name: type: string nullable: true description: Name of the printer group type: type: string nullable: true description: Type of the printer group color: type: string nullable: true description: "Color for the printer group (hex code, e.g. #FF5733). Null renders as gray." defaultItemState: type: string nullable: true enum: - pending - accepted - ready_to_deliver - null description: Default item state for orders routed to this prep group. Null means use location/system default. locationId: type: integer description: Location ID where the printer group is configured createdAt: type: string format: date-time description: When the printer group was created updatedAt: type: string format: date-time description: When the printer group was last updated metaData: type: object nullable: true properties: fontSize: type: string nullable: true description: Font size setting for receipts logotypeUrl: type: string nullable: true description: URL of the logo to print on receipts message: type: string nullable: true description: Custom message to print on receipts displayPayQRProforma: type: boolean nullable: true description: Whether to display payment QR code on proforma displayOrderQRReciept: type: boolean nullable: true description: Whether to display order QR code on receipt printers: type: array items: type: object properties: id: type: string format: uuid description: Unique printer identifier printerGroupId: type: string format: uuid nullable: true description: ID of the primary printer group this printer belongs to (null if unassigned). Kept for backward compatibility. printerGroupIds: type: array items: type: string format: uuid description: Primary prep group memberships — the printer prints these groups' items via the flow engine. secondaryPrinterGroupIds: type: array items: type: string format: uuid description: Secondary ("ride-along") prep group memberships. Items from these groups print on this printer additively in smaller font when the printer fires its primary print. Never triggers a print on its own. locationId: type: integer description: Location ID where the printer is installed name: type: string nullable: true description: Name of the printer (from printer group) type: type: string enum: - tsp654 - tsp100 - any - v400m - v400cplus - s1f2 - mcprint3 nullable: true description: Hardware type of the printer status: type: string nullable: true description: Last reported status code from the printer state: type: string enum: - online - offline description: Current state of the printer (online if both printer is online and group is published) idle: type: boolean nullable: true description: Whether the printer is currently idle (not processing jobs) cloudPrntUrl: type: string format: uri description: CloudPRNT polling URL to configure on the physical printer example: https://printer.karma.life/api/cloudprnt/location/123/printer/abc-def-ghi createdAt: type: string format: date-time description: When the printer was created updatedAt: type: string format: date-time description: When the printer was last updated required: - id - locationId - state - cloudPrntUrl - createdAt - updatedAt description: Printers in this group with CloudPRNT URLs required: - id - locationId - createdAt - updatedAt - printers total: type: integer description: Total number of printer groups required: - printerGroups - total meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: tags: - Printers description: Create a new printer group (prep group) requestBody: content: application/json: schema: type: object properties: name: type: string description: Name for the printer group type: type: string enum: - bar - kitchen - all - none description: Type of the printer group (defaults to kitchen) color: type: string nullable: true description: "Color for the printer group (hex code, e.g. #FF5733)" defaultItemState: type: string nullable: true enum: - pending - accepted - ready_to_deliver - null description: Default item state for orders routed to this prep group. Null means use location/system default. required: - name required: true parameters: - schema: type: integer in: query name: locationId required: false description: Location ID. If not provided, uses X-Location-Id header or default location. responses: "201": description: Successfully created printer group content: application/json: schema: description: Successfully created printer group type: object properties: status: type: string enum: - success data: type: object properties: printerGroup: type: object properties: id: type: string format: uuid description: Unique printer group identifier name: type: string nullable: true description: Name of the printer group type: type: string nullable: true description: Type of the printer group color: type: string nullable: true description: "Color for the printer group (hex code, e.g. #FF5733). Null renders as gray." defaultItemState: type: string nullable: true enum: - pending - accepted - ready_to_deliver - null description: Default item state for orders routed to this prep group. Null means use location/system default. locationId: type: integer description: Location ID where the printer group is configured createdAt: type: string format: date-time description: When the printer group was created updatedAt: type: string format: date-time description: When the printer group was last updated metaData: type: object nullable: true properties: fontSize: type: string nullable: true description: Font size setting for receipts logotypeUrl: type: string nullable: true description: URL of the logo to print on receipts message: type: string nullable: true description: Custom message to print on receipts displayPayQRProforma: type: boolean nullable: true description: Whether to display payment QR code on proforma displayOrderQRReciept: type: boolean nullable: true description: Whether to display order QR code on receipt printers: type: array items: type: object properties: id: type: string format: uuid description: Unique printer identifier printerGroupId: type: string format: uuid nullable: true description: ID of the primary printer group this printer belongs to (null if unassigned). Kept for backward compatibility. printerGroupIds: type: array items: type: string format: uuid description: Primary prep group memberships — the printer prints these groups' items via the flow engine. secondaryPrinterGroupIds: type: array items: type: string format: uuid description: Secondary ("ride-along") prep group memberships. Items from these groups print on this printer additively in smaller font when the printer fires its primary print. Never triggers a print on its own. locationId: type: integer description: Location ID where the printer is installed name: type: string nullable: true description: Name of the printer (from printer group) type: type: string enum: - tsp654 - tsp100 - any - v400m - v400cplus - s1f2 - mcprint3 nullable: true description: Hardware type of the printer status: type: string nullable: true description: Last reported status code from the printer state: type: string enum: - online - offline description: Current state of the printer (online if both printer is online and group is published) idle: type: boolean nullable: true description: Whether the printer is currently idle (not processing jobs) cloudPrntUrl: type: string format: uri description: CloudPRNT polling URL to configure on the physical printer example: https://printer.karma.life/api/cloudprnt/location/123/printer/abc-def-ghi createdAt: type: string format: date-time description: When the printer was created updatedAt: type: string format: date-time description: When the printer was last updated required: - id - locationId - state - cloudPrntUrl - createdAt - updatedAt description: Printers in this group with CloudPRNT URLs required: - id - locationId - createdAt - updatedAt - printers required: - printerGroup meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/printer-groups/{printerGroupId}: get: tags: - Printers description: Get a printer group by ID with its printers and CloudPRNT URLs parameters: - schema: type: string format: uuid in: path name: printerGroupId required: true description: Printer Group UUID responses: "200": description: Successfully retrieved printer group content: application/json: schema: description: Successfully retrieved printer group type: object properties: status: type: string enum: - success data: type: object properties: printerGroup: type: object properties: id: type: string format: uuid description: Unique printer group identifier name: type: string nullable: true description: Name of the printer group type: type: string nullable: true description: Type of the printer group color: type: string nullable: true description: "Color for the printer group (hex code, e.g. #FF5733). Null renders as gray." defaultItemState: type: string nullable: true enum: - pending - accepted - ready_to_deliver - null description: Default item state for orders routed to this prep group. Null means use location/system default. locationId: type: integer description: Location ID where the printer group is configured createdAt: type: string format: date-time description: When the printer group was created updatedAt: type: string format: date-time description: When the printer group was last updated metaData: type: object nullable: true properties: fontSize: type: string nullable: true description: Font size setting for receipts logotypeUrl: type: string nullable: true description: URL of the logo to print on receipts message: type: string nullable: true description: Custom message to print on receipts displayPayQRProforma: type: boolean nullable: true description: Whether to display payment QR code on proforma displayOrderQRReciept: type: boolean nullable: true description: Whether to display order QR code on receipt printers: type: array items: type: object properties: id: type: string format: uuid description: Unique printer identifier printerGroupId: type: string format: uuid nullable: true description: ID of the primary printer group this printer belongs to (null if unassigned). Kept for backward compatibility. printerGroupIds: type: array items: type: string format: uuid description: Primary prep group memberships — the printer prints these groups' items via the flow engine. secondaryPrinterGroupIds: type: array items: type: string format: uuid description: Secondary ("ride-along") prep group memberships. Items from these groups print on this printer additively in smaller font when the printer fires its primary print. Never triggers a print on its own. locationId: type: integer description: Location ID where the printer is installed name: type: string nullable: true description: Name of the printer (from printer group) type: type: string enum: - tsp654 - tsp100 - any - v400m - v400cplus - s1f2 - mcprint3 nullable: true description: Hardware type of the printer status: type: string nullable: true description: Last reported status code from the printer state: type: string enum: - online - offline description: Current state of the printer (online if both printer is online and group is published) idle: type: boolean nullable: true description: Whether the printer is currently idle (not processing jobs) cloudPrntUrl: type: string format: uri description: CloudPRNT polling URL to configure on the physical printer example: https://printer.karma.life/api/cloudprnt/location/123/printer/abc-def-ghi createdAt: type: string format: date-time description: When the printer was created updatedAt: type: string format: date-time description: When the printer was last updated required: - id - locationId - state - cloudPrntUrl - createdAt - updatedAt description: Printers in this group with CloudPRNT URLs required: - id - locationId - createdAt - updatedAt - printers required: - printerGroup meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: tags: - Printers description: Update a printer group (prep group) name requestBody: content: application/json: schema: type: object properties: name: type: string description: New name for the printer group color: type: string nullable: true description: "Color for the printer group (hex code, e.g. #FF5733). Set to null to remove." defaultItemState: type: string nullable: true enum: - pending - accepted - ready_to_deliver - null description: Default item state for orders routed to this prep group. Set to null to use location/system default. parameters: - schema: type: string format: uuid in: path name: printerGroupId required: true description: Printer Group UUID responses: "200": description: Successfully updated printer group content: application/json: schema: description: Successfully updated printer group type: object properties: status: type: string enum: - success data: type: object properties: printerGroup: type: object properties: id: type: string format: uuid description: Unique printer group identifier name: type: string nullable: true description: Name of the printer group type: type: string nullable: true description: Type of the printer group color: type: string nullable: true description: "Color for the printer group (hex code, e.g. #FF5733). Null renders as gray." defaultItemState: type: string nullable: true enum: - pending - accepted - ready_to_deliver - null description: Default item state for orders routed to this prep group. Null means use location/system default. locationId: type: integer description: Location ID where the printer group is configured createdAt: type: string format: date-time description: When the printer group was created updatedAt: type: string format: date-time description: When the printer group was last updated metaData: type: object nullable: true properties: fontSize: type: string nullable: true description: Font size setting for receipts logotypeUrl: type: string nullable: true description: URL of the logo to print on receipts message: type: string nullable: true description: Custom message to print on receipts displayPayQRProforma: type: boolean nullable: true description: Whether to display payment QR code on proforma displayOrderQRReciept: type: boolean nullable: true description: Whether to display order QR code on receipt printers: type: array items: type: object properties: id: type: string format: uuid description: Unique printer identifier printerGroupId: type: string format: uuid nullable: true description: ID of the primary printer group this printer belongs to (null if unassigned). Kept for backward compatibility. printerGroupIds: type: array items: type: string format: uuid description: Primary prep group memberships — the printer prints these groups' items via the flow engine. secondaryPrinterGroupIds: type: array items: type: string format: uuid description: Secondary ("ride-along") prep group memberships. Items from these groups print on this printer additively in smaller font when the printer fires its primary print. Never triggers a print on its own. locationId: type: integer description: Location ID where the printer is installed name: type: string nullable: true description: Name of the printer (from printer group) type: type: string enum: - tsp654 - tsp100 - any - v400m - v400cplus - s1f2 - mcprint3 nullable: true description: Hardware type of the printer status: type: string nullable: true description: Last reported status code from the printer state: type: string enum: - online - offline description: Current state of the printer (online if both printer is online and group is published) idle: type: boolean nullable: true description: Whether the printer is currently idle (not processing jobs) cloudPrntUrl: type: string format: uri description: CloudPRNT polling URL to configure on the physical printer example: https://printer.karma.life/api/cloudprnt/location/123/printer/abc-def-ghi createdAt: type: string format: date-time description: When the printer was created updatedAt: type: string format: date-time description: When the printer was last updated required: - id - locationId - state - cloudPrntUrl - createdAt - updatedAt description: Printers in this group with CloudPRNT URLs required: - id - locationId - createdAt - updatedAt - printers required: - printerGroup meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: tags: - Printers description: Delete a printer group (prep group) and all its printers parameters: - schema: type: string format: uuid in: path name: printerGroupId required: true description: Printer Group UUID responses: "200": description: Successfully deleted printer group content: application/json: schema: description: Successfully deleted printer group type: object properties: status: type: string enum: - success data: type: object properties: deleted: type: boolean required: - deleted meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/printer-groups/{printerGroupId}/events: get: tags: - Printers description: List events for a printer group parameters: - schema: type: integer minimum: 1 maximum: 1000 default: 100 in: query name: limit required: false description: Number of events to return - schema: type: integer minimum: 0 default: 0 in: query name: offset required: false description: Offset for pagination - schema: type: string format: uuid in: path name: printerGroupId required: true description: Printer Group UUID responses: "200": description: Successfully retrieved printer events content: application/json: schema: description: Successfully retrieved printer events type: object properties: status: type: string enum: - success data: type: object properties: events: type: array items: type: object properties: id: type: string format: uuid printerId: type: string nullable: true printerGroupId: type: string format: uuid printerGroupName: type: string nullable: true eventType: type: string timestamp: type: string format: date-time metadata: type: object nullable: true totalCount: type: integer required: - events - totalCount meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/printer-groups/{printerGroupId}/jobs: get: tags: - Printers description: List print jobs for a printer group parameters: - schema: type: integer minimum: 1 maximum: 1000 default: 100 in: query name: limit required: false description: Number of jobs to return - schema: type: integer minimum: 0 default: 0 in: query name: offset required: false description: Offset for pagination - schema: type: string format: date-time in: query name: startDate required: false description: Filter jobs created at or after this ISO 8601 datetime - schema: type: string format: date-time in: query name: endDate required: false description: Filter jobs created at or before this ISO 8601 datetime - schema: type: string format: uuid in: path name: printerGroupId required: true description: Printer Group UUID responses: "200": description: Successfully retrieved print jobs content: application/json: schema: description: Successfully retrieved print jobs type: object properties: status: type: string enum: - success data: type: object properties: jobs: type: array items: type: object properties: id: type: string format: uuid printerGroupId: type: string format: uuid printerGroupName: type: string nullable: true claimedByPrinter: type: string nullable: true status: type: string retries: type: integer metadata: type: object nullable: true content: nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time totalCount: type: integer required: - jobs - totalCount meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/printer-groups/{printerGroupId}/jobs/{jobId}: get: tags: - Printers description: Get a single print job by ID with its events timeline parameters: - schema: type: string format: uuid in: path name: printerGroupId required: true description: Printer Group UUID - schema: type: string format: uuid in: path name: jobId required: true description: Print Job UUID responses: "200": description: Successfully retrieved print job with events content: application/json: schema: description: Successfully retrieved print job with events type: object properties: status: type: string enum: - success data: type: object properties: job: type: object properties: id: type: string format: uuid printerGroupId: type: string format: uuid printerGroupName: type: string nullable: true claimedByPrinter: type: string nullable: true status: type: string retries: type: integer metadata: type: object nullable: true content: nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time events: type: array items: type: object properties: id: type: string format: uuid eventType: type: string timestamp: type: string format: date-time printerId: type: string nullable: true metadata: type: object nullable: true required: - job meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/printer-groups/{printerGroupId}/printers: post: tags: - Printers description: Add a printer to an existing printer group requestBody: content: application/json: schema: type: object properties: type: type: string enum: - tsp654 - tsp100 - any - v400m - v400cplus - s1f2 - mcprint3 description: Hardware type of the printer terminalId: type: string format: uuid description: Terminal ID for terminal printers (v400m, v400cplus, s1f2) required: - type required: true parameters: - schema: type: string format: uuid in: path name: printerGroupId required: true description: Printer Group UUID responses: "201": description: Successfully added printer to group content: application/json: schema: description: Successfully added printer to group type: object properties: status: type: string enum: - success data: type: object properties: printer: type: object properties: id: type: string format: uuid description: Unique printer identifier printerGroupId: type: string format: uuid nullable: true description: ID of the primary printer group this printer belongs to (null if unassigned). Kept for backward compatibility. printerGroupIds: type: array items: type: string format: uuid description: Primary prep group memberships — the printer prints these groups' items via the flow engine. secondaryPrinterGroupIds: type: array items: type: string format: uuid description: Secondary ("ride-along") prep group memberships. Items from these groups print on this printer additively in smaller font when the printer fires its primary print. Never triggers a print on its own. locationId: type: integer description: Location ID where the printer is installed name: type: string nullable: true description: Name of the printer (from printer group) type: type: string enum: - tsp654 - tsp100 - any - v400m - v400cplus - s1f2 - mcprint3 nullable: true description: Hardware type of the printer status: type: string nullable: true description: Last reported status code from the printer state: type: string enum: - online - offline description: Current state of the printer (online if both printer is online and group is published) idle: type: boolean nullable: true description: Whether the printer is currently idle (not processing jobs) cloudPrntUrl: type: string format: uri description: CloudPRNT polling URL to configure on the physical printer example: https://printer.karma.life/api/cloudprnt/location/123/printer/abc-def-ghi createdAt: type: string format: date-time description: When the printer was created updatedAt: type: string format: date-time description: When the printer was last updated required: - id - locationId - state - cloudPrntUrl - createdAt - updatedAt required: - printer meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/printers: get: tags: - Printers description: List all printers for a location with CloudPRNT URLs parameters: - schema: type: integer in: query name: locationId required: false description: Location ID to filter printers. If not provided, uses X-Location-Id header or default location. responses: "200": description: Successfully retrieved printers content: application/json: schema: description: Successfully retrieved printers type: object properties: status: type: string enum: - success data: type: object properties: printers: type: array items: type: object properties: id: type: string format: uuid description: Unique printer identifier printerGroupId: type: string format: uuid nullable: true description: ID of the primary printer group this printer belongs to (null if unassigned). Kept for backward compatibility. printerGroupIds: type: array items: type: string format: uuid description: Primary prep group memberships — the printer prints these groups' items via the flow engine. secondaryPrinterGroupIds: type: array items: type: string format: uuid description: Secondary ("ride-along") prep group memberships. Items from these groups print on this printer additively in smaller font when the printer fires its primary print. Never triggers a print on its own. locationId: type: integer description: Location ID where the printer is installed name: type: string nullable: true description: Name of the printer (from printer group) type: type: string enum: - tsp654 - tsp100 - any - v400m - v400cplus - s1f2 - mcprint3 nullable: true description: Hardware type of the printer status: type: string nullable: true description: Last reported status code from the printer state: type: string enum: - online - offline description: Current state of the printer (online if both printer is online and group is published) idle: type: boolean nullable: true description: Whether the printer is currently idle (not processing jobs) cloudPrntUrl: type: string format: uri description: CloudPRNT polling URL to configure on the physical printer example: https://printer.karma.life/api/cloudprnt/location/123/printer/abc-def-ghi createdAt: type: string format: date-time description: When the printer was created updatedAt: type: string format: date-time description: When the printer was last updated required: - id - locationId - state - cloudPrntUrl - createdAt - updatedAt total: type: integer description: Total number of printers required: - printers - total meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: tags: - Printers description: Create a new printer (optionally assign to a printer group) requestBody: content: application/json: schema: type: object properties: printerGroupId: type: string format: uuid nullable: true description: Optional ID of the printer group to add this printer to. If not provided, printer will be created without a group (storage state). type: type: string enum: - tsp654 - tsp100 - any - v400m - v400cplus - s1f2 - mcprint3 description: Printer hardware model/type name: type: string description: Optional name for the printer terminalId: type: string format: uuid description: Terminal ID for terminal printers (v400m, v400cplus, s1f2) required: - type required: true parameters: - schema: type: integer in: query name: locationId required: false description: Location ID. If not provided, uses X-Location-Id header or default location. responses: "201": description: Successfully created printer content: application/json: schema: description: Successfully created printer type: object properties: status: type: string enum: - success data: type: object properties: printer: type: object properties: id: type: string format: uuid description: Unique printer identifier printerGroupId: type: string format: uuid nullable: true description: ID of the primary printer group this printer belongs to (null if unassigned). Kept for backward compatibility. printerGroupIds: type: array items: type: string format: uuid description: Primary prep group memberships — the printer prints these groups' items via the flow engine. secondaryPrinterGroupIds: type: array items: type: string format: uuid description: Secondary ("ride-along") prep group memberships. Items from these groups print on this printer additively in smaller font when the printer fires its primary print. Never triggers a print on its own. locationId: type: integer description: Location ID where the printer is installed name: type: string nullable: true description: Name of the printer (from printer group) type: type: string enum: - tsp654 - tsp100 - any - v400m - v400cplus - s1f2 - mcprint3 nullable: true description: Hardware type of the printer status: type: string nullable: true description: Last reported status code from the printer state: type: string enum: - online - offline description: Current state of the printer (online if both printer is online and group is published) idle: type: boolean nullable: true description: Whether the printer is currently idle (not processing jobs) cloudPrntUrl: type: string format: uri description: CloudPRNT polling URL to configure on the physical printer example: https://printer.karma.life/api/cloudprnt/location/123/printer/abc-def-ghi createdAt: type: string format: date-time description: When the printer was created updatedAt: type: string format: date-time description: When the printer was last updated required: - id - locationId - state - cloudPrntUrl - createdAt - updatedAt required: - printer meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/printers/{printerId}: get: tags: - Printers description: Get a single printer by ID parameters: - schema: type: integer in: query name: locationId required: false description: Location ID for access verification. If not provided, uses X-Location-Id header or default location. - schema: type: string format: uuid in: path name: printerId required: true description: Printer UUID responses: "200": description: Successfully retrieved printer content: application/json: schema: description: Successfully retrieved printer type: object properties: status: type: string enum: - success data: type: object properties: printer: type: object properties: id: type: string format: uuid description: Unique printer identifier printerGroupId: type: string format: uuid nullable: true description: ID of the primary printer group this printer belongs to (null if unassigned). Kept for backward compatibility. printerGroupIds: type: array items: type: string format: uuid description: Primary prep group memberships — the printer prints these groups' items via the flow engine. secondaryPrinterGroupIds: type: array items: type: string format: uuid description: Secondary ("ride-along") prep group memberships. Items from these groups print on this printer additively in smaller font when the printer fires its primary print. Never triggers a print on its own. locationId: type: integer description: Location ID where the printer is installed name: type: string nullable: true description: Name of the printer (from printer group) type: type: string enum: - tsp654 - tsp100 - any - v400m - v400cplus - s1f2 - mcprint3 nullable: true description: Hardware type of the printer status: type: string nullable: true description: Last reported status code from the printer state: type: string enum: - online - offline description: Current state of the printer (online if both printer is online and group is published) idle: type: boolean nullable: true description: Whether the printer is currently idle (not processing jobs) cloudPrntUrl: type: string format: uri description: CloudPRNT polling URL to configure on the physical printer example: https://printer.karma.life/api/cloudprnt/location/123/printer/abc-def-ghi createdAt: type: string format: date-time description: When the printer was created updatedAt: type: string format: date-time description: When the printer was last updated required: - id - locationId - state - cloudPrntUrl - createdAt - updatedAt required: - printer meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: tags: - Printers description: Update a printer (e.g. reassign to a different printer group) requestBody: content: application/json: schema: type: object properties: name: type: string description: New name for the printer type: type: string enum: - tsp654 - tsp100 - any - v400m - v400cplus - s1f2 - mcprint3 description: Printer hardware model/type printerGroupId: type: string format: uuid description: ID of the printer group to assign this printer to parameters: - schema: type: string format: uuid in: path name: printerId required: true description: Printer UUID responses: "200": description: Successfully updated printer content: application/json: schema: description: Successfully updated printer type: object properties: status: type: string enum: - success data: type: object properties: printer: type: object properties: id: type: string format: uuid description: Unique printer identifier printerGroupId: type: string format: uuid nullable: true description: ID of the primary printer group this printer belongs to (null if unassigned). Kept for backward compatibility. printerGroupIds: type: array items: type: string format: uuid description: Primary prep group memberships — the printer prints these groups' items via the flow engine. secondaryPrinterGroupIds: type: array items: type: string format: uuid description: Secondary ("ride-along") prep group memberships. Items from these groups print on this printer additively in smaller font when the printer fires its primary print. Never triggers a print on its own. locationId: type: integer description: Location ID where the printer is installed name: type: string nullable: true description: Name of the printer (from printer group) type: type: string enum: - tsp654 - tsp100 - any - v400m - v400cplus - s1f2 - mcprint3 nullable: true description: Hardware type of the printer status: type: string nullable: true description: Last reported status code from the printer state: type: string enum: - online - offline description: Current state of the printer (online if both printer is online and group is published) idle: type: boolean nullable: true description: Whether the printer is currently idle (not processing jobs) cloudPrntUrl: type: string format: uri description: CloudPRNT polling URL to configure on the physical printer example: https://printer.karma.life/api/cloudprnt/location/123/printer/abc-def-ghi createdAt: type: string format: date-time description: When the printer was created updatedAt: type: string format: date-time description: When the printer was last updated required: - id - locationId - state - cloudPrntUrl - createdAt - updatedAt required: - printer meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: tags: - Printers description: Delete a printer parameters: - schema: type: string format: uuid in: path name: printerId required: true description: Printer UUID responses: "200": description: Successfully deleted printer content: application/json: schema: description: Successfully deleted printer type: object properties: status: type: string enum: - success data: type: object properties: deleted: type: boolean required: - deleted meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/printers/{printerId}/events: get: tags: - Printers description: List events for a single printer (online, offline, created, deleted) parameters: - schema: type: integer minimum: 1 maximum: 1000 default: 100 in: query name: limit required: false description: Number of events to return - schema: type: integer minimum: 0 default: 0 in: query name: offset required: false description: Offset for pagination - schema: type: string format: uuid in: path name: printerId required: true description: Printer UUID responses: "200": description: Successfully retrieved printer events content: application/json: schema: description: Successfully retrieved printer events type: object properties: status: type: string enum: - success data: type: object properties: events: type: array items: type: object properties: id: type: string format: uuid printerId: type: string nullable: true printerGroupId: type: string format: uuid printerGroupName: type: string nullable: true eventType: type: string timestamp: type: string format: date-time metadata: type: object nullable: true totalCount: type: integer required: - events - totalCount meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/printers/{printerId}/groups: put: tags: - Printers description: Set which printer groups a printer belongs to (replaces all memberships) requestBody: content: application/json: schema: type: object properties: printerGroupIds: type: array items: type: string format: uuid description: Primary prep group UUIDs the printer prints for. Empty array removes all primary memberships. secondaryPrinterGroupIds: type: array items: type: string format: uuid description: Optional. Prep groups this printer is a ride-along ("secondary") member of. When the printer fires a primary print, items from these groups in the same kitchen dispatch are appended in smaller font. Secondary memberships never trigger a print on their own and may not overlap with primary IDs. required: - printerGroupIds required: true parameters: - schema: type: string format: uuid in: path name: printerId required: true description: Printer UUID responses: "200": description: Successfully set printer groups content: application/json: schema: description: Successfully set printer groups type: object properties: status: type: string enum: - success data: type: object properties: printerId: type: string format: uuid printerGroupIds: type: array items: type: string format: uuid secondaryPrinterGroupIds: type: array items: type: string format: uuid required: - printerId - printerGroupIds meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/printers/{printerId}/groups/{printerGroupId}: delete: tags: - Printers description: Remove a printer from a specific printer group parameters: - schema: type: string format: uuid in: path name: printerId required: true description: Printer UUID - schema: type: string format: uuid in: path name: printerGroupId required: true description: Printer Group UUID to remove the printer from responses: "200": description: Successfully removed printer from group content: application/json: schema: description: Successfully removed printer from group type: object properties: status: type: string enum: - success data: type: object properties: removed: type: boolean required: - removed meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/public/orders/create: post: tags: - Public description: Creates an order at a location. A new tab is opened per call unless an existing destination is provided. Optionally associate the order with a guest via user_id, email, or phone. requestBody: content: application/json: schema: type: object required: - location_id - items properties: location_id: type: number description: Location to place the order at ordering_member: type: object description: Optional guest identification. Provide one of user_id, email, or phone. If omitted, an anonymous guest is created for this order. properties: user_id: type: number description: Karma user ID email: type: string format: email description: Guest email phone: type: string description: Guest phone number name: type: string description: Display name for new guests items: type: array minItems: 1 items: type: object required: - id - quantity_cents properties: id: type: number description: Inventory item ID quantity_cents: type: number minimum: 1 description: Quantity in cents (100 = 1 unit, 50 = half) variants: type: array description: Optional variants to apply (e.g. size, milk type) items: type: object required: - id properties: id: type: number description: Variant ID quantity_cents: type: number description: Quantity in cents (100 = 1 unit, 50 = 0.5). Defaults to 100. price_cents: type: number description: Optional price override in cents. Defaults to the item's configured price. coursing_order: type: number description: Optional coursing order (0 = send immediately). Omit to use default. vouchers: type: array description: Optional voucher codes to apply to the order items: type: string order_destination: type: string enum: - NONE - TAB - QR - KD default: NONE description: Where to attach the order. NONE creates a fresh tab. TAB/QR/KD attach to an existing destination identified by order_destination_id. order_destination_id: type: string description: UUID of the destination tab, QR code, or kitchen dispatch. Required when order_destination is not NONE. order_type: type: string enum: - TAKEAWAY - OTC - TABLE default: OTC description: Fulfillment type. Defaults to OTC (over the counter). required: true responses: "201": description: Order created content: application/json: schema: description: Order created type: object properties: status: type: string enum: - success data: type: object properties: orderId: type: string description: Kitchen dispatch UUID tabId: type: string description: Tab UUID totalAmountCents: type: number description: Order total in cents "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/purchase/lookup-session/{sessionId}: get: tags: - Purchases description: >- Look up purchase intent ID by Adyen session ID (stored in psp_request_ref). Used when Adyen redirects back with sessionId but no purchaseIntentId in URL. **Permissions:** 🔵 `purchases.read` parameters: - schema: type: number in: query name: locationId required: true description: Location ID for permission validation - schema: type: string in: path name: sessionId required: true description: Adyen session ID (psp_request_ref) responses: "200": description: Purchase intent found for session content: application/json: schema: description: Purchase intent found for session type: object properties: status: type: string enum: - success data: type: object properties: purchaseIntentId: type: string format: uuid description: Purchase intent UUID locationId: type: number description: Location ID meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/purchases: get: tags: - Purchases description: List purchases with automatic BigQuery routing for historical data parameters: - schema: type: number in: query name: locationId required: true description: Location ID to filter purchases (required for permissions) - schema: type: string format: date-time in: query name: startDate required: false description: Start date for date range filter (ISO 8601) - schema: type: string format: date-time in: query name: endDate required: false description: End date for date range filter (ISO 8601) - schema: type: number in: query name: userId required: false description: Filter by user ID - schema: type: number in: query name: minAmount required: false description: Minimum amount in cents - schema: type: number in: query name: maxAmount required: false description: Maximum amount in cents - schema: type: number in: query name: minRefundedAmount required: false description: Minimum refunded amount in cents - schema: type: number in: query name: maxRefundedAmount required: false description: Maximum refunded amount in cents - schema: type: string in: query name: paymentMethod required: false description: Filter by payment method - schema: type: string in: query name: status required: false description: Filter by payment status - schema: type: string in: query name: customerEmail required: false description: Filter by customer email (partial match) - schema: type: number in: query name: itemId required: false description: Filter purchases containing a specific inventory item ID - schema: type: string in: query name: tableId required: false description: Filter by table/storefront QR code UUID - schema: type: string format: uuid in: query name: tabId required: false description: Filter by tab UUID - schema: type: string in: query name: tabType required: false description: "Filter by tab type (comma-separated: takeaway, over_the_counter, table)" - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number for pagination - schema: type: number minimum: 1 maximum: 1000 default: 50 in: query name: limit required: false description: Number of results per page (max 1000) responses: "200": description: Purchases retrieved successfully content: application/json: schema: description: Purchases retrieved successfully type: object properties: status: type: string enum: - success data: type: object properties: purchases: type: array items: type: object properties: id: type: number description: Purchase ID locationId: type: number description: Location ID userId: type: number nullable: true description: User ID who made the purchase amount: type: number description: Total amount in cents currency: type: string description: Currency code (e.g., SEK, EUR) paymentMethod: type: string nullable: true description: Payment method used paymentProvider: type: string nullable: true description: Payment provider (e.g., stripe, adyen) status: type: string description: Payment status (pending, completed, failed, etc.) createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp tabId: type: string nullable: true format: uuid description: Tab ID if part of a tab lineItems: type: array items: type: object properties: id: type: number description: Line item ID inventoryItemId: type: number description: Inventory item ID quantityCents: type: number description: Quantity in cents (100 = 1x) unitPriceCents: type: number description: Price per unit in cents totalPriceCents: type: number description: Total price in cents title: type: string description: Item title category: type: string nullable: true description: Item category channel: type: string nullable: true description: Order channel (POS, KIOSK, QR, ONLINE, TAKEAWAY, MOVE, MERGE, SPLIT, SYSTEM) enum: - POS - KIOSK - QR - ONLINE - TAKEAWAY - MOVE - MERGE - SPLIT - SYSTEM isTakeaway: type: boolean description: Whether this specific item is takeaway (can differ from the tab-level tabType) createdAt: type: string format: date-time description: Creation timestamp description: Purchased items metadata: type: object nullable: true description: Additional metadata additionalProperties: true pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/purchases/{id}: get: tags: - Purchases description: Get a single purchase by ID parameters: - schema: type: number in: query name: locationId required: true description: Location ID for permission validation - schema: type: string in: path name: id required: true description: Purchase ID responses: "200": description: Purchase retrieved successfully content: application/json: schema: description: Purchase retrieved successfully type: object properties: status: type: string enum: - success data: type: object properties: purchase: type: object properties: id: type: number description: Purchase ID locationId: type: number description: Location ID userId: type: number nullable: true description: User ID who made the purchase amount: type: number description: Total amount in cents currency: type: string description: Currency code (e.g., SEK, EUR) paymentMethod: type: string nullable: true description: Payment method used paymentProvider: type: string nullable: true description: Payment provider (e.g., stripe, adyen) status: type: string description: Payment status (pending, completed, failed, etc.) createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp tabId: type: string nullable: true format: uuid description: Tab ID if part of a tab lineItems: type: array items: type: object properties: id: type: number description: Line item ID inventoryItemId: type: number description: Inventory item ID quantityCents: type: number description: Quantity in cents (100 = 1x) unitPriceCents: type: number description: Price per unit in cents totalPriceCents: type: number description: Total price in cents title: type: string description: Item title category: type: string nullable: true description: Item category channel: type: string nullable: true description: Order channel (POS, KIOSK, QR, ONLINE, TAKEAWAY, MOVE, MERGE, SPLIT, SYSTEM) enum: - POS - KIOSK - QR - ONLINE - TAKEAWAY - MOVE - MERGE - SPLIT - SYSTEM isTakeaway: type: boolean description: Whether this specific item is takeaway (can differ from the tab-level tabType) createdAt: type: string format: date-time description: Creation timestamp description: Purchased items metadata: type: object nullable: true description: Additional metadata additionalProperties: true meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/purchases/{purchaseIntentId}/cash-register/fetch: post: tags: - Purchases description: >- Fetch cash register info from cash-register service for a purchase that has a receipt ID but missing other cash register fields. Used to backfill data for older purchases. **Permissions:** ⚪ `purchases.write` parameters: - schema: type: number in: query name: locationId required: true description: Location ID for permission validation - schema: type: string format: uuid in: path name: purchaseIntentId required: true description: Purchase intent UUID responses: "200": description: Cash register info fetched successfully content: application/json: schema: description: Cash register info fetched successfully type: object properties: status: type: string enum: - success data: type: object properties: purchaseIntentId: type: string format: uuid cashRegister: type: object nullable: true description: Cash register receipt data (SKV required fields). Null if not registered with cash register. properties: receiptNumber: type: number description: Löpnummer - running receipt number from unbroken ascending series registerId: type: string description: Kassabeteckning - cash register designation/ID controlUnit: type: string nullable: true description: Kontrollenhetens tillverkningsnummer - control unit serial number meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/purchases/{purchaseIntentId}/cash-register/register: post: tags: - Purchases description: >- Register a purchase with the cash register service (efterregistrering). Used for purchases that were not registered at the time of payment. Location must have an active cash register configuration. **Permissions:** ⚪ `purchases.write` parameters: - schema: type: number in: query name: locationId required: true description: Location ID for permission validation - schema: type: string format: uuid in: path name: purchaseIntentId required: true description: Purchase intent UUID responses: "200": description: Purchase registered with cash register successfully content: application/json: schema: description: Purchase registered with cash register successfully type: object properties: status: type: string enum: - success data: type: object properties: purchaseIntentId: type: string format: uuid cashRegister: type: object nullable: true description: Cash register receipt data (SKV required fields). Null if not registered with cash register. properties: receiptNumber: type: number description: Löpnummer - running receipt number from unbroken ascending series registerId: type: string description: Kassabeteckning - cash register designation/ID controlUnit: type: string nullable: true description: Kontrollenhetens tillverkningsnummer - control unit serial number meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/purchases/{purchaseIntentId}/connect-customer: post: tags: - Purchases description: Connect a customer to a purchase by email. Optionally enroll in loyalty and award retroactive points. requestBody: content: application/json: schema: type: object required: - email properties: email: type: string format: email description: Customer email address (used to find or create user) name: type: string description: Customer name (optional, used to update user profile) phone: type: string description: Customer phone number (optional) enrollInLoyalty: type: boolean description: Enroll customer in location loyalty program and award retroactive points required: true parameters: - schema: type: number in: query name: locationId required: true description: Location ID for permission validation - schema: type: string format: uuid in: path name: purchaseIntentId required: true description: Purchase intent UUID responses: "200": description: Customer connected successfully content: application/json: schema: description: Customer connected successfully type: object properties: status: type: string enum: - success data: type: object properties: success: type: boolean description: Whether the connection was successful userId: type: number description: The user ID of the connected customer isNewUser: type: boolean description: Whether a new user was created loyaltyEnrolled: type: boolean description: Whether the user was enrolled in loyalty program pointsAwarded: type: number description: Total loyalty points awarded (welcome + purchase) message: type: string description: Human-readable result message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/purchases/{purchaseIntentId}/email-receipt: post: tags: - Purchases description: >- Send a receipt email copy to a specified email address. Validates the purchase is confirmed, then triggers the receipt email Cloud Function via PubSub. The email uses the same template as automatic storefront receipt emails. requestBody: content: application/json: schema: type: object properties: email: type: string format: email description: Email address to send the receipt to required: - email required: true parameters: - schema: type: string format: uuid in: path name: purchaseIntentId required: true description: The purchase intent ID responses: "202": description: Receipt email send initiated content: application/json: schema: description: Receipt email send initiated type: object properties: status: type: string enum: - success data: type: object properties: purchaseIntentId: type: string format: uuid email: type: string required: - purchaseIntentId - email meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/purchases/{purchaseIntentId}/order-details: get: tags: - Purchases description: Get unified order purchase details by purchase intent ID (matches storefront-web format) parameters: - schema: type: number in: query name: locationId required: true description: Location ID for permission validation - schema: type: string format: uuid in: path name: purchaseIntentId required: true description: Purchase intent UUID responses: "200": description: Order purchase details retrieved successfully content: application/json: schema: description: Order purchase details retrieved successfully type: object properties: status: type: string enum: - success data: type: object properties: orderInfo: type: object nullable: true properties: orderState: type: string enum: - initial - sent_to_kitchen - accepted - ready_to_deliver - delivered - cancelled description: Current order state deliveryKind: type: string enum: - takeaway - table - room nullable: true description: Order delivery type orderNumber: type: number nullable: true description: Daily order number for kitchen display tableName: type: string nullable: true description: Table name if order is for table service paymentFlow: type: string enum: - instant - open_tab nullable: true description: Payment timing (instant = pay now, open_tab = pay later) tabId: type: string format: uuid nullable: true description: Tab UUID if order is part of a tab hasBeenScheduled: type: boolean description: Whether order has been scheduled for future preparation desiredPickupTime: type: number nullable: true description: Desired pickup time (Unix timestamp) phoneNumber: type: string nullable: true description: Customer phone number purchaseInfo: type: object nullable: true properties: purchasedAtEpochSeconds: type: number description: Purchase timestamp (Unix seconds) totalAmountCents: type: number nullable: true description: Total purchase amount in cents (from purchases.amount_cents) lineItems: type: array items: type: object properties: type: type: string enum: - product - tip description: Line item type title: type: string description: Item title amountCents: type: number description: Total item amount in cents appliedTotalDiscountAmountCents: type: number nullable: true description: Total discount applied to this line item in cents quantity: type: number description: Quantity of this item appliedModifications: type: array items: type: object properties: title: type: string description: Modification name (e.g., "Extra cheese") priceAdjustmentCents: type: number description: Price adjustment in cents (positive for surcharge, negative for discount) description: Applied modifications (extras, options, etc.) description: Purchased items with quantities and modifications vatBreakdown: type: object properties: vatPercentage: type: number description: VAT percentage (e.g., 12 for 12%) vatAmountCents: type: number description: VAT amount in cents netAmountCents: type: number description: Net amount (excluding VAT) in cents grossAmountCents: type: number description: Gross amount (including VAT) in cents description: VAT calculation breakdown currency: type: string description: Currency code (e.g., SEK, EUR) tabInfo: type: object nullable: true properties: tabId: type: string format: uuid description: Tab UUID remainingAmountCents: type: number nullable: true description: Remaining unpaid amount on the tab in cents qrCodeId: type: string format: uuid nullable: true description: QR code UUID associated with this tab description: Unified order purchase data (matches storefront-service response format) meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/purchases/{purchaseIntentId}/receipt: get: tags: - Purchases description: Get receipt data for email generation with hierarchical line items parameters: - schema: type: number in: query name: locationId required: true description: Location ID for permission validation - schema: type: string format: uuid in: path name: purchaseIntentId required: true description: Purchase intent UUID responses: "200": description: Receipt email data retrieved successfully content: application/json: schema: description: Receipt email data retrieved successfully type: object properties: status: type: string enum: - success data: type: object properties: purchaseIntentId: type: string format: uuid description: Purchase intent UUID purchasedAt: type: string format: date-time description: Purchase timestamp currency: type: string description: Currency code (e.g., SEK) orderNumber: type: number nullable: true description: Daily order number location: type: object properties: name: type: string description: Location/restaurant name address: type: string nullable: true description: Full address phone: type: string nullable: true description: Contact phone number vatId: type: string nullable: true description: Organization number (organisationsnummer) logoUrl: type: string nullable: true description: Location logo URL storefrontSlug: type: string nullable: true description: Storefront URL slug language: type: string nullable: true description: Location language code (e.g. sv, en, no) lineItems: type: array items: type: object properties: type: type: string enum: - product - tip description: Item type title: type: string description: Item title quantity: type: number description: Quantity unitPriceCents: type: number description: Unit price in cents totalPriceCents: type: number description: Total price including children in cents appliedDiscountCents: type: number nullable: true description: Discount amount in cents appliedModifications: type: array items: type: object properties: title: type: string description: Modification name (e.g., "Extra cheese") priceAdjustmentCents: type: number description: Price adjustment in cents description: Applied modifications (extras, sizes, etc.) children: type: array items: type: object properties: title: type: string description: Child item title quantity: type: number description: Quantity unitPriceCents: type: number nullable: true description: Unit price in cents (null for zero-priced included variants) totalPriceCents: type: number nullable: true description: Total price in cents (null for zero-priced included variants) appliedModifications: type: array items: type: object properties: title: type: string description: Modification name (e.g., "Extra cheese") priceAdjustmentCents: type: number description: Price adjustment in cents description: Applied modifications description: Child items (product variants, bundle items) description: Hierarchical line items with children subtotalCents: type: number description: Subtotal before VAT in cents totalDiscountCents: type: number description: Total discounts in cents vatBreakdown: type: array items: type: object properties: rate: type: number description: VAT rate percentage (e.g., 12, 25) baseAmountCents: type: number description: Base amount before VAT in cents vatAmountCents: type: number description: VAT amount in cents description: VAT breakdown by rate totalCents: type: number description: Total amount in cents appliedVouchers: type: array items: type: object properties: code: type: string description: Voucher code appliedAmountCents: type: number description: Amount discounted in cents description: Applied vouchers/discounts customerEmail: type: string nullable: true description: Customer email address paymentMethod: type: string nullable: true description: Payment method (e.g., "visa 4242") paymentBrand: type: string nullable: true description: Payment brand (e.g., "visa") paymentLast4: type: string nullable: true description: Last 4 digits of card tableName: type: string nullable: true description: Table name if applicable deliveryKind: type: string nullable: true description: Delivery type (takeaway, table, counter) cashRegister: type: object nullable: true description: Cash register receipt data (SKV required fields). Null if not registered with cash register. properties: receiptNumber: type: number description: Löpnummer - running receipt number from unbroken ascending series registerId: type: string description: Kassabeteckning - cash register designation/ID controlUnit: type: string nullable: true description: Kontrollenhetens tillverkningsnummer - control unit serial number description: Receipt email data with hierarchical line items meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/purchases/{purchaseIntentId}/receipt/print: get: tags: - Purchases description: >- Render a purchase receipt as Adyen terminal OutputText for printing. Proxies to printer-service. **Permissions:** 🔵 `purchases.read` parameters: - schema: type: number in: query name: locationId required: true description: Location ID for permission validation - schema: type: string format: uuid in: path name: purchaseIntentId required: true description: Purchase intent UUID responses: "200": description: Adyen OutputText payload ready to ship in a Nexo PrintRequest envelope content: application/json: schema: description: Adyen OutputText payload ready to ship in a Nexo PrintRequest envelope type: object properties: status: type: string enum: - success data: type: object properties: outputText: type: array description: Ordered list of Nexo OutputText lines. items: type: object properties: Text: type: string CharacterStyle: type: string enum: - Bold - Normal Alignment: type: string enum: - Left - Centred - Right EndOfLineFlag: type: boolean required: - Text qrCode: type: object nullable: true description: Optional QR follow-up. Print as a separate Nexo envelope after the text slip. properties: url: type: string required: - url required: - outputText meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/purchases/by-intent/{intentId}: get: tags: - Purchases description: Get a single purchase by intent ID (UUID) parameters: - schema: type: number in: query name: locationId required: true description: Location ID for permission validation - schema: type: string format: uuid in: path name: intentId required: true description: Purchase intent ID (UUID) responses: "200": description: Purchase retrieved successfully content: application/json: schema: description: Purchase retrieved successfully type: object properties: status: type: string enum: - success data: type: object properties: purchase: type: object properties: id: type: number description: Purchase ID locationId: type: number description: Location ID userId: type: number nullable: true description: User ID who made the purchase amount: type: number description: Total amount in cents currency: type: string description: Currency code (e.g., SEK, EUR) paymentMethod: type: string nullable: true description: Payment method used paymentProvider: type: string nullable: true description: Payment provider (e.g., stripe, adyen) status: type: string description: Payment status (pending, completed, failed, etc.) createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp tabId: type: string nullable: true format: uuid description: Tab ID if part of a tab lineItems: type: array items: type: object properties: id: type: number description: Line item ID inventoryItemId: type: number description: Inventory item ID quantityCents: type: number description: Quantity in cents (100 = 1x) unitPriceCents: type: number description: Price per unit in cents totalPriceCents: type: number description: Total price in cents title: type: string description: Item title category: type: string nullable: true description: Item category channel: type: string nullable: true description: Order channel (POS, KIOSK, QR, ONLINE, TAKEAWAY, MOVE, MERGE, SPLIT, SYSTEM) enum: - POS - KIOSK - QR - ONLINE - TAKEAWAY - MOVE - MERGE - SPLIT - SYSTEM isTakeaway: type: boolean description: Whether this specific item is takeaway (can differ from the tab-level tabType) createdAt: type: string format: date-time description: Creation timestamp description: Purchased items metadata: type: object nullable: true description: Additional metadata additionalProperties: true meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/reporting/export-settings: get: summary: Get saved accounting export configuration for a location tags: - Reporting parameters: - schema: type: integer in: query name: locationId required: true - schema: type: string enum: - sie - gbat10 in: query name: exportType required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: exportSettings: type: object nullable: true properties: locationId: type: integer exportType: type: string enum: - sie - gbat10 mappings: type: object description: Per-key account number (string) or feature toggle (boolean). Keys are produced by the frontend mapping registries (e.g. "psp_adyen", "vat_25"). additionalProperties: type: - string - boolean includeKarmaFees: type: boolean splitByCostCenter: type: boolean description: "When true, the purchase summary endpoint groups sales / VAT / PSP rows by cost center and the SIE/GBAT10 exports emit one #OBJEKT per CC." updatedAt: type: string updatedByRetailerUserId: type: integer nullable: true updatedByName: type: string nullable: true meta: type: object properties: requestId: type: string timestamp: type: string executionTimeMs: type: integer "400": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string meta: type: object properties: requestId: type: string timestamp: type: string executionTimeMs: type: integer "500": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string meta: type: object properties: requestId: type: string timestamp: type: string executionTimeMs: type: integer put: summary: Save accounting export configuration for a location tags: - Reporting requestBody: content: application/json: schema: type: object required: - locationId - exportType - mappings - includeKarmaFees properties: locationId: type: integer exportType: type: string enum: - sie - gbat10 mappings: type: object additionalProperties: type: - string - boolean includeKarmaFees: type: boolean splitByCostCenter: type: boolean default: false required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: exportSettings: type: object nullable: true properties: locationId: type: integer exportType: type: string enum: - sie - gbat10 mappings: type: object description: Per-key account number (string) or feature toggle (boolean). Keys are produced by the frontend mapping registries (e.g. "psp_adyen", "vat_25"). additionalProperties: type: - string - boolean includeKarmaFees: type: boolean splitByCostCenter: type: boolean description: "When true, the purchase summary endpoint groups sales / VAT / PSP rows by cost center and the SIE/GBAT10 exports emit one #OBJEKT per CC." updatedAt: type: string updatedByRetailerUserId: type: integer nullable: true updatedByName: type: string nullable: true meta: type: object properties: requestId: type: string timestamp: type: string executionTimeMs: type: integer "400": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string meta: type: object properties: requestId: type: string timestamp: type: string executionTimeMs: type: integer "500": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string meta: type: object properties: requestId: type: string timestamp: type: string executionTimeMs: type: integer /api/v1/reporting/purchase-summary: get: summary: Get aggregated purchase data for accounting export tags: - Reporting parameters: - schema: type: integer in: query name: locationId required: true description: Location ID to get purchase summary for - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ in: query name: startDate required: true description: Start date in YYYY-MM-DD format - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ in: query name: endDate required: true description: End date in YYYY-MM-DD format (inclusive) - schema: type: boolean default: false in: query name: splitByCostCenter required: false description: When true, rows in items / vats / psp gain optional costCenterCode + costCenterName, and the response includes a top-level costCenters array. Defaults to false for byte-identical legacy behaviour. responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: purchaseSummary: type: object properties: items: type: array description: Line items grouped by accounting account items: type: object properties: account: type: string description: Account number or "no_account" for unmapped items description: type: string nullable: true description: Account description amount: type: integer description: Total amount in cents (excluding VAT) comment: type: array description: List of items without account mapping (only for no_account) items: type: object properties: id: type: integer name: type: string costCenterCode: type: string description: Cost-center identifier (cost_centers.code, falling back to id). Only present when splitByCostCenter=true AND the underlying tab had a cost_center_id. costCenterName: type: string description: Human-readable CC name. Paired with costCenterCode. required: - account - amount vats: type: array description: VAT amounts grouped by rate items: type: object properties: vat: type: integer description: VAT rate as percentage (e.g., 25, 12, 6) amount: type: integer description: Total VAT amount in cents costCenterCode: type: string costCenterName: type: string required: - vat - amount psp: type: array description: Totals grouped by payment service provider items: type: object properties: psp: type: string description: PSP name (e.g., adyen, swish) amount: type: integer description: Total amount in cents (including VAT and tips) tips: type: integer description: Tips amount in cents costCenterCode: type: string costCenterName: type: string required: - psp - amount - tips fees: type: array description: Karma fees grouped by PSP (never split per cost center) items: type: object properties: psp: type: string description: PSP name vat: type: integer description: VAT on fees in cents amount: type: integer description: Fee amount in cents (excluding VAT) required: - psp - vat - amount costCenters: type: array description: Distinct cost centers that contributed at least one non-zero row. Only present when splitByCostCenter=true. items: type: object properties: code: type: string name: type: string required: - code - name required: - items - vats - psp - fees meta: type: object properties: requestId: type: string timestamp: type: string executionTimeMs: type: integer "400": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string meta: type: object properties: requestId: type: string timestamp: type: string executionTimeMs: type: integer "500": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string meta: type: object properties: requestId: type: string timestamp: type: string executionTimeMs: type: integer /api/v1/reviews: post: summary: Create review tags: - Reviews description: Create a new review for a purchase. Reviews are linked to purchases via purchase_intent_id and can only be created once per purchase (duplicate submissions are idempotent). requestBody: content: application/json: schema: type: object required: - purchaseIntentId - rating additionalProperties: false properties: purchaseIntentId: type: string format: uuid description: UUID of the purchase intent this review is for reviewTags: type: array items: type: string default: [] description: Array of review tag values rating: type: integer minimum: 1 maximum: 5 description: Rating from 1 to 5 stars required: true responses: "200": description: Default Response content: application/json: schema: type: object required: - status - data - meta properties: status: type: string enum: - success data: type: object required: - reviewId properties: reviewId: type: string format: uuid description: UUID of the created review meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/reviews/{purchaseIntentId}: get: summary: Get review by purchase intent ID tags: - Reviews description: Get a review by purchase intent ID. Returns null if no review exists for the given purchase (not a 404 error). parameters: - schema: type: string format: uuid in: path name: purchaseIntentId required: true description: UUID of the purchase intent to get the review for responses: "200": description: Default Response content: application/json: schema: type: object required: - status - data - meta properties: status: type: string enum: - success data: type: object nullable: true properties: reviewId: type: string format: uuid description: Unique identifier for the review reviewTags: type: array nullable: true items: type: string description: Array of review tag values (e.g., "GOOD_FOOD_OR_DRINKS", "FRIENDLY_STAFF") rating: type: integer minimum: 1 maximum: 5 description: Rating from 1 to 5 stars meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/roles: get: summary: List roles tags: - Roles description: |- List all roles in a company with optional filters Note: KARMELEON role is automatically filtered from results **Permissions:** 🔵 `roles.read` parameters: - schema: type: number minimum: 1 default: 1 in: query name: page required: false - schema: type: number minimum: 1 maximum: 1000 default: 50 in: query name: limit required: false responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string example: success data: type: object properties: roles: type: array items: type: object properties: id: type: number name: type: string description: type: string nullable: true locationId: type: number nullable: true description: NULL = global role, number = location-specific role permissionIds: type: array items: type: number isGlobal: type: boolean description: True if this is a global/default role (available to all locations) createdAt: type: string format: date-time updatedAt: type: string format: date-time pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: summary: Create role tags: - Roles description: |- Create a new role in the company **Permissions:** 🟢 `roles.create` requestBody: content: application/json: schema: type: object required: - name - permissionIds properties: name: type: string minLength: 1 maxLength: 100 description: type: string nullable: true description: Optional role description permissionIds: type: array items: type: number description: Array of permission IDs to assign to this role required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string example: success data: type: object properties: id: type: number name: type: string description: type: string nullable: true locationId: type: number nullable: true description: NULL = global role, number = location-specific role permissionIds: type: array items: type: number isGlobal: type: boolean description: True if this is a global/default role (available to all locations) createdAt: type: string format: date-time updatedAt: type: string format: date-time meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/roles/{id}: get: summary: Get role tags: - Roles description: |- Get a single role by ID **Permissions:** 🔵 `roles.read` parameters: - schema: type: number in: path name: id required: true description: Role ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string example: success data: type: object properties: id: type: number name: type: string description: type: string nullable: true locationId: type: number nullable: true description: NULL = global role, number = location-specific role permissionIds: type: array items: type: number isGlobal: type: boolean description: True if this is a global/default role (available to all locations) createdAt: type: string format: date-time updatedAt: type: string format: date-time meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: summary: Update role tags: - Roles description: |- Update an existing role Note: Cannot update system roles or KARMELEON role **Permissions:** 🟠 `roles.update` requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 100 description: type: string description: Optional role description permissionIds: type: array items: type: number description: Array of permission IDs to assign to this role parameters: - schema: type: number in: path name: id required: true description: Role ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string example: success data: type: object properties: id: type: number name: type: string description: type: string nullable: true locationId: type: number nullable: true description: NULL = global role, number = location-specific role permissionIds: type: array items: type: number isGlobal: type: boolean description: True if this is a global/default role (available to all locations) createdAt: type: string format: date-time updatedAt: type: string format: date-time meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete role tags: - Roles description: >- Delete a role Note: Cannot delete system roles, KARMELEON role, or roles in use by users **Permissions:** 🔴 `roles.delete` parameters: - schema: type: number in: path name: id required: true description: Role ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string example: success data: type: object properties: success: type: boolean id: type: number meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/schedules: get: summary: List schedules tags: - Schedules description: List schedules with optional filtering parameters: - schema: type: number in: query name: locationId required: false description: Filter by location ID - schema: type: string enum: - MENU - ITEM - LOCATION - MODIFIER - CATEGORY - MENU_LAYOUT - VARIANT_GROUP - VOUCHER - EARNING_RULE - BOOKING - LOYALTY_REWARD in: query name: entityType required: false description: Filter by entity type - schema: type: string in: query name: entityId required: false description: Filter by entity ID - schema: type: boolean in: query name: isActive required: false description: Filter by active status - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: number minimum: 1 maximum: 100 default: 20 in: query name: limit required: false description: Items per page responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: schedules: type: array items: type: object properties: id: type: string description: Unique schedule ID entityType: type: string enum: - MENU - ITEM - LOCATION - MODIFIER - CATEGORY - MENU_LAYOUT - VARIANT_GROUP - VOUCHER - EARNING_RULE - BOOKING - LOYALTY_REWARD description: Type of entity being scheduled entityId: type: string description: ID of the entity being scheduled locationId: type: number description: Location ID this schedule applies to name: type: string nullable: true description: Schedule name description: type: string nullable: true description: Schedule description isActive: type: boolean description: Whether schedule is active priority: type: number description: Priority for conflicting schedules (higher = more important) createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp rules: type: array items: type: object properties: id: type: string description: Unique rule ID scheduleId: type: string description: Schedule ID this rule belongs to ruleType: type: string enum: - WEEKDAY - DATE_RANGE - SPECIFIC_DATE description: Type of schedule rule weekday: type: number nullable: true minimum: 0 maximum: 6 description: Day of week (0=Sunday, 6=Saturday) startTime: type: string nullable: true pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: Start time in HH:MM or HH:MM:SS format (seconds are stripped) endTime: type: string nullable: true pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: End time in HH:MM or HH:MM:SS format (seconds are stripped) startDate: type: string nullable: true format: date description: Start date for date range rules endDate: type: string nullable: true format: date description: End date for date range rules validFrom: type: string nullable: true format: date description: Rule valid from date validTo: type: string nullable: true format: date description: Rule valid until date isAvailable: type: boolean description: Whether entity is available during this rule createdAt: type: string format: date-time description: Creation timestamp required: - id - scheduleId - ruleType - isAvailable - createdAt description: Schedule rules defining availability patterns required: - id - entityType - entityId - locationId - isActive - priority - createdAt - updatedAt - rules pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages required: - schedules - pagination meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: summary: Create schedule tags: - Schedules description: |- Create a new schedule with rules **Permissions:** 🟢 `schedules.create` requestBody: content: application/json: schema: type: object properties: entityType: type: string enum: - MENU - ITEM - LOCATION - MODIFIER - CATEGORY - MENU_LAYOUT - VARIANT_GROUP - VOUCHER - EARNING_RULE - BOOKING - LOYALTY_REWARD description: Type of entity being scheduled entityId: type: string description: ID of the entity to schedule locationId: type: number description: Location ID name: type: string description: Schedule name description: type: string description: Schedule description isActive: type: boolean default: true description: Whether schedule is active priority: type: number default: 0 description: Priority for conflicting schedules rules: type: array items: type: object properties: ruleType: type: string enum: - WEEKDAY - DATE_RANGE - SPECIFIC_DATE description: Type of schedule rule weekday: type: number minimum: 0 maximum: 6 description: Day of week (0=Sunday, 6=Saturday) startTime: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: Start time in HH:MM or HH:MM:SS format (seconds are stripped) endTime: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: End time in HH:MM or HH:MM:SS format (seconds are stripped) startDate: type: string format: date description: Start date for date range rules endDate: type: string format: date description: End date for date range rules validFrom: type: string format: date description: Rule valid from date validTo: type: string format: date description: Rule valid until date isAvailable: type: boolean default: true description: Whether entity is available during this rule required: - ruleType description: Schedule rules defining availability patterns required: - entityType - entityId - locationId - rules required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string description: Unique schedule ID entityType: type: string enum: - MENU - ITEM - LOCATION - MODIFIER - CATEGORY - MENU_LAYOUT - VARIANT_GROUP - VOUCHER - EARNING_RULE - BOOKING - LOYALTY_REWARD description: Type of entity being scheduled entityId: type: string description: ID of the entity being scheduled locationId: type: number description: Location ID this schedule applies to name: type: string nullable: true description: Schedule name description: type: string nullable: true description: Schedule description isActive: type: boolean description: Whether schedule is active priority: type: number description: Priority for conflicting schedules (higher = more important) createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp rules: type: array items: type: object properties: id: type: string description: Unique rule ID scheduleId: type: string description: Schedule ID this rule belongs to ruleType: type: string enum: - WEEKDAY - DATE_RANGE - SPECIFIC_DATE description: Type of schedule rule weekday: type: number nullable: true minimum: 0 maximum: 6 description: Day of week (0=Sunday, 6=Saturday) startTime: type: string nullable: true pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: Start time in HH:MM or HH:MM:SS format (seconds are stripped) endTime: type: string nullable: true pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: End time in HH:MM or HH:MM:SS format (seconds are stripped) startDate: type: string nullable: true format: date description: Start date for date range rules endDate: type: string nullable: true format: date description: End date for date range rules validFrom: type: string nullable: true format: date description: Rule valid from date validTo: type: string nullable: true format: date description: Rule valid until date isAvailable: type: boolean description: Whether entity is available during this rule createdAt: type: string format: date-time description: Creation timestamp required: - id - scheduleId - ruleType - isAvailable - createdAt description: Schedule rules defining availability patterns required: - id - entityType - entityId - locationId - isActive - priority - createdAt - updatedAt - rules meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/schedules/{id}: get: summary: Get schedule tags: - Schedules description: Get a single schedule by ID with its rules parameters: - schema: type: string in: path name: id required: true description: Schedule ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string description: Unique schedule ID entityType: type: string enum: - MENU - ITEM - LOCATION - MODIFIER - CATEGORY - MENU_LAYOUT - VARIANT_GROUP - VOUCHER - EARNING_RULE - BOOKING - LOYALTY_REWARD description: Type of entity being scheduled entityId: type: string description: ID of the entity being scheduled locationId: type: number description: Location ID this schedule applies to name: type: string nullable: true description: Schedule name description: type: string nullable: true description: Schedule description isActive: type: boolean description: Whether schedule is active priority: type: number description: Priority for conflicting schedules (higher = more important) createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp rules: type: array items: type: object properties: id: type: string description: Unique rule ID scheduleId: type: string description: Schedule ID this rule belongs to ruleType: type: string enum: - WEEKDAY - DATE_RANGE - SPECIFIC_DATE description: Type of schedule rule weekday: type: number nullable: true minimum: 0 maximum: 6 description: Day of week (0=Sunday, 6=Saturday) startTime: type: string nullable: true pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: Start time in HH:MM or HH:MM:SS format (seconds are stripped) endTime: type: string nullable: true pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: End time in HH:MM or HH:MM:SS format (seconds are stripped) startDate: type: string nullable: true format: date description: Start date for date range rules endDate: type: string nullable: true format: date description: End date for date range rules validFrom: type: string nullable: true format: date description: Rule valid from date validTo: type: string nullable: true format: date description: Rule valid until date isAvailable: type: boolean description: Whether entity is available during this rule createdAt: type: string format: date-time description: Creation timestamp required: - id - scheduleId - ruleType - isAvailable - createdAt description: Schedule rules defining availability patterns required: - id - entityType - entityId - locationId - isActive - priority - createdAt - updatedAt - rules meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: summary: Update schedule tags: - Schedules description: |- Update an existing schedule **Permissions:** 🟠 `schedules.update` requestBody: content: application/json: schema: type: object properties: name: type: string description: type: string nullable: true isActive: type: boolean priority: type: number parameters: - schema: type: string in: path name: id required: true description: Schedule ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string description: Unique schedule ID entityType: type: string enum: - MENU - ITEM - LOCATION - MODIFIER - CATEGORY - MENU_LAYOUT - VARIANT_GROUP - VOUCHER - EARNING_RULE - BOOKING - LOYALTY_REWARD description: Type of entity being scheduled entityId: type: string description: ID of the entity being scheduled locationId: type: number description: Location ID this schedule applies to name: type: string nullable: true description: Schedule name description: type: string nullable: true description: Schedule description isActive: type: boolean description: Whether schedule is active priority: type: number description: Priority for conflicting schedules (higher = more important) createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp rules: type: array items: type: object properties: id: type: string description: Unique rule ID scheduleId: type: string description: Schedule ID this rule belongs to ruleType: type: string enum: - WEEKDAY - DATE_RANGE - SPECIFIC_DATE description: Type of schedule rule weekday: type: number nullable: true minimum: 0 maximum: 6 description: Day of week (0=Sunday, 6=Saturday) startTime: type: string nullable: true pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: Start time in HH:MM or HH:MM:SS format (seconds are stripped) endTime: type: string nullable: true pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: End time in HH:MM or HH:MM:SS format (seconds are stripped) startDate: type: string nullable: true format: date description: Start date for date range rules endDate: type: string nullable: true format: date description: End date for date range rules validFrom: type: string nullable: true format: date description: Rule valid from date validTo: type: string nullable: true format: date description: Rule valid until date isAvailable: type: boolean description: Whether entity is available during this rule createdAt: type: string format: date-time description: Creation timestamp required: - id - scheduleId - ruleType - isAvailable - createdAt description: Schedule rules defining availability patterns required: - id - entityType - entityId - locationId - isActive - priority - createdAt - updatedAt - rules meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete schedule tags: - Schedules description: |- Delete a schedule and its rules **Permissions:** 🔴 `schedules.delete` parameters: - schema: type: string in: path name: id required: true description: Schedule ID responses: "200": description: Schedule successfully deleted content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: deleted: type: boolean meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/schedules/{scheduleId}/rules: post: summary: Add schedule rule tags: - Schedules description: |- Add a new rule to an existing schedule **Permissions:** 🟢 `schedules.create` requestBody: content: application/json: schema: type: object properties: ruleType: type: string enum: - WEEKDAY - DATE_RANGE - SPECIFIC_DATE description: Type of schedule rule weekday: type: number minimum: 0 maximum: 6 description: Day of week (0=Sunday, 6=Saturday) startTime: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: Start time in HH:MM or HH:MM:SS format (seconds are stripped) endTime: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: End time in HH:MM or HH:MM:SS format (seconds are stripped) startDate: type: string format: date description: Start date for date range rules endDate: type: string format: date description: End date for date range rules validFrom: type: string format: date description: Rule valid from date validTo: type: string format: date description: Rule valid until date isAvailable: type: boolean default: true description: Whether entity is available during this rule required: - ruleType required: true parameters: - schema: type: string in: path name: scheduleId required: true description: Schedule ID responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string description: Unique rule ID scheduleId: type: string description: Schedule ID this rule belongs to ruleType: type: string enum: - WEEKDAY - DATE_RANGE - SPECIFIC_DATE description: Type of schedule rule weekday: type: number nullable: true minimum: 0 maximum: 6 description: Day of week (0=Sunday, 6=Saturday) startTime: type: string nullable: true pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: Start time in HH:MM or HH:MM:SS format (seconds are stripped) endTime: type: string nullable: true pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: End time in HH:MM or HH:MM:SS format (seconds are stripped) startDate: type: string nullable: true format: date description: Start date for date range rules endDate: type: string nullable: true format: date description: End date for date range rules validFrom: type: string nullable: true format: date description: Rule valid from date validTo: type: string nullable: true format: date description: Rule valid until date isAvailable: type: boolean description: Whether entity is available during this rule createdAt: type: string format: date-time description: Creation timestamp required: - id - scheduleId - ruleType - isAvailable - createdAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: summary: Replace schedule rules tags: - Schedules description: |- Replace all rules for a schedule in a single operation **Permissions:** 🟠 `schedules.update` requestBody: content: application/json: schema: type: object properties: rules: type: array items: type: object properties: ruleType: type: string enum: - WEEKDAY - DATE_RANGE - SPECIFIC_DATE description: Type of schedule rule weekday: type: number minimum: 0 maximum: 6 description: Day of week (0=Sunday, 6=Saturday) startTime: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: Start time in HH:MM or HH:MM:SS format (seconds are stripped) endTime: type: string pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: End time in HH:MM or HH:MM:SS format (seconds are stripped) startDate: type: string format: date description: Start date for date range rules endDate: type: string format: date description: End date for date range rules validFrom: type: string format: date description: Rule valid from date validTo: type: string format: date description: Rule valid until date isAvailable: type: boolean default: true description: Whether entity is available during this rule required: - ruleType description: New rules to replace existing rules minItems: 1 required: - rules required: true parameters: - schema: type: string in: path name: scheduleId required: true description: Schedule ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string description: Unique schedule ID entityType: type: string enum: - MENU - ITEM - LOCATION - MODIFIER - CATEGORY - MENU_LAYOUT - VARIANT_GROUP - VOUCHER - EARNING_RULE - BOOKING - LOYALTY_REWARD description: Type of entity being scheduled entityId: type: string description: ID of the entity being scheduled locationId: type: number description: Location ID this schedule applies to name: type: string nullable: true description: Schedule name description: type: string nullable: true description: Schedule description isActive: type: boolean description: Whether schedule is active priority: type: number description: Priority for conflicting schedules (higher = more important) createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp rules: type: array items: type: object properties: id: type: string description: Unique rule ID scheduleId: type: string description: Schedule ID this rule belongs to ruleType: type: string enum: - WEEKDAY - DATE_RANGE - SPECIFIC_DATE description: Type of schedule rule weekday: type: number nullable: true minimum: 0 maximum: 6 description: Day of week (0=Sunday, 6=Saturday) startTime: type: string nullable: true pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: Start time in HH:MM or HH:MM:SS format (seconds are stripped) endTime: type: string nullable: true pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: End time in HH:MM or HH:MM:SS format (seconds are stripped) startDate: type: string nullable: true format: date description: Start date for date range rules endDate: type: string nullable: true format: date description: End date for date range rules validFrom: type: string nullable: true format: date description: Rule valid from date validTo: type: string nullable: true format: date description: Rule valid until date isAvailable: type: boolean description: Whether entity is available during this rule createdAt: type: string format: date-time description: Creation timestamp required: - id - scheduleId - ruleType - isAvailable - createdAt description: Schedule rules defining availability patterns required: - id - entityType - entityId - locationId - isActive - priority - createdAt - updatedAt - rules meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/schedules/check-availability: get: summary: Check availability tags: - Schedules description: Check entity availability at a specific time based on schedules parameters: - schema: type: string enum: - MENU - ITEM - LOCATION - MODIFIER - CATEGORY - MENU_LAYOUT - VARIANT_GROUP - VOUCHER - EARNING_RULE - BOOKING - LOYALTY_REWARD in: query name: entityType required: true description: Type of entity to check - schema: type: string in: query name: entityId required: true description: ID of the entity to check - schema: type: number in: query name: locationId required: false description: Location ID - schema: type: string format: date-time in: query name: checkTime required: false description: Time to check availability (defaults to now) responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: isAvailable: type: boolean description: Whether entity is available at the specified time matchingSchedules: type: array items: type: object properties: id: type: string description: Unique schedule ID entityType: type: string enum: - MENU - ITEM - LOCATION - MODIFIER - CATEGORY - MENU_LAYOUT - VARIANT_GROUP - VOUCHER - EARNING_RULE - BOOKING - LOYALTY_REWARD description: Type of entity being scheduled entityId: type: string description: ID of the entity being scheduled locationId: type: number description: Location ID this schedule applies to name: type: string nullable: true description: Schedule name description: type: string nullable: true description: Schedule description isActive: type: boolean description: Whether schedule is active priority: type: number description: Priority for conflicting schedules (higher = more important) createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp rules: type: array items: type: object properties: id: type: string description: Unique rule ID scheduleId: type: string description: Schedule ID this rule belongs to ruleType: type: string enum: - WEEKDAY - DATE_RANGE - SPECIFIC_DATE description: Type of schedule rule weekday: type: number nullable: true minimum: 0 maximum: 6 description: Day of week (0=Sunday, 6=Saturday) startTime: type: string nullable: true pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: Start time in HH:MM or HH:MM:SS format (seconds are stripped) endTime: type: string nullable: true pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: End time in HH:MM or HH:MM:SS format (seconds are stripped) startDate: type: string nullable: true format: date description: Start date for date range rules endDate: type: string nullable: true format: date description: End date for date range rules validFrom: type: string nullable: true format: date description: Rule valid from date validTo: type: string nullable: true format: date description: Rule valid until date isAvailable: type: boolean description: Whether entity is available during this rule createdAt: type: string format: date-time description: Creation timestamp required: - id - scheduleId - ruleType - isAvailable - createdAt description: Schedule rules defining availability patterns required: - id - entityType - entityId - locationId - isActive - priority - createdAt - updatedAt - rules description: Schedules that apply to this entity required: - isAvailable - matchingSchedules meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/schedules/rules/{ruleId}: put: summary: Update schedule rule tags: - Schedules description: |- Update an existing schedule rule **Permissions:** 🟠 `schedules.update` requestBody: content: application/json: schema: type: object properties: ruleType: type: string enum: - WEEKDAY - DATE_RANGE - SPECIFIC_DATE weekday: type: number nullable: true minimum: 0 maximum: 6 startTime: type: string nullable: true pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ endTime: type: string nullable: true pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ startDate: type: string nullable: true format: date endDate: type: string nullable: true format: date validFrom: type: string nullable: true format: date validTo: type: string nullable: true format: date isAvailable: type: boolean parameters: - schema: type: string in: path name: ruleId required: true description: Rule ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string description: Unique rule ID scheduleId: type: string description: Schedule ID this rule belongs to ruleType: type: string enum: - WEEKDAY - DATE_RANGE - SPECIFIC_DATE description: Type of schedule rule weekday: type: number nullable: true minimum: 0 maximum: 6 description: Day of week (0=Sunday, 6=Saturday) startTime: type: string nullable: true pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: Start time in HH:MM or HH:MM:SS format (seconds are stripped) endTime: type: string nullable: true pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$ description: End time in HH:MM or HH:MM:SS format (seconds are stripped) startDate: type: string nullable: true format: date description: Start date for date range rules endDate: type: string nullable: true format: date description: End date for date range rules validFrom: type: string nullable: true format: date description: Rule valid from date validTo: type: string nullable: true format: date description: Rule valid until date isAvailable: type: boolean description: Whether entity is available during this rule createdAt: type: string format: date-time description: Creation timestamp required: - id - scheduleId - ruleType - isAvailable - createdAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete schedule rule tags: - Schedules description: |- Delete a schedule rule **Permissions:** 🔴 `schedules.delete` parameters: - schema: type: string in: path name: ruleId required: true description: Rule ID responses: "200": description: Rule successfully deleted content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: deleted: type: boolean meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/settlements/{settlementId}: get: summary: Get settlement details tags: - Settlements description: Get settlement details by ID parameters: - schema: type: string format: uuid in: path name: settlementId required: true description: ID of the settlement to retrieve responses: "200": description: Default Response content: application/json: schema: type: object required: - status - data - meta properties: status: type: string enum: - success data: type: object required: - id - tabMemberId - state - createdAt - updatedAt additionalProperties: false properties: id: type: string format: uuid description: Unique identifier for the settlement tabMemberId: type: string format: uuid description: ID of the tab member who owns this settlement paymentId: type: integer nullable: true description: Payment ID if settlement has been processed for payment state: type: string enum: - in_preparation - payment_in_progress - settled - cancelled description: Current state of the settlement createdAt: type: string format: date-time description: When the settlement was created updatedAt: type: string format: date-time description: When the settlement was last updated meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{tabId}/settlements/active: post: summary: Get or create active settlement tags: - Settlements description: Get or create active settlement for a tab member requestBody: content: application/json: schema: type: object required: - tabMember additionalProperties: false properties: tabMember: type: object additionalProperties: false properties: id: type: integer description: User ID (Priority 1 - highest priority) email: type: string format: email description: Email address (Priority 2) phone: type: string description: Phone number (Priority 3) identifier: type: string description: Device identifier or session ID (Priority 4 - lowest priority) description: "Tab member identification. The system uses priority order: id > email > phone > identifier" required: true parameters: - schema: type: string format: uuid in: path name: tabId required: true description: ID of the tab to get settlement for responses: "200": description: Default Response content: application/json: schema: type: object required: - status - data - meta properties: status: type: string enum: - success data: type: object required: - tabSettlementId - state - isNew additionalProperties: false properties: tabSettlementId: type: string format: uuid description: Unique identifier for the settlement state: type: string enum: - in_preparation - payment_in_progress - settled - cancelled description: Current state of the settlement isNew: type: boolean description: Whether this settlement was just created (true) or already existed (false) meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/statistics/items-aggregated: get: tags: - Statistics description: >- Retrieve aggregated items and modifications with pagination. **Query Routing**: Automatically routes to BigQuery for historical data (>24 hours) or PostgreSQL for recent data. **Item Types**: - `regular_item` - Normal menu items - Other types - Item modifications (extras) **Use Cases**: - Item sales reports - Menu performance analysis - VAT reporting **Permissions:** 🔵 `statistics.read` parameters: - schema: type: string in: query name: locationIds required: true description: Comma-separated list of location IDs - schema: type: string format: date in: query name: startDate required: true description: Start date (YYYY-MM-DD) - schema: type: string format: date in: query name: endDate required: true description: End date (YYYY-MM-DD) - schema: type: string default: "1" in: query name: page required: false description: Page number - schema: type: string default: "50" in: query name: limit required: false description: Items per page (max 1000) responses: "200": description: Aggregated items data content: application/json: schema: description: Aggregated items data type: object properties: status: type: string enum: - success data: type: object properties: items: type: array items: type: object properties: title: type: string nullable: true locationName: type: string nullable: true locationId: type: number itemId: type: number nullable: true articleNumber: type: string nullable: true itemType: type: string discountPercentage: type: number amountIncVat: type: number vatAmount: type: number amountExVat: type: number vatRate: type: number nullable: true soldCount: type: number required: - locationId - itemType - amountIncVat - vatAmount - amountExVat - soldCount pagination: type: object properties: page: type: number limit: type: number total: type: number totalPages: type: number required: - page - limit - total - totalPages required: - items - pagination meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number source: type: string enum: - bigquery - postgres required: - requestId - timestamp - executionTimeMs - source required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/statistics/sale-summary: get: tags: - Statistics description: >- Retrieve sale summary with items, extras (modifications), and tips for a date range. **Query Routing**: Automatically routes to BigQuery for historical data (>24 hours) or PostgreSQL for recent data. **Response includes**: - Items sold with VAT breakdown - Item modifications (extras) with VAT breakdown - Total tips - Summary totals **Permissions:** 🔵 `statistics.read` parameters: - schema: type: string in: query name: locationIds required: true description: Comma-separated list of location IDs - schema: type: string format: date in: query name: startDate required: true description: Start date (YYYY-MM-DD) - schema: type: string format: date in: query name: endDate required: true description: End date (YYYY-MM-DD) responses: "200": description: Sale summary data content: application/json: schema: description: Sale summary data type: object properties: status: type: string enum: - success data: type: object properties: items: type: array items: type: object properties: itemId: type: number nullable: true soldCount: type: number amountIncVat: type: number vatAmount: type: number vatRate: type: number nullable: true required: - soldCount - amountIncVat - vatAmount extras: type: array items: type: object properties: itemId: type: number nullable: true soldCount: type: number amountIncVat: type: number vatAmount: type: number vatRate: type: number nullable: true required: - soldCount - amountIncVat - vatAmount totalTips: type: number summary: type: object properties: totalAmountIncVat: type: number totalVatAmount: type: number totalSoldCount: type: number required: - totalAmountIncVat - totalVatAmount - totalSoldCount required: - items - extras - totalTips - summary meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number source: type: string enum: - bigquery - postgres required: - requestId - timestamp - executionTimeMs - source required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/statistics/time-series: get: tags: - Statistics description: >- Retrieve time series data for a specific metric across locations and date range. **Query Routing**: Automatically routes to BigQuery for historical data (>24 hours) or PostgreSQL for recent data. **Available Metrics**: - `gmv` - Gross Merchandise Value - `orders_count` - Number of orders - `sold_count` - Number of items sold - `tips_amount` - Total tips amount - `saved_co2` - CO2 saved (grams) - `pushes_sent` - Push notifications sent **Target Options**: - `aggregated` - Combine all locations into single series - `locations` - Return separate series per location **Permissions:** 🔵 `statistics.read` parameters: - schema: type: string in: query name: locationIds required: true description: Comma-separated list of location IDs (e.g., "100,101,102") - schema: type: string format: date in: query name: startDate required: true description: Start date (YYYY-MM-DD) - schema: type: string format: date in: query name: endDate required: true description: End date (YYYY-MM-DD) - schema: type: string enum: - gmv - orders_count - sold_count - tips_amount - saved_co2 - pushes_sent in: query name: metric required: true description: Metric to retrieve - schema: type: string enum: - aggregated - locations default: aggregated in: query name: target required: false description: Aggregation target responses: "200": description: Time series data content: application/json: schema: description: Time series data type: object properties: status: type: string enum: - success data: type: object properties: metric: type: string target: type: string enum: - aggregated - locations points: type: array items: type: object properties: locationId: type: number nullable: true date: type: string format: date value: type: number required: - date - value summary: type: object properties: total: type: number average: type: number min: type: number max: type: number required: - total - average - min - max required: - metric - target - points - summary meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number source: type: string enum: - bigquery - postgres required: - requestId - timestamp - executionTimeMs - source required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/statistics/time-series-batch: get: tags: - Statistics description: |- Retrieve time series data for MULTIPLE metrics in a single request. Much more efficient than calling the single-metric endpoint multiple times. **Query Routing**: Automatically routes to BigQuery for historical data (>24 hours) or PostgreSQL for recent data. **Available Metrics** (comma-separated): - `gmv` - Gross Merchandise Value - `orders_count` - Number of orders - `sold_count` - Number of items sold - `tips_amount` - Total tips amount - `saved_co2` - CO2 saved (grams) - `pushes_sent` - Push notifications sent **Target Options**: - `aggregated` - Combine all locations into single series - `locations` - Return separate series per location **Example**: `/api/v1/statistics/time-series-batch?metrics=gmv,orders_count,sold_count&locationIds=100,101&startDate=2025-01-01&endDate=2025-01-31` **Permissions:** 🔵 `statistics.read` parameters: - schema: type: string in: query name: locationIds required: true description: Comma-separated list of location IDs (e.g., "100,101,102") - schema: type: string format: date in: query name: startDate required: true description: Start date (YYYY-MM-DD) - schema: type: string format: date in: query name: endDate required: true description: End date (YYYY-MM-DD) - schema: type: string in: query name: metrics required: true description: Comma-separated list of metrics (e.g., "gmv,orders_count,sold_count") - schema: type: string enum: - aggregated - locations default: aggregated in: query name: target required: false description: Aggregation target responses: "200": description: Time series data for multiple metrics content: application/json: schema: description: Time series data for multiple metrics type: object properties: status: type: string enum: - success data: type: object properties: target: type: string enum: - aggregated - locations metrics: type: object additionalProperties: type: object properties: metric: type: string enum: - gmv - orders_count - sold_count - tips_amount - saved_co2 - pushes_sent points: type: array items: type: object properties: locationId: type: number nullable: true date: type: string format: date value: type: number required: - date - value summary: type: object properties: total: type: number average: type: number min: type: number max: type: number required: - total - average - min - max required: - metric - points - summary description: Object with metric names as keys and their data as values required: - target - metrics meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number source: type: string enum: - bigquery - postgres metricsRequested: type: number required: - requestId - timestamp - executionTimeMs - source - metricsRequested required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/statistics/tips: get: tags: - Statistics description: >- Retrieve tips for a location and date range. **Query Routing**: Automatically routes to BigQuery for historical data (>24 hours) or PostgreSQL for recent data. **Response includes**: - Tips by date with VAT breakdown - Total amounts and counts **Permissions:** 🔵 `statistics.read` parameters: - schema: type: string in: query name: locationId required: true description: Location ID - schema: type: string format: date in: query name: startDate required: true description: Start date (YYYY-MM-DD) - schema: type: string format: date in: query name: endDate required: true description: End date (YYYY-MM-DD) responses: "200": description: Tips data content: application/json: schema: description: Tips data type: object properties: status: type: string enum: - success data: type: object properties: tips: type: array items: type: object properties: locationId: type: number date: type: string format: date amountIncVat: type: number vat: type: number nullable: true vatRate: type: number nullable: true count: type: number title: type: string nullable: true required: - locationId - date - amountIncVat - count summary: type: object properties: totalAmount: type: number totalCount: type: number required: - totalAmount - totalCount required: - tips - summary meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number source: type: string enum: - bigquery - postgres required: - requestId - timestamp - executionTimeMs - source required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/table-groups: get: summary: List table groups tags: - Table Groups description: |- List table groups with optional filtering and sorting **Permissions:** 🔵 `table_groups.read` parameters: - schema: type: number in: query name: locationId required: false description: Filter by location ID - schema: type: string in: query name: search required: false description: Search by name or description - schema: type: string default: name in: query name: sort required: false description: Sort field (name, created_at) - schema: type: string enum: - asc - desc default: asc in: query name: order required: false description: Sort order - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: number minimum: 1 maximum: 100 default: 20 in: query name: limit required: false description: Items per page responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: tableGroups: type: array items: type: object properties: id: type: number description: Unique table group ID name: type: string description: Group name (e.g., "Patio", "Main Dining Room") description: type: string nullable: true description: Group description locationId: type: number description: Location ID tableIds: type: array items: type: string format: uuid description: Array of table UUIDs in this group createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time nullable: true description: Last update timestamp required: - id - name - locationId - tableIds - createdAt pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages required: - tableGroups - pagination meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: summary: Create table group tags: - Table Groups description: |- Create a new table group **Permissions:** 🟢 `table_groups.create` requestBody: content: application/json: schema: type: object properties: locationId: type: number description: Location ID name: type: string minLength: 1 description: Group name description: type: string description: Group description required: - locationId - name required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Unique table group ID name: type: string description: Group name (e.g., "Patio", "Main Dining Room") description: type: string nullable: true description: Group description locationId: type: number description: Location ID tableIds: type: array items: type: string format: uuid description: Array of table UUIDs in this group createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time nullable: true description: Last update timestamp required: - id - name - locationId - tableIds - createdAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/table-groups/{id}: get: summary: Get table group tags: - Table Groups description: |- Get a single table group by ID with table UUIDs **Permissions:** 🔵 `table_groups.read` parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: id required: true description: Table group ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Unique table group ID name: type: string description: Group name (e.g., "Patio", "Main Dining Room") description: type: string nullable: true description: Group description locationId: type: number description: Location ID tableIds: type: array items: type: string format: uuid description: Array of table UUIDs in this group createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time nullable: true description: Last update timestamp required: - id - name - locationId - tableIds - createdAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: summary: Update table group tags: - Table Groups description: |- Update an existing table group **Permissions:** 🟠 `table_groups.update` requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 description: type: string nullable: true parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: id required: true description: Table group ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Unique table group ID name: type: string description: Group name (e.g., "Patio", "Main Dining Room") description: type: string nullable: true description: Group description locationId: type: number description: Location ID tableIds: type: array items: type: string format: uuid description: Array of table UUIDs in this group createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time nullable: true description: Last update timestamp required: - id - name - locationId - tableIds - createdAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete table group tags: - Table Groups description: |- Delete a table group **Permissions:** 🔴 `table_groups.delete` parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: id required: true description: Table group ID responses: "200": description: Table group successfully deleted content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: deleted: type: boolean meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/locations/{locationId}/staff: get: summary: List staff for a location tags: - Tables description: >- List retailer_users with access to a location. Powers the POS table-map Staff sidebar. Returns a minimal projection (id, name, color). **Permissions:** 🔵 `tables.read` parameters: - schema: type: string in: path name: locationId required: true description: Location ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: staff: type: array items: type: object properties: id: type: number name: type: - "null" - string color: type: - "null" - string description: Hex color (#RRGGBB) or null. required: - id required: - staff meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/retailer-users/{retailerUserId}/color: put: summary: Update a staff member's color tags: - Tables description: >- Set or clear the hex color used on the POS table-map staff badge. The target retailer_user must have access to the caller's active location. **Permissions:** 🟠 `tables.update` requestBody: content: application/json: schema: type: object properties: color: type: - string - "null" pattern: ^#[0-9a-fA-F]{6}$ description: Hex color (#RRGGBB) or null to clear. required: - color required: true parameters: - schema: type: string in: path name: retailerUserId required: true description: Retailer user ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number name: type: - "null" - string color: type: - "null" - string required: - id meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tables: get: summary: List tables tags: - Tables description: |- List tables with optional filtering **Permissions:** 🔵 `tables.read` parameters: - schema: type: number in: query name: locationId required: false description: Filter by location ID - schema: type: string enum: - live - paused - deleted in: query name: status required: false description: Filter by status - schema: type: number in: query name: tableGroupId required: false description: Filter by table group ID - schema: type: string in: query name: search required: false description: Search by name or description - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: number minimum: 1 maximum: 999 default: 20 in: query name: limit required: false description: Items per page responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: tables: type: array items: type: object properties: id: type: string format: uuid description: Unique table ID (UUID) name: type: string description: Table name/number description: type: string nullable: true description: Table description contextParams: type: object additionalProperties: true description: Custom context parameters locationId: type: number description: Location ID storefrontUrl: type: string format: uri nullable: true description: Full storefront URL for this table tableGroupId: type: number nullable: true description: Table group ID (if grouped) costCenterId: type: number nullable: true description: Cost center ID status: type: string enum: - live - paused - deleted description: Table status qrCodeImageUrl: type: string format: uri nullable: true description: QR code image URL activeTabs: type: array items: type: object properties: id: type: string description: Tab UUID state: type: string description: Tab state (started, initiated, etc.) orderTotal: type: number description: Total order amount in cents (legacy field) paidTotal: type: number description: Total paid amount in cents (legacy field) tipsTotal: type: number description: Total tips in cents selectedPaymentFlow: type: string nullable: true description: Selected payment flow coursingOrder: type: number nullable: true description: Current coursing level for the tab (items below this level cannot be sent) memberCount: type: number description: Number of tab_members on this tab (party size for walk-ins) totalAmountCents: type: number description: Total order amount in cents (from tabs table) paidAmountCents: type: number description: Total paid amount in cents (from tabs table) remainingBalanceCents: type: number description: Remaining balance in cents paymentMode: type: string enum: - ITEM - AMOUNT description: Payment mode storefrontQrCodeId: type: string format: uuid nullable: true description: Table/QR code UUID createdAt: type: string format: date-time description: Tab creation timestamp updatedAt: type: string format: date-time nullable: true description: Tab last update timestamp extras: type: array items: type: object additionalProperties: true description: Tab extras (only in single table endpoint) kitchenDispatches: type: array items: type: object properties: id: type: string description: Kitchen dispatch UUID createdAt: type: string format: date-time description: Creation timestamp dailyOrderNumber: type: number nullable: true description: Daily order number state: type: string description: Dispatch state tabUUID: type: string description: Tab UUID tabType: type: string description: Tab type (table, takeaway, etc.) tableName: type: string nullable: true description: Table name if applicable tabState: type: string description: Current tab state source: type: string nullable: true description: Source channel that created the dispatch (POS, QR, KIOSK, ONLINE, TAKEAWAY, MOVE, MERGE, SPLIT, SYSTEM) message: type: string nullable: true description: Optional contextual message (e.g., "Moved from Table 5") comments: type: array items: type: object properties: comment: type: string description: Comment text createdAt: type: string format: date-time description: Comment timestamp tabMemberUUID: type: string nullable: true description: Tab member UUID who made the comment uuid: type: string description: Comment UUID additionalProperties: true description: Dispatch comments kitchenDispatchItems: type: array items: type: object properties: id: type: string description: Kitchen dispatch item UUID itemId: type: number nullable: true description: Item ID from inventory saleItemId: type: number nullable: true description: Sale item ID price: type: number description: Item price in cents basePrice: type: number description: Base price before modifications quantityCents: type: number nullable: true description: Item quantity in cents (e.g., 100 = 1.0, 50 = 0.5) coursingOrder: type: number nullable: true description: Coursing level for this item (e.g., 1=appetizer, 2=main, 3=dessert) isNonSurplus: type: boolean description: Whether item is non-surplus settlementState: type: string nullable: true description: Settlement state itemState: type: string nullable: true description: Kitchen-side item state ('aborted' = voided) voidedQuantityCents: type: number nullable: true description: Voided slice in cents (read from platform_events) — null when not aborted title: type: string nullable: true description: Item title tabMember: type: object properties: uuid: type: string nullable: true description: Tab member UUID name: type: string description: Member name email: type: string description: Member email additionalProperties: true comments: type: array items: type: object properties: comment: type: string description: Comment text createdAt: type: string format: date-time description: Comment timestamp tabMemberUUID: type: string nullable: true description: Tab member UUID who made the comment uuid: type: string description: Comment UUID additionalProperties: true description: Item comments variants: type: array items: type: object properties: id: type: number description: Variant ID name: type: string description: Variant name price: type: number description: Variant price (positive or negative) quantityCents: type: number nullable: true description: Quantity in cents (100 = 1.0). NULL = default 1.0 priceCents: type: number nullable: true description: Price at time of order in cents. NULL = look up from variants table additionalProperties: true description: Item variants/modifications additionalProperties: true description: Items in this dispatch additionalProperties: true description: Kitchen dispatches (only in single table endpoint) notes: type: array items: type: object properties: uuid: type: string format: uuid description: Note UUID entityType: type: string enum: - tab - user description: Entity type (tab or user) entityId: type: string description: Entity ID (tab UUID or user ID) note: type: string description: Note content locationId: type: number description: Location ID sortOrder: type: number description: Sort order for display createdByRetailerUserId: type: number nullable: true description: Retailer user ID who created the note createdByName: type: string nullable: true description: Name of the user who created the note updatedByRetailerUserId: type: number nullable: true description: Retailer user ID who last updated the note updatedByName: type: string nullable: true description: Name of the user who last updated the note createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp additionalProperties: true description: Notes attached to this tab required: - id - state additionalProperties: true description: Active tabs on this table totalOrderAmountOnActiveTables: type: number description: Total order amount across active tabs totalPaidAmountOnActiveTables: type: number description: Total paid amount across active tabs isBookable: type: boolean description: Whether this table accepts bookings minCapacity: type: - "null" - number description: Minimum seating capacity maxCapacity: type: - "null" - number description: Maximum seating capacity seatingDurationMinutes: type: - "null" - number description: Per-table seating duration override (minutes) newTabPerGuest: type: boolean description: When true, every scan of this QR forces a brand-new tab instead of joining any existing open tab. Use for shared QRs at theme parks, festivals, multi-buyer kiosks, etc. requireGuestCount: type: boolean description: When true, the POS prompts for guest count when seating an empty table, instead of creating a tab silently. assignedRetailerUser: type: object nullable: true description: Server currently assigned to this table in POS (null when unassigned). properties: id: type: number name: type: - "null" - string color: type: - "null" - string description: Hex color (#RRGGBB) used by the staff badge. required: - id createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: - "null" - string format: date-time description: Last update timestamp required: - id - name - contextParams - locationId - status - activeTabs - createdAt - isBookable pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages required: - tables - pagination meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: summary: Create table tags: - Tables description: |- Create a new table **Permissions:** 🟢 `tables.create` requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 description: Table name/number description: type: string description: Table description locationId: type: number description: Location ID tableGroupId: type: number description: Table group ID costCenterId: type: number nullable: true description: Cost center ID contextParams: type: object additionalProperties: true description: Custom context parameters required: - name - locationId required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Unique table ID (UUID) name: type: string description: Table name/number description: type: string nullable: true description: Table description contextParams: type: object additionalProperties: true description: Custom context parameters locationId: type: number description: Location ID storefrontUrl: type: string format: uri nullable: true description: Full storefront URL for this table tableGroupId: type: number nullable: true description: Table group ID (if grouped) costCenterId: type: number nullable: true description: Cost center ID status: type: string enum: - live - paused - deleted description: Table status qrCodeImageUrl: type: string format: uri nullable: true description: QR code image URL activeTabs: type: array items: type: object properties: id: type: string description: Tab UUID state: type: string description: Tab state (started, initiated, etc.) orderTotal: type: number description: Total order amount in cents (legacy field) paidTotal: type: number description: Total paid amount in cents (legacy field) tipsTotal: type: number description: Total tips in cents selectedPaymentFlow: type: string nullable: true description: Selected payment flow coursingOrder: type: number nullable: true description: Current coursing level for the tab (items below this level cannot be sent) memberCount: type: number description: Number of tab_members on this tab (party size for walk-ins) totalAmountCents: type: number description: Total order amount in cents (from tabs table) paidAmountCents: type: number description: Total paid amount in cents (from tabs table) remainingBalanceCents: type: number description: Remaining balance in cents paymentMode: type: string enum: - ITEM - AMOUNT description: Payment mode storefrontQrCodeId: type: string format: uuid nullable: true description: Table/QR code UUID createdAt: type: string format: date-time description: Tab creation timestamp updatedAt: type: string format: date-time nullable: true description: Tab last update timestamp extras: type: array items: type: object additionalProperties: true description: Tab extras (only in single table endpoint) kitchenDispatches: type: array items: type: object properties: id: type: string description: Kitchen dispatch UUID createdAt: type: string format: date-time description: Creation timestamp dailyOrderNumber: type: number nullable: true description: Daily order number state: type: string description: Dispatch state tabUUID: type: string description: Tab UUID tabType: type: string description: Tab type (table, takeaway, etc.) tableName: type: string nullable: true description: Table name if applicable tabState: type: string description: Current tab state source: type: string nullable: true description: Source channel that created the dispatch (POS, QR, KIOSK, ONLINE, TAKEAWAY, MOVE, MERGE, SPLIT, SYSTEM) message: type: string nullable: true description: Optional contextual message (e.g., "Moved from Table 5") comments: type: array items: type: object properties: comment: type: string description: Comment text createdAt: type: string format: date-time description: Comment timestamp tabMemberUUID: type: string nullable: true description: Tab member UUID who made the comment uuid: type: string description: Comment UUID additionalProperties: true description: Dispatch comments kitchenDispatchItems: type: array items: type: object properties: id: type: string description: Kitchen dispatch item UUID itemId: type: number nullable: true description: Item ID from inventory saleItemId: type: number nullable: true description: Sale item ID price: type: number description: Item price in cents basePrice: type: number description: Base price before modifications quantityCents: type: number nullable: true description: Item quantity in cents (e.g., 100 = 1.0, 50 = 0.5) coursingOrder: type: number nullable: true description: Coursing level for this item (e.g., 1=appetizer, 2=main, 3=dessert) isNonSurplus: type: boolean description: Whether item is non-surplus settlementState: type: string nullable: true description: Settlement state itemState: type: string nullable: true description: Kitchen-side item state ('aborted' = voided) voidedQuantityCents: type: number nullable: true description: Voided slice in cents (read from platform_events) — null when not aborted title: type: string nullable: true description: Item title tabMember: type: object properties: uuid: type: string nullable: true description: Tab member UUID name: type: string description: Member name email: type: string description: Member email additionalProperties: true comments: type: array items: type: object properties: comment: type: string description: Comment text createdAt: type: string format: date-time description: Comment timestamp tabMemberUUID: type: string nullable: true description: Tab member UUID who made the comment uuid: type: string description: Comment UUID additionalProperties: true description: Item comments variants: type: array items: type: object properties: id: type: number description: Variant ID name: type: string description: Variant name price: type: number description: Variant price (positive or negative) quantityCents: type: number nullable: true description: Quantity in cents (100 = 1.0). NULL = default 1.0 priceCents: type: number nullable: true description: Price at time of order in cents. NULL = look up from variants table additionalProperties: true description: Item variants/modifications additionalProperties: true description: Items in this dispatch additionalProperties: true description: Kitchen dispatches (only in single table endpoint) notes: type: array items: type: object properties: uuid: type: string format: uuid description: Note UUID entityType: type: string enum: - tab - user description: Entity type (tab or user) entityId: type: string description: Entity ID (tab UUID or user ID) note: type: string description: Note content locationId: type: number description: Location ID sortOrder: type: number description: Sort order for display createdByRetailerUserId: type: number nullable: true description: Retailer user ID who created the note createdByName: type: string nullable: true description: Name of the user who created the note updatedByRetailerUserId: type: number nullable: true description: Retailer user ID who last updated the note updatedByName: type: string nullable: true description: Name of the user who last updated the note createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp additionalProperties: true description: Notes attached to this tab required: - id - state additionalProperties: true description: Active tabs on this table totalOrderAmountOnActiveTables: type: number description: Total order amount across active tabs totalPaidAmountOnActiveTables: type: number description: Total paid amount across active tabs isBookable: type: boolean description: Whether this table accepts bookings minCapacity: type: - "null" - number description: Minimum seating capacity maxCapacity: type: - "null" - number description: Maximum seating capacity seatingDurationMinutes: type: - "null" - number description: Per-table seating duration override (minutes) newTabPerGuest: type: boolean description: When true, every scan of this QR forces a brand-new tab instead of joining any existing open tab. Use for shared QRs at theme parks, festivals, multi-buyer kiosks, etc. requireGuestCount: type: boolean description: When true, the POS prompts for guest count when seating an empty table, instead of creating a tab silently. assignedRetailerUser: type: object nullable: true description: Server currently assigned to this table in POS (null when unassigned). properties: id: type: number name: type: - "null" - string color: type: - "null" - string description: Hex color (#RRGGBB) used by the staff badge. required: - id createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: - "null" - string format: date-time description: Last update timestamp required: - id - name - contextParams - locationId - status - activeTabs - createdAt - isBookable meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tables/{id}: get: summary: Get table details tags: - Tables description: |- Get a single table by ID with active tabs **Permissions:** 🔵 `tables.read` parameters: - schema: type: string format: uuid in: path name: id required: true description: Table UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Unique table ID (UUID) name: type: string description: Table name/number description: type: string nullable: true description: Table description contextParams: type: object additionalProperties: true description: Custom context parameters locationId: type: number description: Location ID storefrontUrl: type: string format: uri nullable: true description: Full storefront URL for this table tableGroupId: type: number nullable: true description: Table group ID (if grouped) costCenterId: type: number nullable: true description: Cost center ID status: type: string enum: - live - paused - deleted description: Table status qrCodeImageUrl: type: string format: uri nullable: true description: QR code image URL activeTabs: type: array items: type: object properties: id: type: string description: Tab UUID state: type: string description: Tab state (started, initiated, etc.) orderTotal: type: number description: Total order amount in cents (legacy field) paidTotal: type: number description: Total paid amount in cents (legacy field) tipsTotal: type: number description: Total tips in cents selectedPaymentFlow: type: string nullable: true description: Selected payment flow coursingOrder: type: number nullable: true description: Current coursing level for the tab (items below this level cannot be sent) memberCount: type: number description: Number of tab_members on this tab (party size for walk-ins) totalAmountCents: type: number description: Total order amount in cents (from tabs table) paidAmountCents: type: number description: Total paid amount in cents (from tabs table) remainingBalanceCents: type: number description: Remaining balance in cents paymentMode: type: string enum: - ITEM - AMOUNT description: Payment mode storefrontQrCodeId: type: string format: uuid nullable: true description: Table/QR code UUID createdAt: type: string format: date-time description: Tab creation timestamp updatedAt: type: string format: date-time nullable: true description: Tab last update timestamp extras: type: array items: type: object additionalProperties: true description: Tab extras (only in single table endpoint) kitchenDispatches: type: array items: type: object properties: id: type: string description: Kitchen dispatch UUID createdAt: type: string format: date-time description: Creation timestamp dailyOrderNumber: type: number nullable: true description: Daily order number state: type: string description: Dispatch state tabUUID: type: string description: Tab UUID tabType: type: string description: Tab type (table, takeaway, etc.) tableName: type: string nullable: true description: Table name if applicable tabState: type: string description: Current tab state source: type: string nullable: true description: Source channel that created the dispatch (POS, QR, KIOSK, ONLINE, TAKEAWAY, MOVE, MERGE, SPLIT, SYSTEM) message: type: string nullable: true description: Optional contextual message (e.g., "Moved from Table 5") comments: type: array items: type: object properties: comment: type: string description: Comment text createdAt: type: string format: date-time description: Comment timestamp tabMemberUUID: type: string nullable: true description: Tab member UUID who made the comment uuid: type: string description: Comment UUID additionalProperties: true description: Dispatch comments kitchenDispatchItems: type: array items: type: object properties: id: type: string description: Kitchen dispatch item UUID itemId: type: number nullable: true description: Item ID from inventory saleItemId: type: number nullable: true description: Sale item ID price: type: number description: Item price in cents basePrice: type: number description: Base price before modifications quantityCents: type: number nullable: true description: Item quantity in cents (e.g., 100 = 1.0, 50 = 0.5) coursingOrder: type: number nullable: true description: Coursing level for this item (e.g., 1=appetizer, 2=main, 3=dessert) isNonSurplus: type: boolean description: Whether item is non-surplus settlementState: type: string nullable: true description: Settlement state itemState: type: string nullable: true description: Kitchen-side item state ('aborted' = voided) voidedQuantityCents: type: number nullable: true description: Voided slice in cents (read from platform_events) — null when not aborted title: type: string nullable: true description: Item title tabMember: type: object properties: uuid: type: string nullable: true description: Tab member UUID name: type: string description: Member name email: type: string description: Member email additionalProperties: true comments: type: array items: type: object properties: comment: type: string description: Comment text createdAt: type: string format: date-time description: Comment timestamp tabMemberUUID: type: string nullable: true description: Tab member UUID who made the comment uuid: type: string description: Comment UUID additionalProperties: true description: Item comments variants: type: array items: type: object properties: id: type: number description: Variant ID name: type: string description: Variant name price: type: number description: Variant price (positive or negative) quantityCents: type: number nullable: true description: Quantity in cents (100 = 1.0). NULL = default 1.0 priceCents: type: number nullable: true description: Price at time of order in cents. NULL = look up from variants table additionalProperties: true description: Item variants/modifications additionalProperties: true description: Items in this dispatch additionalProperties: true description: Kitchen dispatches (only in single table endpoint) notes: type: array items: type: object properties: uuid: type: string format: uuid description: Note UUID entityType: type: string enum: - tab - user description: Entity type (tab or user) entityId: type: string description: Entity ID (tab UUID or user ID) note: type: string description: Note content locationId: type: number description: Location ID sortOrder: type: number description: Sort order for display createdByRetailerUserId: type: number nullable: true description: Retailer user ID who created the note createdByName: type: string nullable: true description: Name of the user who created the note updatedByRetailerUserId: type: number nullable: true description: Retailer user ID who last updated the note updatedByName: type: string nullable: true description: Name of the user who last updated the note createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp additionalProperties: true description: Notes attached to this tab required: - id - state additionalProperties: true description: Active tabs on this table totalOrderAmountOnActiveTables: type: number description: Total order amount across active tabs totalPaidAmountOnActiveTables: type: number description: Total paid amount across active tabs isBookable: type: boolean description: Whether this table accepts bookings minCapacity: type: - "null" - number description: Minimum seating capacity maxCapacity: type: - "null" - number description: Maximum seating capacity seatingDurationMinutes: type: - "null" - number description: Per-table seating duration override (minutes) newTabPerGuest: type: boolean description: When true, every scan of this QR forces a brand-new tab instead of joining any existing open tab. Use for shared QRs at theme parks, festivals, multi-buyer kiosks, etc. requireGuestCount: type: boolean description: When true, the POS prompts for guest count when seating an empty table, instead of creating a tab silently. assignedRetailerUser: type: object nullable: true description: Server currently assigned to this table in POS (null when unassigned). properties: id: type: number name: type: - "null" - string color: type: - "null" - string description: Hex color (#RRGGBB) used by the staff badge. required: - id createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: - "null" - string format: date-time description: Last update timestamp required: - id - name - contextParams - locationId - status - activeTabs - createdAt - isBookable meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: summary: Update table tags: - Tables description: |- Update an existing table **Permissions:** 🟠 `tables.update` requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 description: type: string nullable: true tableGroupId: type: number nullable: true costCenterId: type: number nullable: true description: Cost center ID status: type: string enum: - live - paused - deleted contextParams: type: object additionalProperties: true isBookable: type: boolean minCapacity: type: - number - "null" maxCapacity: type: - number - "null" seatingDurationMinutes: type: - number - "null" newTabPerGuest: type: boolean description: Force a new tab on every scan (theme parks, festivals, shared kiosks). requireGuestCount: type: boolean description: Prompt POS staff for guest count when seating an empty table. assignedRetailerUserId: type: - number - "null" description: Server (retailer_user) to assign to this table. Pass null to clear. Must reference an active retailer_user with access to this location. parameters: - schema: type: string format: uuid in: path name: id required: true description: Table UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string format: uuid description: Unique table ID (UUID) name: type: string description: Table name/number description: type: string nullable: true description: Table description contextParams: type: object additionalProperties: true description: Custom context parameters locationId: type: number description: Location ID storefrontUrl: type: string format: uri nullable: true description: Full storefront URL for this table tableGroupId: type: number nullable: true description: Table group ID (if grouped) costCenterId: type: number nullable: true description: Cost center ID status: type: string enum: - live - paused - deleted description: Table status qrCodeImageUrl: type: string format: uri nullable: true description: QR code image URL activeTabs: type: array items: type: object properties: id: type: string description: Tab UUID state: type: string description: Tab state (started, initiated, etc.) orderTotal: type: number description: Total order amount in cents (legacy field) paidTotal: type: number description: Total paid amount in cents (legacy field) tipsTotal: type: number description: Total tips in cents selectedPaymentFlow: type: string nullable: true description: Selected payment flow coursingOrder: type: number nullable: true description: Current coursing level for the tab (items below this level cannot be sent) memberCount: type: number description: Number of tab_members on this tab (party size for walk-ins) totalAmountCents: type: number description: Total order amount in cents (from tabs table) paidAmountCents: type: number description: Total paid amount in cents (from tabs table) remainingBalanceCents: type: number description: Remaining balance in cents paymentMode: type: string enum: - ITEM - AMOUNT description: Payment mode storefrontQrCodeId: type: string format: uuid nullable: true description: Table/QR code UUID createdAt: type: string format: date-time description: Tab creation timestamp updatedAt: type: string format: date-time nullable: true description: Tab last update timestamp extras: type: array items: type: object additionalProperties: true description: Tab extras (only in single table endpoint) kitchenDispatches: type: array items: type: object properties: id: type: string description: Kitchen dispatch UUID createdAt: type: string format: date-time description: Creation timestamp dailyOrderNumber: type: number nullable: true description: Daily order number state: type: string description: Dispatch state tabUUID: type: string description: Tab UUID tabType: type: string description: Tab type (table, takeaway, etc.) tableName: type: string nullable: true description: Table name if applicable tabState: type: string description: Current tab state source: type: string nullable: true description: Source channel that created the dispatch (POS, QR, KIOSK, ONLINE, TAKEAWAY, MOVE, MERGE, SPLIT, SYSTEM) message: type: string nullable: true description: Optional contextual message (e.g., "Moved from Table 5") comments: type: array items: type: object properties: comment: type: string description: Comment text createdAt: type: string format: date-time description: Comment timestamp tabMemberUUID: type: string nullable: true description: Tab member UUID who made the comment uuid: type: string description: Comment UUID additionalProperties: true description: Dispatch comments kitchenDispatchItems: type: array items: type: object properties: id: type: string description: Kitchen dispatch item UUID itemId: type: number nullable: true description: Item ID from inventory saleItemId: type: number nullable: true description: Sale item ID price: type: number description: Item price in cents basePrice: type: number description: Base price before modifications quantityCents: type: number nullable: true description: Item quantity in cents (e.g., 100 = 1.0, 50 = 0.5) coursingOrder: type: number nullable: true description: Coursing level for this item (e.g., 1=appetizer, 2=main, 3=dessert) isNonSurplus: type: boolean description: Whether item is non-surplus settlementState: type: string nullable: true description: Settlement state itemState: type: string nullable: true description: Kitchen-side item state ('aborted' = voided) voidedQuantityCents: type: number nullable: true description: Voided slice in cents (read from platform_events) — null when not aborted title: type: string nullable: true description: Item title tabMember: type: object properties: uuid: type: string nullable: true description: Tab member UUID name: type: string description: Member name email: type: string description: Member email additionalProperties: true comments: type: array items: type: object properties: comment: type: string description: Comment text createdAt: type: string format: date-time description: Comment timestamp tabMemberUUID: type: string nullable: true description: Tab member UUID who made the comment uuid: type: string description: Comment UUID additionalProperties: true description: Item comments variants: type: array items: type: object properties: id: type: number description: Variant ID name: type: string description: Variant name price: type: number description: Variant price (positive or negative) quantityCents: type: number nullable: true description: Quantity in cents (100 = 1.0). NULL = default 1.0 priceCents: type: number nullable: true description: Price at time of order in cents. NULL = look up from variants table additionalProperties: true description: Item variants/modifications additionalProperties: true description: Items in this dispatch additionalProperties: true description: Kitchen dispatches (only in single table endpoint) notes: type: array items: type: object properties: uuid: type: string format: uuid description: Note UUID entityType: type: string enum: - tab - user description: Entity type (tab or user) entityId: type: string description: Entity ID (tab UUID or user ID) note: type: string description: Note content locationId: type: number description: Location ID sortOrder: type: number description: Sort order for display createdByRetailerUserId: type: number nullable: true description: Retailer user ID who created the note createdByName: type: string nullable: true description: Name of the user who created the note updatedByRetailerUserId: type: number nullable: true description: Retailer user ID who last updated the note updatedByName: type: string nullable: true description: Name of the user who last updated the note createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp additionalProperties: true description: Notes attached to this tab required: - id - state additionalProperties: true description: Active tabs on this table totalOrderAmountOnActiveTables: type: number description: Total order amount across active tabs totalPaidAmountOnActiveTables: type: number description: Total paid amount across active tabs isBookable: type: boolean description: Whether this table accepts bookings minCapacity: type: - "null" - number description: Minimum seating capacity maxCapacity: type: - "null" - number description: Maximum seating capacity seatingDurationMinutes: type: - "null" - number description: Per-table seating duration override (minutes) newTabPerGuest: type: boolean description: When true, every scan of this QR forces a brand-new tab instead of joining any existing open tab. Use for shared QRs at theme parks, festivals, multi-buyer kiosks, etc. requireGuestCount: type: boolean description: When true, the POS prompts for guest count when seating an empty table, instead of creating a tab silently. assignedRetailerUser: type: object nullable: true description: Server currently assigned to this table in POS (null when unassigned). properties: id: type: number name: type: - "null" - string color: type: - "null" - string description: Hex color (#RRGGBB) used by the staff badge. required: - id createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: - "null" - string format: date-time description: Last update timestamp required: - id - name - contextParams - locationId - status - activeTabs - createdAt - isBookable meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete table tags: - Tables description: |- Delete a table (soft delete - sets status to deleted) **Permissions:** 🔴 `tables.delete` parameters: - schema: type: string format: uuid in: path name: id required: true description: Table UUID responses: "200": description: Table successfully deleted content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: deleted: type: boolean meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tables/bulk: put: summary: Bulk update tables tags: - Tables description: >- Update multiple tables in a single request. Apply the same changes to all specified tables. **Permissions:** 🟠 `tables.update` requestBody: content: application/json: schema: type: object properties: tableIds: type: array items: type: string format: uuid minItems: 1 description: Array of table UUIDs to update tableGroupId: type: number nullable: true description: Table group ID to assign (null to remove from group) contextParamsToMerge: type: object additionalProperties: true description: Context parameters to merge into existing params contextParamsToDelete: type: array items: type: string description: Context parameter keys to delete status: type: string enum: - live - paused - deleted description: Status to set on all tables required: - tableIds required: true responses: "200": description: Tables updated successfully content: application/json: schema: description: Tables updated successfully type: object properties: status: type: string enum: - success data: type: array items: type: object properties: id: type: string format: uuid description: Unique table ID (UUID) name: type: string description: Table name/number description: type: string nullable: true description: Table description contextParams: type: object additionalProperties: true description: Custom context parameters locationId: type: number description: Location ID storefrontUrl: type: string format: uri nullable: true description: Full storefront URL for this table tableGroupId: type: number nullable: true description: Table group ID (if grouped) costCenterId: type: number nullable: true description: Cost center ID status: type: string enum: - live - paused - deleted description: Table status qrCodeImageUrl: type: string format: uri nullable: true description: QR code image URL activeTabs: type: array items: type: object properties: id: type: string description: Tab UUID state: type: string description: Tab state (started, initiated, etc.) orderTotal: type: number description: Total order amount in cents (legacy field) paidTotal: type: number description: Total paid amount in cents (legacy field) tipsTotal: type: number description: Total tips in cents selectedPaymentFlow: type: string nullable: true description: Selected payment flow coursingOrder: type: number nullable: true description: Current coursing level for the tab (items below this level cannot be sent) memberCount: type: number description: Number of tab_members on this tab (party size for walk-ins) totalAmountCents: type: number description: Total order amount in cents (from tabs table) paidAmountCents: type: number description: Total paid amount in cents (from tabs table) remainingBalanceCents: type: number description: Remaining balance in cents paymentMode: type: string enum: - ITEM - AMOUNT description: Payment mode storefrontQrCodeId: type: string format: uuid nullable: true description: Table/QR code UUID createdAt: type: string format: date-time description: Tab creation timestamp updatedAt: type: string format: date-time nullable: true description: Tab last update timestamp extras: type: array items: type: object additionalProperties: true description: Tab extras (only in single table endpoint) kitchenDispatches: type: array items: type: object properties: id: type: string description: Kitchen dispatch UUID createdAt: type: string format: date-time description: Creation timestamp dailyOrderNumber: type: number nullable: true description: Daily order number state: type: string description: Dispatch state tabUUID: type: string description: Tab UUID tabType: type: string description: Tab type (table, takeaway, etc.) tableName: type: string nullable: true description: Table name if applicable tabState: type: string description: Current tab state source: type: string nullable: true description: Source channel that created the dispatch (POS, QR, KIOSK, ONLINE, TAKEAWAY, MOVE, MERGE, SPLIT, SYSTEM) message: type: string nullable: true description: Optional contextual message (e.g., "Moved from Table 5") comments: type: array items: type: object properties: comment: type: string description: Comment text createdAt: type: string format: date-time description: Comment timestamp tabMemberUUID: type: string nullable: true description: Tab member UUID who made the comment uuid: type: string description: Comment UUID additionalProperties: true description: Dispatch comments kitchenDispatchItems: type: array items: type: object properties: id: type: string description: Kitchen dispatch item UUID itemId: type: number nullable: true description: Item ID from inventory saleItemId: type: number nullable: true description: Sale item ID price: type: number description: Item price in cents basePrice: type: number description: Base price before modifications quantityCents: type: number nullable: true description: Item quantity in cents (e.g., 100 = 1.0, 50 = 0.5) coursingOrder: type: number nullable: true description: Coursing level for this item (e.g., 1=appetizer, 2=main, 3=dessert) isNonSurplus: type: boolean description: Whether item is non-surplus settlementState: type: string nullable: true description: Settlement state itemState: type: string nullable: true description: Kitchen-side item state ('aborted' = voided) voidedQuantityCents: type: number nullable: true description: Voided slice in cents (read from platform_events) — null when not aborted title: type: string nullable: true description: Item title tabMember: type: object properties: uuid: type: string nullable: true description: Tab member UUID name: type: string description: Member name email: type: string description: Member email additionalProperties: true comments: type: array items: type: object properties: comment: type: string description: Comment text createdAt: type: string format: date-time description: Comment timestamp tabMemberUUID: type: string nullable: true description: Tab member UUID who made the comment uuid: type: string description: Comment UUID additionalProperties: true description: Item comments variants: type: array items: type: object properties: id: type: number description: Variant ID name: type: string description: Variant name price: type: number description: Variant price (positive or negative) quantityCents: type: number nullable: true description: Quantity in cents (100 = 1.0). NULL = default 1.0 priceCents: type: number nullable: true description: Price at time of order in cents. NULL = look up from variants table additionalProperties: true description: Item variants/modifications additionalProperties: true description: Items in this dispatch additionalProperties: true description: Kitchen dispatches (only in single table endpoint) notes: type: array items: type: object properties: uuid: type: string format: uuid description: Note UUID entityType: type: string enum: - tab - user description: Entity type (tab or user) entityId: type: string description: Entity ID (tab UUID or user ID) note: type: string description: Note content locationId: type: number description: Location ID sortOrder: type: number description: Sort order for display createdByRetailerUserId: type: number nullable: true description: Retailer user ID who created the note createdByName: type: string nullable: true description: Name of the user who created the note updatedByRetailerUserId: type: number nullable: true description: Retailer user ID who last updated the note updatedByName: type: string nullable: true description: Name of the user who last updated the note createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp additionalProperties: true description: Notes attached to this tab required: - id - state additionalProperties: true description: Active tabs on this table totalOrderAmountOnActiveTables: type: number description: Total order amount across active tabs totalPaidAmountOnActiveTables: type: number description: Total paid amount across active tabs isBookable: type: boolean description: Whether this table accepts bookings minCapacity: type: - "null" - number description: Minimum seating capacity maxCapacity: type: - "null" - number description: Maximum seating capacity seatingDurationMinutes: type: - "null" - number description: Per-table seating duration override (minutes) newTabPerGuest: type: boolean description: When true, every scan of this QR forces a brand-new tab instead of joining any existing open tab. Use for shared QRs at theme parks, festivals, multi-buyer kiosks, etc. requireGuestCount: type: boolean description: When true, the POS prompts for guest count when seating an empty table, instead of creating a tab silently. assignedRetailerUser: type: object nullable: true description: Server currently assigned to this table in POS (null when unassigned). properties: id: type: number name: type: - "null" - string color: type: - "null" - string description: Hex color (#RRGGBB) used by the staff badge. required: - id createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: - "null" - string format: date-time description: Last update timestamp required: - id - name - contextParams - locationId - status - activeTabs - createdAt - isBookable description: Updated tables meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tab/{tabId}/payment-methods: get: summary: Get Adyen payment methods tags: - Tabs description: Returns available Adyen payment methods for the Advanced flow. No purchase is created. parameters: - schema: type: number minimum: 0 in: query name: amountCents required: true description: "Payment amount in cents. 0 is a valid value: the storefront still hits this endpoint when the cart nets to 0 (voucher fully covers the order) and the handler short-circuits with an empty paymentMethodsResponse so the drawer can route to the complimentary settlement path without a PSP method selection." - schema: type: string in: query name: currencyCode required: true description: ISO 4217 currency code (e.g. SEK, EUR) - schema: type: string in: query name: countryCode required: false description: ISO 3166-1 alpha-2 country code (e.g. SE, NL) - schema: type: string format: uuid in: query name: tabMemberId required: false description: Optional tab member UUID. When supplied, the handler resolves the paying user and includes a shopperReference so Adyen returns storedPaymentMethods (saved cards) for the shopper. Omit for guest checkouts. - schema: type: string format: uuid in: path name: tabId required: true description: Tab UUID responses: "200": description: Payment methods fetched successfully content: application/json: schema: description: Payment methods fetched successfully type: object properties: status: type: string enum: - success data: type: object additionalProperties: true properties: paymentMethodsResponse: type: object additionalProperties: true description: Adyen paymentMethodsResponse object clientKey: type: string description: Adyen client key for Drop-in/Components environment: type: string enum: - test - live description: Adyen environment freeOrder: type: boolean description: True when amountCents=0 and no PSP picker is needed — drawer should auto-submit the intent for complimentary settlement. meta: type: object "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tab/cancel: post: summary: Cancel tab payment tags: - Tabs description: |- Cancel a pending tab payment by purchase intent ID **Permissions:** 🟠 `tabs.update` requestBody: content: application/json: schema: type: object required: - purchase_intent_id properties: purchase_intent_id: type: string format: uuid description: Purchase intent ID to cancel required: true responses: "200": description: Payment canceled successfully content: application/json: schema: description: Payment canceled successfully type: object properties: status: type: string enum: - success data: type: object properties: purchase_intent_id: type: string format: uuid tab_settlement_id: type: string format: uuid tab_id: type: string format: uuid canceled: type: boolean meta: type: object "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tab/cancel-all: post: summary: Cancel all tab payments tags: - Tabs description: |- Cancel all pending payments for a specific tab **Permissions:** 🟠 `tabs.update` requestBody: content: application/json: schema: type: object required: - tab_id properties: tab_id: type: string format: uuid description: Tab ID to cancel all payments for required: true responses: "200": description: All payments canceled successfully content: application/json: schema: description: All payments canceled successfully type: object properties: status: type: string enum: - success data: type: object properties: tab_id: type: string format: uuid canceled_count: type: number purchase_intent_ids: type: array items: type: string format: uuid meta: type: object "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tab/pay: post: summary: Pay for tab tags: - Tabs description: |- Process a payment for a tab using various payment methods **Permissions:** 🟠 `tabs.update` requestBody: content: application/json: schema: type: object required: - tab_id - payment_method properties: tab_id: type: string format: uuid description: UUID of the tab to pay for tab_member_id: type: string description: ID of the tab member making the payment (UUID). Optional - will be auto-resolved from JWT token if not provided. payment_method: type: string enum: - prepaid - invoice - swish - terminal - online - gift_card description: Payment method to use kitchen_dispatch_items: type: array items: type: string format: uuid description: Array of kitchen dispatch item IDs to pay for (ITEM mode) amount_cents: type: number minimum: 0 description: Amount to pay in cents (AMOUNT mode or triggers mode switch) terminal_id: type: string format: uuid description: Terminal ID (required for terminal payments) return_url: type: string format: uri description: Return URL after payment (required for online/swish payments) tip_amount_cents: type: number minimum: 0 default: 0 description: Tip amount in cents metadata: type: object description: Additional metadata for the payment voucher_codes: type: array items: type: string description: Voucher codes to apply to the payment recipient_id: type: string format: uuid description: Invoice recipient UUID (for invoice payments) gift_card_code: type: string description: "Gift card code for gift_card payment method (format: XXXX-XXXX-XXXX)" payment_data: type: object additionalProperties: true description: Adyen payment method data from Drop-in/Components (triggers Advanced flow when present) cancel_existing_payment: type: boolean description: "User confirmed: cancel the in-progress Adyen CS payment and start a new one" save_payment_method: type: boolean description: When true, persist the card token after Adyen Authorised so the user can re-use it. Default false. Honored when location has the instant_pay_v2 feature flag enabled. selected_saved_payment_method_id: type: string description: UUID of a previously saved payment method to charge. Forwarded to payment-service alongside the Adyen Advanced PSP payload. required: true responses: "200": description: Payment initiated successfully content: application/json: schema: description: Payment initiated successfully type: object properties: status: type: string enum: - success data: type: object properties: purchase_intent_id: type: string format: uuid tab_settlement_id: type: string format: uuid payment_method: type: string payment_mode: type: string enum: - ITEM - AMOUNT mode_switched: type: boolean terminal_id: type: string format: uuid nullable: true description: Terminal ID for cancel functionality complimentary: type: boolean description: True when the server converted a 0 kr terminal request into a complimentary prepaid purchase (voucher-covered tab). terminal_id will be null and the payment is already sync-confirmed — no terminal-awaiting UI or card receipt should be shown. psp_response: type: object additionalProperties: true properties: success: type: boolean message: type: string pspCheckoutResponse: type: object additionalProperties: true properties: providedKarmaRef: type: string pspInstruction: type: object additionalProperties: true properties: psp: type: string sessionData: type: string sessionId: type: string type: type: string pspPaymentRequestId: type: string checkoutUrl: type: string checkoutUrlFallback: type: object properties: purchaseIntentId: type: string qrCodeSvgBase64: type: string softpayRequestId: type: string nullable: true description: Softpay request ID for softpos terminal payments meta: type: object "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tab/pay/details: post: summary: Submit Adyen payment details tags: - Tabs description: Submit additional payment details (3DS, redirect) for an existing Adyen Advanced flow purchase. requestBody: content: application/json: schema: type: object required: - purchase_intent_id - details properties: purchase_intent_id: type: string format: uuid description: Purchase intent ID from the initial /tab/pay response details: type: object additionalProperties: true description: Adyen payment details object (from onAdditionalDetails callback) required: true responses: "200": description: Payment details processed successfully content: application/json: schema: description: Payment details processed successfully type: object properties: status: type: string enum: - success data: type: object properties: resultCode: type: string description: Adyen result code (Authorised, Refused, etc.) action: type: object additionalProperties: true nullable: true description: Additional action required (another 3DS step) pspReference: type: string nullable: true description: Adyen PSP reference meta: type: object "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tab/recalculate: post: summary: Recalculate tab balance tags: - Tabs description: >- Recalculate tab balance from source of truth (kitchen dispatch items and purchases). Useful for fixing tabs with incorrect balance values. **Permissions:** 🟠 `tabs.update` requestBody: content: application/json: schema: type: object required: - tab_id properties: tab_id: type: string format: uuid description: Tab ID to recalculate balance for required: true responses: "200": description: Tab balance recalculated successfully content: application/json: schema: description: Tab balance recalculated successfully type: object properties: status: type: string enum: - success data: type: object properties: tab_id: type: string format: uuid total_amount_cents: type: number description: Recalculated total amount from kitchen dispatch items paid_amount_cents: type: number description: Recalculated paid amount from purchases remaining_balance_cents: type: number description: Calculated remaining balance (total - paid) item_count: type: number description: Number of kitchen dispatch items found purchase_count: type: number description: Number of confirmed purchases found previous_total: type: number description: Previous total_amount_cents value previous_paid: type: number description: Previous paid_amount_cents value total_changed: type: boolean description: Whether total amount was changed paid_changed: type: boolean description: Whether paid amount was changed meta: type: object "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs: get: summary: List tabs tags: - Tabs description: |- List tabs with optional filtering **Permissions:** 🔵 `tabs.read` parameters: - schema: type: number in: query name: locationId required: false description: Filter by location ID - schema: type: string enum: - initiated - started - instant - closed - settled - aborted - action_required in: query name: state required: false description: Filter by tab state - schema: type: string in: query name: storefrontQrCodeId required: false description: Filter by table/QR code UUID - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: number minimum: 1 maximum: 100 default: 20 in: query name: limit required: false description: Items per page responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: tabs: type: array items: type: object properties: uuid: type: string format: uuid description: Tab UUID locationId: type: number description: Location ID latestState: type: string enum: - initiated - started - instant - closed - settled - aborted - action_required description: Current tab state selectedPaymentFlow: type: string nullable: true enum: - open_tab - pay_upfront description: "Payment flow (open_tab: pay later, pay_upfront: pay now/instant pay)" paymentMode: type: string enum: - ITEM - AMOUNT description: "Payment mode (ITEM: pay per item, AMOUNT: pay arbitrary amounts)" paymentSplit: type: number nullable: true minimum: 2 maximum: 10 description: Number of splits when in AMOUNT mode (2-10), null when in ITEM mode totalAmountCents: type: number description: Total order amount in cents paidAmountCents: type: number description: Total paid amount in cents remainingBalanceCents: type: number description: Remaining balance to be paid in cents storefrontQrCodeId: type: string nullable: true description: Table/QR code UUID if applicable bookingId: type: string format: uuid nullable: true description: UUID of the booking/reservation that created this tab, if any. Null for tabs not created from a reservation. bookingConfirmationCode: type: string nullable: true description: Confirmation code of the linked booking, when the tab is bound to one. Used by the storefront to deep-link back to the booking confirmation page. tabMembers: type: array items: type: object properties: uuid: type: string format: uuid description: Tab member UUID storefrontSessionId: type: string nullable: true description: Storefront session ID initiator: type: boolean description: Whether this member initiated the tab memberType: type: string description: Member type (guest, user, etc.) userId: type: number nullable: true description: User ID if authenticated retailUserId: type: number nullable: true description: Retail user ID if applicable clientId: type: string nullable: true description: Client identifier (user UUID for identification) userEmail: type: string nullable: true description: User email (canonical, never overridden per-location) userName: type: string nullable: true description: Override-merged display name (falls back through retailer.name → ulo.display_name → users.name) isEnrolledInLoyalty: type: boolean description: Whether user is enrolled in location loyalty program createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - initiator - memberType - isEnrolledInLoyalty - createdAt - updatedAt description: Tab members memberCount: type: number description: Number of guest tab_members (party size; excludes staff) kitchenDispatches: type: array items: type: object properties: uuid: type: string format: uuid description: Kitchen dispatch UUID tabId: type: string format: uuid description: Tab UUID locationId: type: number description: Location ID dailyOrderNumber: type: number nullable: true description: Daily order number latestState: type: string description: Current state of the dispatch createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp kitchenDispatchItems: type: array items: type: object properties: uuid: type: string format: uuid description: Kitchen dispatch item UUID kitchenDispatchId: type: string format: uuid description: Kitchen dispatch UUID saleItemId: type: number nullable: true description: Sale item ID itemId: type: number nullable: true description: Inventory item ID tabMemberId: type: string nullable: true description: Tab member UUID who ordered this parentKitchenDispatchItemId: type: string nullable: true description: Parent kitchen dispatch item UUID (for nested items) price: type: number description: Item price in cents basePrice: type: number description: Base price before modifications in cents discount: type: number nullable: true description: Discount amount in cents quantity: type: number description: Quantity ordered quantityCents: type: number nullable: true description: Quantity in cents (for fractional items) splitOfKdi: type: string format: uuid nullable: true description: UUID of original item if this is a split item (for grouping) tabSettlementId: type: string nullable: true description: Settlement UUID if paid settlementState: type: string nullable: true description: Settlement state (payment_in_progress, settled) status: type: string nullable: true description: Item status itemState: type: string nullable: true description: Kitchen-side item state ('aborted' = voided) voidedQuantityCents: type: number nullable: true description: Voided slice in cents (read from platform_events) — null when not aborted paidAmount: type: number nullable: true description: Amount paid for this item in cents createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp itemTitle: type: string nullable: true description: Item title from inventory itemTitlePrep: type: string nullable: true description: Item prep name from inventory itemDescription: type: string nullable: true description: Item description from inventory itemImageUrl: type: string nullable: true description: Item image URL from inventory tabMember: type: object nullable: true description: Guest/user information for the person who ordered this item properties: uuid: type: string format: uuid description: Tab member UUID name: type: string description: Member name email: type: string description: Member email phone: type: string description: Member phone number imageUrl: type: string description: Member profile image URL memberType: type: string description: Member type (guest, user, etc.) userId: type: number nullable: true description: User ID if authenticated user retailUserId: type: number nullable: true description: Retailer user ID if staff member comments: type: array description: Comments on this item items: type: object properties: comment: type: string createdAt: type: string format: date-time tabMemberUUID: type: string nullable: true uuid: type: string format: uuid variants: type: array description: Variants/modifications on this item items: type: object properties: id: type: number name: type: string price: type: number description: Price in cents (positive or negative) quantityCents: type: number nullable: true description: Quantity in cents (100 = 1.0). NULL = default 1.0 priceCents: type: number nullable: true description: Price at time of order in cents. NULL = look up from variants table required: - uuid - kitchenDispatchId - price - basePrice - quantity - createdAt - updatedAt description: Items in this dispatch required: - uuid - tabId - locationId - latestState - createdAt - updatedAt - kitchenDispatchItems description: Kitchen dispatches with items vouchers: type: array items: type: object properties: id: type: number description: tab_vouchers.id (use with DELETE /vouchers/applied/:id) discountId: type: number description: discounts.id discountCode: type: string description: Voucher code as entered appliedAt: type: string format: date-time voucherName: type: string nullable: true description: discounts.name (internal name) voucherType: type: string nullable: true typeSpecification: type: object nullable: true additionalProperties: true maxDiscountAmountCents: type: number nullable: true maxUses: type: number nullable: true timesUsed: type: number hasUsesLeft: type: boolean description: "Computed: maxUses null/0 OR timesUsed < maxUses" remainingBalanceCents: type: number nullable: true description: For gift cards displayTitle: type: string nullable: true description: Guest-facing title displayDescription: type: string nullable: true description: Guest-facing description displayImageUrl: type: string nullable: true description: Thumbnail URL required: - id - discountId - discountCode - appliedAt - timesUsed - hasUsesLeft description: Vouchers attached to this tab (from POS or storefront) notes: type: array items: type: object properties: uuid: type: string format: uuid description: Note UUID entityType: type: string description: Entity type (tab, user) entityId: type: string description: Entity ID (tab UUID or user ID) note: type: string description: Note content locationId: type: number description: Location ID sortOrder: type: number description: Sort order (0 = first/top) createdByRetailerUserId: type: number nullable: true description: Retailer user who created the note createdByName: type: string nullable: true description: Name of user who created the note updatedByRetailerUserId: type: number nullable: true description: Retailer user who last updated the note updatedByName: type: string nullable: true description: Name of user who last updated the note createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - entityType - entityId - note - locationId - sortOrder - createdAt - updatedAt description: Notes attached to this tab createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - locationId - latestState - paymentMode - totalAmountCents - paidAmountCents - remainingBalanceCents - tabMembers - createdAt - updatedAt pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages required: - tabs - pagination meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{id}: get: summary: Get tab details tags: - Tabs description: |- Get a single tab by ID with members and kitchen dispatch items **Permissions:** 🔵 `tabs.read` parameters: - schema: type: string format: uuid in: path name: id required: true description: Tab UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: uuid: type: string format: uuid description: Tab UUID locationId: type: number description: Location ID latestState: type: string enum: - initiated - started - instant - closed - settled - aborted - action_required description: Current tab state selectedPaymentFlow: type: string nullable: true enum: - open_tab - pay_upfront description: "Payment flow (open_tab: pay later, pay_upfront: pay now/instant pay)" paymentMode: type: string enum: - ITEM - AMOUNT description: "Payment mode (ITEM: pay per item, AMOUNT: pay arbitrary amounts)" paymentSplit: type: number nullable: true minimum: 2 maximum: 10 description: Number of splits when in AMOUNT mode (2-10), null when in ITEM mode totalAmountCents: type: number description: Total order amount in cents paidAmountCents: type: number description: Total paid amount in cents remainingBalanceCents: type: number description: Remaining balance to be paid in cents storefrontQrCodeId: type: string nullable: true description: Table/QR code UUID if applicable bookingId: type: string format: uuid nullable: true description: UUID of the booking/reservation that created this tab, if any. Null for tabs not created from a reservation. bookingConfirmationCode: type: string nullable: true description: Confirmation code of the linked booking, when the tab is bound to one. Used by the storefront to deep-link back to the booking confirmation page. tabMembers: type: array items: type: object properties: uuid: type: string format: uuid description: Tab member UUID storefrontSessionId: type: string nullable: true description: Storefront session ID initiator: type: boolean description: Whether this member initiated the tab memberType: type: string description: Member type (guest, user, etc.) userId: type: number nullable: true description: User ID if authenticated retailUserId: type: number nullable: true description: Retail user ID if applicable clientId: type: string nullable: true description: Client identifier (user UUID for identification) userEmail: type: string nullable: true description: User email (canonical, never overridden per-location) userName: type: string nullable: true description: Override-merged display name (falls back through retailer.name → ulo.display_name → users.name) isEnrolledInLoyalty: type: boolean description: Whether user is enrolled in location loyalty program createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - initiator - memberType - isEnrolledInLoyalty - createdAt - updatedAt description: Tab members memberCount: type: number description: Number of guest tab_members (party size; excludes staff) kitchenDispatches: type: array items: type: object properties: uuid: type: string format: uuid description: Kitchen dispatch UUID tabId: type: string format: uuid description: Tab UUID locationId: type: number description: Location ID dailyOrderNumber: type: number nullable: true description: Daily order number latestState: type: string description: Current state of the dispatch createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp kitchenDispatchItems: type: array items: type: object properties: uuid: type: string format: uuid description: Kitchen dispatch item UUID kitchenDispatchId: type: string format: uuid description: Kitchen dispatch UUID saleItemId: type: number nullable: true description: Sale item ID itemId: type: number nullable: true description: Inventory item ID tabMemberId: type: string nullable: true description: Tab member UUID who ordered this parentKitchenDispatchItemId: type: string nullable: true description: Parent kitchen dispatch item UUID (for nested items) price: type: number description: Item price in cents basePrice: type: number description: Base price before modifications in cents discount: type: number nullable: true description: Discount amount in cents quantity: type: number description: Quantity ordered quantityCents: type: number nullable: true description: Quantity in cents (for fractional items) splitOfKdi: type: string format: uuid nullable: true description: UUID of original item if this is a split item (for grouping) tabSettlementId: type: string nullable: true description: Settlement UUID if paid settlementState: type: string nullable: true description: Settlement state (payment_in_progress, settled) status: type: string nullable: true description: Item status itemState: type: string nullable: true description: Kitchen-side item state ('aborted' = voided) voidedQuantityCents: type: number nullable: true description: Voided slice in cents (read from platform_events) — null when not aborted paidAmount: type: number nullable: true description: Amount paid for this item in cents createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp itemTitle: type: string nullable: true description: Item title from inventory itemTitlePrep: type: string nullable: true description: Item prep name from inventory itemDescription: type: string nullable: true description: Item description from inventory itemImageUrl: type: string nullable: true description: Item image URL from inventory tabMember: type: object nullable: true description: Guest/user information for the person who ordered this item properties: uuid: type: string format: uuid description: Tab member UUID name: type: string description: Member name email: type: string description: Member email phone: type: string description: Member phone number imageUrl: type: string description: Member profile image URL memberType: type: string description: Member type (guest, user, etc.) userId: type: number nullable: true description: User ID if authenticated user retailUserId: type: number nullable: true description: Retailer user ID if staff member comments: type: array description: Comments on this item items: type: object properties: comment: type: string createdAt: type: string format: date-time tabMemberUUID: type: string nullable: true uuid: type: string format: uuid variants: type: array description: Variants/modifications on this item items: type: object properties: id: type: number name: type: string price: type: number description: Price in cents (positive or negative) quantityCents: type: number nullable: true description: Quantity in cents (100 = 1.0). NULL = default 1.0 priceCents: type: number nullable: true description: Price at time of order in cents. NULL = look up from variants table required: - uuid - kitchenDispatchId - price - basePrice - quantity - createdAt - updatedAt description: Items in this dispatch required: - uuid - tabId - locationId - latestState - createdAt - updatedAt - kitchenDispatchItems description: Kitchen dispatches with items vouchers: type: array items: type: object properties: id: type: number description: tab_vouchers.id (use with DELETE /vouchers/applied/:id) discountId: type: number description: discounts.id discountCode: type: string description: Voucher code as entered appliedAt: type: string format: date-time voucherName: type: string nullable: true description: discounts.name (internal name) voucherType: type: string nullable: true typeSpecification: type: object nullable: true additionalProperties: true maxDiscountAmountCents: type: number nullable: true maxUses: type: number nullable: true timesUsed: type: number hasUsesLeft: type: boolean description: "Computed: maxUses null/0 OR timesUsed < maxUses" remainingBalanceCents: type: number nullable: true description: For gift cards displayTitle: type: string nullable: true description: Guest-facing title displayDescription: type: string nullable: true description: Guest-facing description displayImageUrl: type: string nullable: true description: Thumbnail URL required: - id - discountId - discountCode - appliedAt - timesUsed - hasUsesLeft description: Vouchers attached to this tab (from POS or storefront) notes: type: array items: type: object properties: uuid: type: string format: uuid description: Note UUID entityType: type: string description: Entity type (tab, user) entityId: type: string description: Entity ID (tab UUID or user ID) note: type: string description: Note content locationId: type: number description: Location ID sortOrder: type: number description: Sort order (0 = first/top) createdByRetailerUserId: type: number nullable: true description: Retailer user who created the note createdByName: type: string nullable: true description: Name of user who created the note updatedByRetailerUserId: type: number nullable: true description: Retailer user who last updated the note updatedByName: type: string nullable: true description: Name of user who last updated the note createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - entityType - entityId - note - locationId - sortOrder - createdAt - updatedAt description: Notes attached to this tab createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - locationId - latestState - paymentMode - totalAmountCents - paidAmountCents - remainingBalanceCents - tabMembers - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{id}/close: post: summary: Close a tab tags: - Tabs description: >- Close a tab by setting its state to closed or aborted. Use force=true to close any tab regardless of state. **Permissions:** 🟠 `tabs.update` requestBody: content: application/json: schema: type: object properties: comment: type: string description: Optional comment explaining why the tab is being closed force: type: boolean description: If true, forces the tab to close (state becomes "aborted"). If false, normal close (state becomes "closed") and only works on non-closed tabs default: false parameters: - schema: type: string format: uuid in: path name: id required: true description: Tab UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: uuid: type: string format: uuid description: Tab UUID locationId: type: number description: Location ID latestState: type: string enum: - initiated - started - instant - closed - settled - aborted - action_required description: Current tab state selectedPaymentFlow: type: string nullable: true enum: - open_tab - pay_upfront description: "Payment flow (open_tab: pay later, pay_upfront: pay now/instant pay)" paymentMode: type: string enum: - ITEM - AMOUNT description: "Payment mode (ITEM: pay per item, AMOUNT: pay arbitrary amounts)" paymentSplit: type: number nullable: true minimum: 2 maximum: 10 description: Number of splits when in AMOUNT mode (2-10), null when in ITEM mode totalAmountCents: type: number description: Total order amount in cents paidAmountCents: type: number description: Total paid amount in cents remainingBalanceCents: type: number description: Remaining balance to be paid in cents storefrontQrCodeId: type: string nullable: true description: Table/QR code UUID if applicable bookingId: type: string format: uuid nullable: true description: UUID of the booking/reservation that created this tab, if any. Null for tabs not created from a reservation. bookingConfirmationCode: type: string nullable: true description: Confirmation code of the linked booking, when the tab is bound to one. Used by the storefront to deep-link back to the booking confirmation page. tabMembers: type: array items: type: object properties: uuid: type: string format: uuid description: Tab member UUID storefrontSessionId: type: string nullable: true description: Storefront session ID initiator: type: boolean description: Whether this member initiated the tab memberType: type: string description: Member type (guest, user, etc.) userId: type: number nullable: true description: User ID if authenticated retailUserId: type: number nullable: true description: Retail user ID if applicable clientId: type: string nullable: true description: Client identifier (user UUID for identification) userEmail: type: string nullable: true description: User email (canonical, never overridden per-location) userName: type: string nullable: true description: Override-merged display name (falls back through retailer.name → ulo.display_name → users.name) isEnrolledInLoyalty: type: boolean description: Whether user is enrolled in location loyalty program createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - initiator - memberType - isEnrolledInLoyalty - createdAt - updatedAt description: Tab members memberCount: type: number description: Number of guest tab_members (party size; excludes staff) kitchenDispatches: type: array items: type: object properties: uuid: type: string format: uuid description: Kitchen dispatch UUID tabId: type: string format: uuid description: Tab UUID locationId: type: number description: Location ID dailyOrderNumber: type: number nullable: true description: Daily order number latestState: type: string description: Current state of the dispatch createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp kitchenDispatchItems: type: array items: type: object properties: uuid: type: string format: uuid description: Kitchen dispatch item UUID kitchenDispatchId: type: string format: uuid description: Kitchen dispatch UUID saleItemId: type: number nullable: true description: Sale item ID itemId: type: number nullable: true description: Inventory item ID tabMemberId: type: string nullable: true description: Tab member UUID who ordered this parentKitchenDispatchItemId: type: string nullable: true description: Parent kitchen dispatch item UUID (for nested items) price: type: number description: Item price in cents basePrice: type: number description: Base price before modifications in cents discount: type: number nullable: true description: Discount amount in cents quantity: type: number description: Quantity ordered quantityCents: type: number nullable: true description: Quantity in cents (for fractional items) splitOfKdi: type: string format: uuid nullable: true description: UUID of original item if this is a split item (for grouping) tabSettlementId: type: string nullable: true description: Settlement UUID if paid settlementState: type: string nullable: true description: Settlement state (payment_in_progress, settled) status: type: string nullable: true description: Item status itemState: type: string nullable: true description: Kitchen-side item state ('aborted' = voided) voidedQuantityCents: type: number nullable: true description: Voided slice in cents (read from platform_events) — null when not aborted paidAmount: type: number nullable: true description: Amount paid for this item in cents createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp itemTitle: type: string nullable: true description: Item title from inventory itemTitlePrep: type: string nullable: true description: Item prep name from inventory itemDescription: type: string nullable: true description: Item description from inventory itemImageUrl: type: string nullable: true description: Item image URL from inventory tabMember: type: object nullable: true description: Guest/user information for the person who ordered this item properties: uuid: type: string format: uuid description: Tab member UUID name: type: string description: Member name email: type: string description: Member email phone: type: string description: Member phone number imageUrl: type: string description: Member profile image URL memberType: type: string description: Member type (guest, user, etc.) userId: type: number nullable: true description: User ID if authenticated user retailUserId: type: number nullable: true description: Retailer user ID if staff member comments: type: array description: Comments on this item items: type: object properties: comment: type: string createdAt: type: string format: date-time tabMemberUUID: type: string nullable: true uuid: type: string format: uuid variants: type: array description: Variants/modifications on this item items: type: object properties: id: type: number name: type: string price: type: number description: Price in cents (positive or negative) quantityCents: type: number nullable: true description: Quantity in cents (100 = 1.0). NULL = default 1.0 priceCents: type: number nullable: true description: Price at time of order in cents. NULL = look up from variants table required: - uuid - kitchenDispatchId - price - basePrice - quantity - createdAt - updatedAt description: Items in this dispatch required: - uuid - tabId - locationId - latestState - createdAt - updatedAt - kitchenDispatchItems description: Kitchen dispatches with items vouchers: type: array items: type: object properties: id: type: number description: tab_vouchers.id (use with DELETE /vouchers/applied/:id) discountId: type: number description: discounts.id discountCode: type: string description: Voucher code as entered appliedAt: type: string format: date-time voucherName: type: string nullable: true description: discounts.name (internal name) voucherType: type: string nullable: true typeSpecification: type: object nullable: true additionalProperties: true maxDiscountAmountCents: type: number nullable: true maxUses: type: number nullable: true timesUsed: type: number hasUsesLeft: type: boolean description: "Computed: maxUses null/0 OR timesUsed < maxUses" remainingBalanceCents: type: number nullable: true description: For gift cards displayTitle: type: string nullable: true description: Guest-facing title displayDescription: type: string nullable: true description: Guest-facing description displayImageUrl: type: string nullable: true description: Thumbnail URL required: - id - discountId - discountCode - appliedAt - timesUsed - hasUsesLeft description: Vouchers attached to this tab (from POS or storefront) notes: type: array items: type: object properties: uuid: type: string format: uuid description: Note UUID entityType: type: string description: Entity type (tab, user) entityId: type: string description: Entity ID (tab UUID or user ID) note: type: string description: Note content locationId: type: number description: Location ID sortOrder: type: number description: Sort order (0 = first/top) createdByRetailerUserId: type: number nullable: true description: Retailer user who created the note createdByName: type: string nullable: true description: Name of user who created the note updatedByRetailerUserId: type: number nullable: true description: Retailer user who last updated the note updatedByName: type: string nullable: true description: Name of user who last updated the note createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - entityType - entityId - note - locationId - sortOrder - createdAt - updatedAt description: Notes attached to this tab createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - locationId - latestState - paymentMode - totalAmountCents - paidAmountCents - remainingBalanceCents - tabMembers - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{id}/coursing: patch: summary: Advance tab coursing tags: - Tabs description: >- Advance the coursing order for a tab. If coursingOrder is provided in the body, sets to that specific value. Otherwise, advances to the next available coursing level from the location's coursings. Used for POS coursing feature to control when items from each course can be sent to the kitchen. **Permissions:** 🟠 `tabs.update` requestBody: content: application/json: schema: type: object properties: coursingOrder: type: number nullable: true description: Specific coursing order to set. If omitted, advances to the next available coursing level. additionalProperties: false parameters: - schema: type: string format: uuid in: path name: id required: true description: Tab UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: tabId: type: string format: uuid description: Tab UUID previousCoursingOrder: type: number nullable: true description: Previous coursing order value coursingOrder: type: number nullable: true description: New coursing order value coursingTitle: type: string nullable: true description: Title of the new coursing level (e.g., "Appetizers", "Main Course") required: - tabId - previousCoursingOrder - coursingOrder additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{id}/debug: get: summary: "Debug: single tab" tags: - Tabs description: >- Debug endpoint for a specific tab with detailed balance verification, per-item allocation breakdowns, and per-purchase line item details. Useful for diagnosing individual tab balance issues. **Permissions:** 🔵 `tabs.read` parameters: - schema: type: string in: path name: id required: true description: Tab UUID responses: "200": description: Detailed debug info for a single tab content: application/json: schema: description: Detailed debug info for a single tab type: object properties: status: type: string enum: - success data: type: object properties: tab: type: object additionalProperties: true balance: type: object additionalProperties: true summary: type: object additionalProperties: true verification: type: object additionalProperties: true purchases: type: array items: type: object additionalProperties: true items: type: array items: type: object additionalProperties: true meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{id}/join: post: summary: Join a tab by its UUID tags: - Tabs description: |- Join a specific tab directly by UUID — no QR code required. Used by the direct tab link feature (?tab=UUID in storefront-web). Returns 400 if the tab is closed/settled. Idempotent — safe to call multiple times with the same identifier. **Permissions:** 🔵 `tabs.read` requestBody: content: application/json: schema: type: object properties: tabMember: type: object description: User identification using priority system properties: id: type: number description: User ID (authenticated users, priority 1) email: type: string format: email description: Email address (priority 2) phone: type: string description: Phone number (priority 3) identifier: type: string description: Device identifier (priority 4) required: - tabMember additionalProperties: false required: true parameters: - schema: type: string format: uuid in: path name: id required: true description: Tab UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: tabId: type: string format: uuid description: Tab UUID tabMemberId: type: string format: uuid description: Tab member UUID isNewMember: type: boolean description: True if newly joined, false if already a member tabState: type: string description: Current tab state required: - tabId - tabMemberId - isNewMember - tabState additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{id}/members: post: summary: Add a member to a tab tags: - Tabs description: >- Add a user as a member to an existing tab. Looks up user by userId (priority 1), email (priority 2), or phone (priority 3). If user is already a member, returns existing member. Useful for POS "Add Loyalty Member" functionality. **Permissions:** 🟠 `tabs.update` requestBody: content: application/json: schema: type: object properties: userId: type: number description: User ID (Priority 1 - direct lookup) email: type: string format: email description: Email address (Priority 2 - lookup by email) phone: type: string description: Phone number (Priority 3 - lookup by phone) additionalProperties: false description: "At least one of userId, email, or phone is required. Resolution priority: userId > email > phone" description: "At least one of userId, email, or phone is required. Resolution priority: userId > email > phone" parameters: - schema: type: string format: uuid in: path name: id required: true description: Tab UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: tabMember: type: object properties: uuid: type: string format: uuid description: Tab member UUID storefrontSessionId: type: string nullable: true description: Storefront session ID initiator: type: boolean description: Whether this member initiated the tab memberType: type: string description: Member type (guest, user, etc.) userId: type: number nullable: true description: User ID if authenticated retailUserId: type: number nullable: true description: Retail user ID if applicable clientId: type: string nullable: true description: Client identifier (user UUID for identification) userEmail: type: string nullable: true description: User email (canonical, never overridden per-location) userName: type: string nullable: true description: Override-merged display name (falls back through retailer.name → ulo.display_name → users.name) isEnrolledInLoyalty: type: boolean description: Whether user is enrolled in location loyalty program createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - initiator - memberType - isEnrolledInLoyalty - createdAt - updatedAt isNewMember: type: boolean description: True if member was newly created, false if already existed user: type: object nullable: true properties: id: type: number description: User ID email: type: string nullable: true description: User email name: type: string nullable: true description: User name phone: type: string nullable: true description: User phone required: - id required: - tabMember - isNewMember - user additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{id}/members/{memberUuid}: delete: summary: Remove a tab member tags: - Tabs description: >- Delete a tab member row. Refuses with 409 MEMBER_HAS_ORDERS when the member is referenced by any kitchen dispatch, settlement, voucher reservation, purchase, or comment (history is never cascade-deleted). Refuses with 409 CANNOT_REMOVE_INITIATOR for the initiator member. Use this from the POS guests tab to remove guests added by mistake. **Permissions:** 🟠 `tabs.update` parameters: - schema: type: string format: uuid in: path name: id required: true description: Tab UUID - schema: type: string format: uuid in: path name: memberUuid required: true description: Tab member UUID to remove responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: removed: type: boolean enum: - true memberUuid: type: string format: uuid required: - removed - memberUuid additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{id}/members/{memberUuid}/contact: patch: summary: Upsert guest contact on a tab member tags: - Tabs description: >- Overwrite email/phone/name on the user row attached to an anonymous tab member. Mirrors the kiosk-commit contact-overwrite semantics so a kiosk pay-upfront flow can record the guest's email before payment (avoiding "no recipient address on file" skips on the receipt-email cloud function). Registered accounts (users.guest=false) are refused — use the identify endpoint for those. **Permissions:** 🟠 `tabs.update` requestBody: content: application/json: schema: type: object properties: email: type: string format: email description: Guest email (overwrites existing non-empty value) phone: type: string description: Guest phone (overwrites existing non-empty value) name: type: string description: Guest name (overwrites existing non-empty value) additionalProperties: false description: At least one of email, phone, or name is required. Non-empty fields are written to the tab member's user row; empty fields are ignored. Only applies to anonymous guest users (users.guest=true). description: At least one of email, phone, or name is required. Non-empty fields are written to the tab member's user row; empty fields are ignored. Only applies to anonymous guest users (users.guest=true). parameters: - schema: type: string format: uuid in: path name: id required: true description: Tab UUID - schema: type: string format: uuid in: path name: memberUuid required: true description: Tab member UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: tabMember: type: object properties: uuid: type: string format: uuid userId: type: number required: - uuid - userId additionalProperties: false user: type: object properties: id: type: number email: type: string nullable: true phone: type: string nullable: true name: type: string nullable: true required: - id additionalProperties: false required: - tabMember - user additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{id}/members/{memberUuid}/identify: patch: summary: Identify an anonymous tab member tags: - Tabs description: >- Link an anonymous tab member to a known user. Looks up user by userId (priority 1), email (priority 2), or phone (priority 3), then updates the tab member record to associate with that user. Useful for POS "Identify Guest" functionality when an anonymous guest needs to be linked to their loyalty account. **Permissions:** 🟠 `tabs.update` requestBody: content: application/json: schema: type: object properties: userId: type: number description: User ID (Priority 1 - direct lookup) email: type: string format: email description: Email address (Priority 2 - lookup by email) phone: type: string description: Phone number (Priority 3 - lookup by phone) additionalProperties: false description: "At least one of userId, email, or phone is required. Resolution priority: userId > email > phone" description: "At least one of userId, email, or phone is required. Resolution priority: userId > email > phone" parameters: - schema: type: string format: uuid in: path name: id required: true description: Tab UUID - schema: type: string format: uuid in: path name: memberUuid required: true description: Tab member UUID to identify responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: tabMember: type: object properties: uuid: type: string format: uuid description: Tab member UUID storefrontSessionId: type: string nullable: true description: Storefront session ID initiator: type: boolean description: Whether this member initiated the tab memberType: type: string description: Member type (guest, user, etc.) userId: type: number nullable: true description: User ID if authenticated retailUserId: type: number nullable: true description: Retail user ID if applicable clientId: type: string nullable: true description: Client identifier (user UUID for identification) userEmail: type: string nullable: true description: User email (canonical, never overridden per-location) userName: type: string nullable: true description: Override-merged display name (falls back through retailer.name → ulo.display_name → users.name) isEnrolledInLoyalty: type: boolean description: Whether user is enrolled in location loyalty program createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - initiator - memberType - isEnrolledInLoyalty - createdAt - updatedAt user: type: object nullable: true properties: id: type: number description: User ID email: type: string nullable: true description: User email name: type: string nullable: true description: User name phone: type: string nullable: true description: User phone required: - id required: - tabMember - user additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{id}/settle: post: summary: Settle a fully paid tab tags: - Tabs description: >- Settle a tab when its remaining balance is 0. This endpoint: 1. **Validates** the tab can be settled: - Tab must exist - Tab must have remaining_balance_cents = 0 (fully paid) - Tab must not already be closed/settled/aborted 2. **Updates** the tab state to 'settled' 3. **Converts amount payments** to proportional item allocations (if any): - Amount payments (type='amount') get converted to product allocations - Each payer gets a proportional share of each item based on their pre-discount payment value - Original amount line items get quantity_cents set to 0 to mark as converted **Use cases:** - When balance reaches 0 via payments - Manual settlement by staff - This is the single source of truth for settling tabs **Note:** If all payments were for specific items (ITEM mode), no conversion is needed. **Permissions:** 🟠 `tabs.update` parameters: - schema: type: string format: uuid in: path name: id required: true description: Tab UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: uuid: type: string format: uuid description: Tab UUID locationId: type: number description: Location ID latestState: type: string enum: - initiated - started - instant - closed - settled - aborted - action_required description: Current tab state selectedPaymentFlow: type: string nullable: true enum: - open_tab - pay_upfront description: "Payment flow (open_tab: pay later, pay_upfront: pay now/instant pay)" paymentMode: type: string enum: - ITEM - AMOUNT description: "Payment mode (ITEM: pay per item, AMOUNT: pay arbitrary amounts)" paymentSplit: type: number nullable: true minimum: 2 maximum: 10 description: Number of splits when in AMOUNT mode (2-10), null when in ITEM mode totalAmountCents: type: number description: Total order amount in cents paidAmountCents: type: number description: Total paid amount in cents remainingBalanceCents: type: number description: Remaining balance to be paid in cents storefrontQrCodeId: type: string nullable: true description: Table/QR code UUID if applicable bookingId: type: string format: uuid nullable: true description: UUID of the booking/reservation that created this tab, if any. Null for tabs not created from a reservation. bookingConfirmationCode: type: string nullable: true description: Confirmation code of the linked booking, when the tab is bound to one. Used by the storefront to deep-link back to the booking confirmation page. tabMembers: type: array items: type: object properties: uuid: type: string format: uuid description: Tab member UUID storefrontSessionId: type: string nullable: true description: Storefront session ID initiator: type: boolean description: Whether this member initiated the tab memberType: type: string description: Member type (guest, user, etc.) userId: type: number nullable: true description: User ID if authenticated retailUserId: type: number nullable: true description: Retail user ID if applicable clientId: type: string nullable: true description: Client identifier (user UUID for identification) userEmail: type: string nullable: true description: User email (canonical, never overridden per-location) userName: type: string nullable: true description: Override-merged display name (falls back through retailer.name → ulo.display_name → users.name) isEnrolledInLoyalty: type: boolean description: Whether user is enrolled in location loyalty program createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - initiator - memberType - isEnrolledInLoyalty - createdAt - updatedAt description: Tab members memberCount: type: number description: Number of guest tab_members (party size; excludes staff) kitchenDispatches: type: array items: type: object properties: uuid: type: string format: uuid description: Kitchen dispatch UUID tabId: type: string format: uuid description: Tab UUID locationId: type: number description: Location ID dailyOrderNumber: type: number nullable: true description: Daily order number latestState: type: string description: Current state of the dispatch createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp kitchenDispatchItems: type: array items: type: object properties: uuid: type: string format: uuid description: Kitchen dispatch item UUID kitchenDispatchId: type: string format: uuid description: Kitchen dispatch UUID saleItemId: type: number nullable: true description: Sale item ID itemId: type: number nullable: true description: Inventory item ID tabMemberId: type: string nullable: true description: Tab member UUID who ordered this parentKitchenDispatchItemId: type: string nullable: true description: Parent kitchen dispatch item UUID (for nested items) price: type: number description: Item price in cents basePrice: type: number description: Base price before modifications in cents discount: type: number nullable: true description: Discount amount in cents quantity: type: number description: Quantity ordered quantityCents: type: number nullable: true description: Quantity in cents (for fractional items) splitOfKdi: type: string format: uuid nullable: true description: UUID of original item if this is a split item (for grouping) tabSettlementId: type: string nullable: true description: Settlement UUID if paid settlementState: type: string nullable: true description: Settlement state (payment_in_progress, settled) status: type: string nullable: true description: Item status itemState: type: string nullable: true description: Kitchen-side item state ('aborted' = voided) voidedQuantityCents: type: number nullable: true description: Voided slice in cents (read from platform_events) — null when not aborted paidAmount: type: number nullable: true description: Amount paid for this item in cents createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp itemTitle: type: string nullable: true description: Item title from inventory itemTitlePrep: type: string nullable: true description: Item prep name from inventory itemDescription: type: string nullable: true description: Item description from inventory itemImageUrl: type: string nullable: true description: Item image URL from inventory tabMember: type: object nullable: true description: Guest/user information for the person who ordered this item properties: uuid: type: string format: uuid description: Tab member UUID name: type: string description: Member name email: type: string description: Member email phone: type: string description: Member phone number imageUrl: type: string description: Member profile image URL memberType: type: string description: Member type (guest, user, etc.) userId: type: number nullable: true description: User ID if authenticated user retailUserId: type: number nullable: true description: Retailer user ID if staff member comments: type: array description: Comments on this item items: type: object properties: comment: type: string createdAt: type: string format: date-time tabMemberUUID: type: string nullable: true uuid: type: string format: uuid variants: type: array description: Variants/modifications on this item items: type: object properties: id: type: number name: type: string price: type: number description: Price in cents (positive or negative) quantityCents: type: number nullable: true description: Quantity in cents (100 = 1.0). NULL = default 1.0 priceCents: type: number nullable: true description: Price at time of order in cents. NULL = look up from variants table required: - uuid - kitchenDispatchId - price - basePrice - quantity - createdAt - updatedAt description: Items in this dispatch required: - uuid - tabId - locationId - latestState - createdAt - updatedAt - kitchenDispatchItems description: Kitchen dispatches with items vouchers: type: array items: type: object properties: id: type: number description: tab_vouchers.id (use with DELETE /vouchers/applied/:id) discountId: type: number description: discounts.id discountCode: type: string description: Voucher code as entered appliedAt: type: string format: date-time voucherName: type: string nullable: true description: discounts.name (internal name) voucherType: type: string nullable: true typeSpecification: type: object nullable: true additionalProperties: true maxDiscountAmountCents: type: number nullable: true maxUses: type: number nullable: true timesUsed: type: number hasUsesLeft: type: boolean description: "Computed: maxUses null/0 OR timesUsed < maxUses" remainingBalanceCents: type: number nullable: true description: For gift cards displayTitle: type: string nullable: true description: Guest-facing title displayDescription: type: string nullable: true description: Guest-facing description displayImageUrl: type: string nullable: true description: Thumbnail URL required: - id - discountId - discountCode - appliedAt - timesUsed - hasUsesLeft description: Vouchers attached to this tab (from POS or storefront) notes: type: array items: type: object properties: uuid: type: string format: uuid description: Note UUID entityType: type: string description: Entity type (tab, user) entityId: type: string description: Entity ID (tab UUID or user ID) note: type: string description: Note content locationId: type: number description: Location ID sortOrder: type: number description: Sort order (0 = first/top) createdByRetailerUserId: type: number nullable: true description: Retailer user who created the note createdByName: type: string nullable: true description: Name of user who created the note updatedByRetailerUserId: type: number nullable: true description: Retailer user who last updated the note updatedByName: type: string nullable: true description: Name of user who last updated the note createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - entityType - entityId - note - locationId - sortOrder - createdAt - updatedAt description: Notes attached to this tab createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp amountPaymentsConverted: type: boolean description: Whether amount payments were converted to item allocations amountPaymentsCount: type: number description: Number of amount payments that were converted newLineItemsCount: type: number description: Number of new product line items created from conversion meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{id}/timeline: get: summary: Get tab timeline tags: - Tabs description: >- Get a unified timeline of all events for a specific tab, including state transitions, order events, member joins, and payments. Events are sorted by creation time descending. **Permissions:** 🔵 `tabs.read` parameters: - schema: type: string format: uuid in: path name: id required: true description: Tab UUID responses: "200": description: Tab timeline events content: application/json: schema: description: Tab timeline events type: object properties: status: type: string enum: - success data: type: object properties: events: type: array items: type: object properties: uuid: type: string description: Event UUID source: type: string enum: - tab_event - order_event - member_joined - purchase description: Event source eventType: type: string description: Event type (e.g. started, closed, pending, confirmed) description: type: string description: Human-readable event description createdAt: type: string format: date-time description: When the event occurred metadata: type: object nullable: true additionalProperties: true description: Additional event-specific data required: - uuid - source - eventType - description - createdAt required: - events meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{tabId}/checkout-summary: post: summary: Get checkout summary tags: - Tabs description: Get checkout summary for a tab member's locked items. Returns items, totals, VAT breakdown, and kitchenDispatchItems array for payment processing. requestBody: content: application/json: schema: type: object properties: tabMember: type: object properties: id: type: string description: Tab member UUID (Priority 1) email: type: string description: Email address (Priority 2) phone: type: string description: Phone number (Priority 3) identifier: type: string description: Device/client identifier (Priority 4) description: "Tab member identification. Provide at least one identifier. Priority: id > email > phone > identifier" required: - tabMember required: true parameters: - schema: type: string format: uuid in: path name: tabId required: true description: Tab UUID responses: "200": description: Checkout summary retrieved successfully content: application/json: schema: description: Checkout summary retrieved successfully type: object properties: status: type: string enum: - success data: type: object properties: paymentMode: type: string enum: - ITEM - AMOUNT description: "Payment mode indicator: ITEM for item-based, AMOUNT for split-based" tabId: type: string description: Tab UUID tabMemberId: type: string description: Resolved tab member UUID clientId: type: string nullable: true description: Client UUID for session correlation items: type: array items: type: object properties: kitchenDispatchItemId: type: string description: Kitchen dispatch item UUID itemId: type: number description: Inventory item ID title: type: string description: Item title quantity: type: number description: Actual quantity (quantity_cents / 100) basePrice: type: number description: Base item price in cents variantsPrice: type: number description: Total variants price in cents totalPrice: type: number description: Total price (basePrice + variantsPrice) * quantity in cents discount: type: number nullable: true description: Discount amount in cents vat: type: number description: VAT rate in basis points (1200 = 12%, defaults to 1200 if item has no VAT) vatId: type: number description: VAT ID for mapping (defaults to 1 if item has no VAT ID) vatAmountCents: type: number description: Calculated VAT amount in cents (VAT-inclusive calculation) variants: type: array items: type: object properties: id: type: number description: Variant ID name: type: string description: Variant name/title from inventory quantity_cents: type: number description: Quantity in cents (100 = 1x) price_cents: type: number nullable: true description: Price override in cents comments: type: array items: type: string description: Variant-specific comments variants: type: array items: type: object description: Nested variants (recursive structure) required: - id description: Selected variants for this item comments: type: array items: type: string description: Item comments required: - kitchenDispatchItemId - itemId - title - quantity - basePrice - variantsPrice - totalPrice - vat - vatId - vatAmountCents - variants - comments description: Locked items for checkout (ITEM mode only) totals: type: object properties: subtotal: type: number description: Sum of all item totalPrice (before discounts) in cents discounts: type: number description: Total discounts applied in cents totalAmountInCents: type: number description: Final total (subtotal - discounts) in cents vatBreakdown: type: object additionalProperties: type: number description: VAT breakdown by rate. Keys are formatted like "12 %", "25 %". Values in cents. example: 12 %: 1200 25 %: 500 required: - subtotal - discounts - totalAmountInCents - vatBreakdown kitchenDispatchItems: type: array items: type: string description: Kitchen dispatch item UUIDs for payment call (ITEM mode only) paymentSplit: type: number description: Number of ways the tab is split, 2-10 (AMOUNT mode only) totalAmountCents: type: number description: Total tab amount in cents (AMOUNT mode only) splitAmountCents: type: number description: Amount per split in cents, rounded up (AMOUNT mode only) paidAmountCents: type: number description: Total amount already paid in cents (AMOUNT mode only) remainingBalanceCents: type: number description: Remaining balance in cents (AMOUNT mode only) paidSplits: type: number description: Number of splits already paid (AMOUNT mode only) remainingSplits: type: number description: Number of splits remaining to pay (AMOUNT mode only) vatBreakdown: type: object additionalProperties: type: number description: VAT breakdown by rate. Keys are formatted like "12 %", "25 %". Values in cents. Present in both modes. required: - paymentMode - tabId - tabMemberId - clientId meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{tabId}/discounts: get: summary: Get tab discounts tags: - Tabs description: Retrieve all items with discounts or price changes on a tab parameters: - schema: type: string enum: - DISCOUNT_PERCENTAGE - DISCOUNT_FIXED - PRICE_SET - DISCOUNT_REMOVED in: query name: changeType required: false description: Filter by type of price change - schema: type: integer in: query name: appliedBy required: false description: Filter by retailer user ID who applied the change - schema: type: string format: uuid in: path name: tabId required: true description: UUID of the tab responses: "200": description: Default Response content: application/json: schema: type: object required: - status - data - meta properties: status: type: string enum: - success description: Response status data: type: object required: - events properties: events: type: array items: type: object required: - id - kitchenDispatchItemId - tabId - appliedBy - previousPrice - newPrice - basePrice - changeType - reasonCode - createdAt properties: id: type: integer description: Unique identifier for this price event kitchenDispatchItemId: type: string format: uuid description: UUID of the kitchen dispatch item that was modified tabId: type: string format: uuid description: UUID of the tab containing the item appliedBy: type: object required: - userId properties: userId: type: integer description: Retailer user ID of the staff member name: type: string nullable: true description: Name of the staff member email: type: string nullable: true format: email description: Email of the staff member previousPrice: type: integer description: Previous price in cents newPrice: type: integer description: New price in cents previousDiscount: type: integer nullable: true description: Previous discount amount in cents (null if no previous discount) newDiscount: type: integer nullable: true description: New discount amount in cents (null if no discount) basePrice: type: integer description: Original base price in cents (for reference) changeType: type: string enum: - DISCOUNT_PERCENTAGE - DISCOUNT_FIXED - PRICE_SET - DISCOUNT_REMOVED description: Type of price change applied to the item discountPercentage: type: number nullable: true description: "For percentage discounts: the percentage value (e.g., 15.5 for 15.5% off)" discountAmountCents: type: integer nullable: true description: "For fixed discounts: the fixed amount in cents" reasonCode: type: string description: Reason code for the price change (PRICE_MATCH, GOODWILL, etc.) example: PRICE_MATCH notes: type: string nullable: true description: Optional notes explaining the price adjustment createdAt: type: string format: date-time description: When the price change was applied description: List of price change events meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{tabId}/items: get: summary: Get selected items tags: - Tabs description: Get current selected items state for a tab parameters: - schema: type: string format: uuid in: path name: tabId required: true description: UUID of the tab responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: stateValidToEpoch: type: number description: Timestamp (milliseconds since epoch) when this state expires selectedItems: type: array items: type: object properties: tabMemberId: type: string format: uuid description: UUID of the tab member who claimed this item clientId: type: string format: uuid description: UUID of the client (from storefront sessions) for compatibility itemId: type: string format: uuid description: UUID of the inventory item that was claimed isLocked: type: boolean description: Whether this item is locked for checkout (cannot be unclaimed by others) required: - tabMemberId - clientId - itemId - isLocked description: Array of currently claimed items with their lock status hasLockedMembers: type: boolean description: True if any member has locked their selections for checkout (blocks split changes) required: - stateValidToEpoch - selectedItems - hasLockedMembers meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{tabId}/items/{itemId}/discount: delete: summary: Remove item discount tags: - Tabs description: Remove any discount from an item and restore its base price requestBody: content: application/json: schema: type: object required: - reasonCode properties: reasonCode: type: string description: Reason code for removing the discount notes: type: string description: Optional notes required: true parameters: - schema: type: string format: uuid in: path name: tabId required: true description: UUID of the tab containing the item - schema: type: string format: uuid in: path name: itemId required: true description: UUID of the kitchen dispatch item to restore responses: "200": description: Default Response content: application/json: schema: type: object required: - status - data - meta properties: status: type: string enum: - success description: Response status data: type: object required: - priceEvent properties: priceEvent: type: object required: - id - kitchenDispatchItemId - tabId - appliedBy - previousPrice - newPrice - basePrice - changeType - reasonCode - createdAt properties: id: type: integer description: Unique identifier for this price event kitchenDispatchItemId: type: string format: uuid description: UUID of the kitchen dispatch item that was modified tabId: type: string format: uuid description: UUID of the tab containing the item appliedBy: type: object required: - userId properties: userId: type: integer description: Retailer user ID of the staff member name: type: string nullable: true description: Name of the staff member email: type: string nullable: true format: email description: Email of the staff member previousPrice: type: integer description: Previous price in cents newPrice: type: integer description: New price in cents previousDiscount: type: integer nullable: true description: Previous discount amount in cents (null if no previous discount) newDiscount: type: integer nullable: true description: New discount amount in cents (null if no discount) basePrice: type: integer description: Original base price in cents (for reference) changeType: type: string enum: - DISCOUNT_PERCENTAGE - DISCOUNT_FIXED - PRICE_SET - DISCOUNT_REMOVED description: Type of price change applied to the item discountPercentage: type: number nullable: true description: "For percentage discounts: the percentage value (e.g., 15.5 for 15.5% off)" discountAmountCents: type: integer nullable: true description: "For fixed discounts: the fixed amount in cents" reasonCode: type: string description: Reason code for the price change (PRICE_MATCH, GOODWILL, etc.) example: PRICE_MATCH notes: type: string nullable: true description: Optional notes explaining the price adjustment createdAt: type: string format: date-time description: When the price change was applied meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{tabId}/items/{itemId}/price: put: summary: Update item price tags: - Tabs description: Apply a discount or set a new price on a kitchen dispatch item requestBody: content: application/json: schema: type: object required: - action - reasonCode properties: action: type: string enum: - discount - set_price description: 'Type of action: "discount" for applying discounts, "set_price" for setting arbitrary price' discountType: type: string enum: - percentage - fixed description: 'Required when action is "discount": type of discount to apply' value: type: number description: 'Required when action is "discount": percentage (1-100) or cents for fixed discount' minimum: 0 priceInCents: type: integer description: 'Required when action is "set_price": new price in cents' minimum: 0 reasonCode: type: string description: Required reason code explaining why the price is being adjusted example: PRICE_MATCH notes: type: string description: Optional notes providing additional context for the price adjustment required: true parameters: - schema: type: string format: uuid in: path name: tabId required: true description: UUID of the tab containing the item - schema: type: string format: uuid in: path name: itemId required: true description: UUID of the kitchen dispatch item to modify responses: "200": description: Default Response content: application/json: schema: type: object required: - status - data - meta properties: status: type: string enum: - success description: Response status data: type: object required: - priceEvent properties: priceEvent: type: object required: - id - kitchenDispatchItemId - tabId - appliedBy - previousPrice - newPrice - basePrice - changeType - reasonCode - createdAt properties: id: type: integer description: Unique identifier for this price event kitchenDispatchItemId: type: string format: uuid description: UUID of the kitchen dispatch item that was modified tabId: type: string format: uuid description: UUID of the tab containing the item appliedBy: type: object required: - userId properties: userId: type: integer description: Retailer user ID of the staff member name: type: string nullable: true description: Name of the staff member email: type: string nullable: true format: email description: Email of the staff member previousPrice: type: integer description: Previous price in cents newPrice: type: integer description: New price in cents previousDiscount: type: integer nullable: true description: Previous discount amount in cents (null if no previous discount) newDiscount: type: integer nullable: true description: New discount amount in cents (null if no discount) basePrice: type: integer description: Original base price in cents (for reference) changeType: type: string enum: - DISCOUNT_PERCENTAGE - DISCOUNT_FIXED - PRICE_SET - DISCOUNT_REMOVED description: Type of price change applied to the item discountPercentage: type: number nullable: true description: "For percentage discounts: the percentage value (e.g., 15.5 for 15.5% off)" discountAmountCents: type: integer nullable: true description: "For fixed discounts: the fixed amount in cents" reasonCode: type: string description: Reason code for the price change (PRICE_MATCH, GOODWILL, etc.) example: PRICE_MATCH notes: type: string nullable: true description: Optional notes explaining the price adjustment createdAt: type: string format: date-time description: When the price change was applied meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{tabId}/items/{itemId}/price-history: get: summary: Get item price history tags: - Tabs description: Retrieve the complete price change history for a kitchen dispatch item parameters: - schema: type: string format: uuid in: path name: tabId required: true description: UUID of the tab - schema: type: string format: uuid in: path name: itemId required: true description: UUID of the kitchen dispatch item responses: "200": description: Default Response content: application/json: schema: type: object required: - status - data - meta properties: status: type: string enum: - success description: Response status data: type: object required: - events properties: events: type: array items: type: object required: - id - kitchenDispatchItemId - tabId - appliedBy - previousPrice - newPrice - basePrice - changeType - reasonCode - createdAt properties: id: type: integer description: Unique identifier for this price event kitchenDispatchItemId: type: string format: uuid description: UUID of the kitchen dispatch item that was modified tabId: type: string format: uuid description: UUID of the tab containing the item appliedBy: type: object required: - userId properties: userId: type: integer description: Retailer user ID of the staff member name: type: string nullable: true description: Name of the staff member email: type: string nullable: true format: email description: Email of the staff member previousPrice: type: integer description: Previous price in cents newPrice: type: integer description: New price in cents previousDiscount: type: integer nullable: true description: Previous discount amount in cents (null if no previous discount) newDiscount: type: integer nullable: true description: New discount amount in cents (null if no discount) basePrice: type: integer description: Original base price in cents (for reference) changeType: type: string enum: - DISCOUNT_PERCENTAGE - DISCOUNT_FIXED - PRICE_SET - DISCOUNT_REMOVED description: Type of price change applied to the item discountPercentage: type: number nullable: true description: "For percentage discounts: the percentage value (e.g., 15.5 for 15.5% off)" discountAmountCents: type: integer nullable: true description: "For fixed discounts: the fixed amount in cents" reasonCode: type: string description: Reason code for the price change (PRICE_MATCH, GOODWILL, etc.) example: PRICE_MATCH notes: type: string nullable: true description: Optional notes explaining the price adjustment createdAt: type: string format: date-time description: When the price change was applied description: List of price change events meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{tabId}/items/batch: post: summary: Batch claim and unclaim items tags: - Tabs description: Atomically claim and unclaim items for a tab member in a single operation. Emits a single webhook event for the combined change. requestBody: content: application/json: schema: type: object properties: tabMemberId: type: string format: uuid description: UUID of the tab member performing the batch operation clientId: type: string format: uuid description: UUID of the client (from storefront sessions) claim: type: array items: type: string description: Item IDs to claim (UUIDs in ITEM mode, virtual IDs like "split-index-N" in AMOUNT mode) unclaim: type: array items: type: string description: Item IDs to unclaim (UUIDs in ITEM mode, virtual IDs like "split-index-N" in AMOUNT mode) mode: type: string enum: - ITEM - AMOUNT description: Payment mode for the batch operation required: - tabMemberId - clientId required: true parameters: - schema: type: string format: uuid in: path name: tabId required: true description: UUID of the tab responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: success: type: boolean enum: - true stateValidToEpoch: type: number description: Timestamp when this state expires selectedItems: type: array items: type: object properties: tabMemberId: type: string format: uuid description: UUID of the tab member who claimed this item clientId: type: string format: uuid description: UUID of the client (from storefront sessions) for compatibility itemId: type: string format: uuid description: UUID of the inventory item that was claimed isLocked: type: boolean description: Whether this item is locked for checkout (cannot be unclaimed by others) required: - tabMemberId - clientId - itemId - isLocked description: Updated list of selected items hasLockedMembers: type: boolean description: True if any member has locked their selections for checkout required: - success - stateValidToEpoch - selectedItems - hasLockedMembers meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "409": description: Selections are locked for checkout content: application/json: schema: description: Selections are locked for checkout type: object properties: status: type: string enum: - error error: type: object properties: code: type: string enum: - SELECTIONS_LOCKED message: type: string meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{tabId}/items/bulk-price: put: summary: Bulk update item prices tags: - Tabs description: Apply discounts or set new prices on multiple kitchen dispatch items in a single request. Only sends items that need to be updated. requestBody: content: application/json: schema: type: object required: - items - reasonCode properties: items: type: array items: type: object required: - kitchenDispatchItemId properties: kitchenDispatchItemId: type: string format: uuid description: UUID of the kitchen dispatch item to modify newPrice: type: integer description: New price in cents (for set_price action) minimum: 0 discountPercent: type: number description: Percentage discount to apply (1-100) minimum: 0 maximum: 100 removeDiscount: type: boolean description: Set to true to remove discount and restore base price description: "Array of items to update. Each item should specify exactly one of: newPrice, discountPercent, or removeDiscount" minItems: 1 reasonCode: type: string description: Reason code explaining why the prices are being adjusted example: PRICE_MATCH notes: type: string description: Optional notes providing additional context for the price adjustments required: true parameters: - schema: type: string format: uuid in: path name: tabId required: true description: UUID of the tab containing the items responses: "200": description: Default Response content: application/json: schema: type: object required: - status - data - meta properties: status: type: string enum: - success description: Response status data: type: object required: - results properties: results: type: array items: type: object required: - kitchenDispatchItemId - previousPrice - newPrice - changeType - success properties: kitchenDispatchItemId: type: string format: uuid description: UUID of the modified item previousPrice: type: integer description: Previous price in cents newPrice: type: integer description: New price in cents changeType: type: string enum: - DISCOUNT_PERCENTAGE - DISCOUNT_FIXED - PRICE_SET - DISCOUNT_REMOVED description: Type of price change applied to the item success: type: boolean description: Whether the update succeeded error: type: string description: Error message if update failed description: Results for each item update totalUpdated: type: integer description: Number of items successfully updated meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{tabId}/items/claim: post: summary: Claim items tags: - Tabs description: Claim specific items for a tab member requestBody: content: application/json: schema: type: object properties: tabMemberId: type: string format: uuid description: UUID of the tab member claiming the items clientId: type: string format: uuid description: UUID of the client (from storefront sessions) for storage efficiency items: type: array items: type: string minItems: 1 description: 'Array of item IDs to claim. In ITEM mode: inventory item UUIDs. In AMOUNT mode: virtual IDs like "split-index-0".' mode: type: string enum: - ITEM - AMOUNT description: "Payment mode: ITEM for individual item claiming, AMOUNT for split claiming" required: - tabMemberId - clientId - items required: true parameters: - schema: type: string format: uuid in: path name: tabId required: true description: UUID of the tab responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: success: type: boolean enum: - true stateValidToEpoch: type: number description: Timestamp when this state expires selectedItems: type: array items: type: object properties: tabMemberId: type: string format: uuid description: UUID of the tab member who claimed this item clientId: type: string format: uuid description: UUID of the client (from storefront sessions) for compatibility itemId: type: string format: uuid description: UUID of the inventory item that was claimed isLocked: type: boolean description: Whether this item is locked for checkout (cannot be unclaimed by others) required: - tabMemberId - clientId - itemId - isLocked description: Updated list of selected items hasLockedMembers: type: boolean description: True if any member has locked their selections for checkout required: - success - stateValidToEpoch - selectedItems - hasLockedMembers meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "409": description: Selections are locked for checkout content: application/json: schema: description: Selections are locked for checkout type: object properties: status: type: string enum: - error error: type: object properties: code: type: string enum: - SELECTIONS_LOCKED message: type: string meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{tabId}/items/lock: post: summary: Lock item selections tags: - Tabs description: Lock a tab member's selections for checkout (prevents further modifications) requestBody: content: application/json: schema: type: object properties: tabMemberId: anyOf: - type: string format: uuid - type: "null" description: UUID of the tab member to lock/unlock selections for (nullable) clientId: type: string format: uuid description: UUID of the client (fallback identifier when tabMemberId is not available) claimAfterUnlock: type: boolean description: If true, freed items are re-claimed to the caller after force-unlock of another member. skipCascadeCancel: type: boolean description: When true, bypass the auto-cancel of any payment_in_progress settlements for the unlocked member. Use only for staff force-unlock flows. Default false. anyOf: - required: - tabMemberId - required: - clientId parameters: - schema: type: string format: uuid in: path name: tabId required: true description: UUID of the tab responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: success: type: boolean enum: - true stateValidToEpoch: type: number description: Timestamp when this state expires selectedItems: type: array items: type: object properties: tabMemberId: type: string format: uuid description: UUID of the tab member who claimed this item clientId: type: string format: uuid description: UUID of the client (from storefront sessions) for compatibility itemId: type: string format: uuid description: UUID of the inventory item that was claimed isLocked: type: boolean description: Whether this item is locked for checkout (cannot be unclaimed by others) required: - tabMemberId - clientId - itemId - isLocked description: Updated list of selected items hasLockedMembers: type: boolean description: True if any member has locked their selections for checkout required: - success - stateValidToEpoch - selectedItems - hasLockedMembers meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{tabId}/items/unclaim: post: summary: Unclaim items tags: - Tabs description: Unclaim (release) specific items for a tab member requestBody: content: application/json: schema: type: object properties: tabMemberId: type: string format: uuid description: UUID of the tab member unclaiming the items items: type: array items: type: string minItems: 1 description: 'Array of item IDs to unclaim. In ITEM mode: inventory item UUIDs. In AMOUNT mode: virtual IDs like "split-index-0".' mode: type: string enum: - ITEM - AMOUNT description: "Payment mode: ITEM for individual item unclaiming, AMOUNT for split unclaiming" required: - tabMemberId - items required: true parameters: - schema: type: string format: uuid in: path name: tabId required: true description: UUID of the tab responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: success: type: boolean enum: - true stateValidToEpoch: type: number description: Timestamp when this state expires selectedItems: type: array items: type: object properties: tabMemberId: type: string format: uuid description: UUID of the tab member who claimed this item clientId: type: string format: uuid description: UUID of the client (from storefront sessions) for compatibility itemId: type: string format: uuid description: UUID of the inventory item that was claimed isLocked: type: boolean description: Whether this item is locked for checkout (cannot be unclaimed by others) required: - tabMemberId - clientId - itemId - isLocked description: Updated list of selected items hasLockedMembers: type: boolean description: True if any member has locked their selections for checkout required: - success - stateValidToEpoch - selectedItems - hasLockedMembers meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "409": description: Selections are locked for checkout content: application/json: schema: description: Selections are locked for checkout type: object properties: status: type: string enum: - error error: type: object properties: code: type: string enum: - SELECTIONS_LOCKED message: type: string meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{tabId}/items/unlock: post: summary: Unlock item selections tags: - Tabs description: Unlock a tab member's selections (allows modifications again) requestBody: content: application/json: schema: type: object properties: tabMemberId: anyOf: - type: string format: uuid - type: "null" description: UUID of the tab member to lock/unlock selections for (nullable) clientId: type: string format: uuid description: UUID of the client (fallback identifier when tabMemberId is not available) claimAfterUnlock: type: boolean description: If true, freed items are re-claimed to the caller after force-unlock of another member. skipCascadeCancel: type: boolean description: When true, bypass the auto-cancel of any payment_in_progress settlements for the unlocked member. Use only for staff force-unlock flows. Default false. anyOf: - required: - tabMemberId - required: - clientId parameters: - schema: type: string format: uuid in: path name: tabId required: true description: UUID of the tab responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: success: type: boolean enum: - true stateValidToEpoch: type: number description: Timestamp when this state expires selectedItems: type: array items: type: object properties: tabMemberId: type: string format: uuid description: UUID of the tab member who claimed this item clientId: type: string format: uuid description: UUID of the client (from storefront sessions) for compatibility itemId: type: string format: uuid description: UUID of the inventory item that was claimed isLocked: type: boolean description: Whether this item is locked for checkout (cannot be unclaimed by others) required: - tabMemberId - clientId - itemId - isLocked description: Updated list of selected items hasLockedMembers: type: boolean description: True if any member has locked their selections for checkout required: - success - stateValidToEpoch - selectedItems - hasLockedMembers meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{tabId}/move/dispatch: post: summary: Move dispatch to another table tags: - Tabs description: Move an entire kitchen_dispatch from a tab to another table requestBody: content: application/json: schema: type: object properties: dispatchId: type: string format: uuid description: Kitchen dispatch UUID to move destinationTableId: type: string format: uuid description: Destination table (storefront_qr_code) UUID required: - dispatchId - destinationTableId required: true parameters: - schema: type: string format: uuid in: path name: tabId required: true description: Source tab UUID responses: "200": description: Dispatch moved successfully content: application/json: schema: description: Dispatch moved successfully type: object properties: status: type: string enum: - success data: type: object properties: success: type: boolean message: type: string sourceTabId: type: string format: uuid destinationTabId: type: string format: uuid movedItemCount: type: integer tabMerged: type: boolean required: - success - message - sourceTabId - destinationTabId - movedItemCount - tabMerged meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{tabId}/move/items: post: summary: Move items to another table tags: - Tabs description: Move specific kitchen_dispatch_items from a tab to another table requestBody: content: application/json: schema: type: object properties: itemIds: type: array items: type: string format: uuid description: Array of kitchen_dispatch_item UUIDs to move minItems: 1 destinationTableId: type: string format: uuid description: Destination table (storefront_qr_code) UUID required: - itemIds - destinationTableId required: true parameters: - schema: type: string format: uuid in: path name: tabId required: true description: Source tab UUID responses: "200": description: Items moved successfully content: application/json: schema: description: Items moved successfully type: object properties: status: type: string enum: - success data: type: object properties: success: type: boolean message: type: string sourceTabId: type: string format: uuid destinationTabId: type: string format: uuid movedItemCount: type: integer tabMerged: type: boolean required: - success - message - sourceTabId - destinationTabId - movedItemCount - tabMerged meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{tabId}/move/tab: post: summary: Move tab to another table tags: - Tabs description: Move an entire tab to another table. If destination table has an active tab, tabs are merged. requestBody: content: application/json: schema: type: object properties: destinationTableId: type: string format: uuid description: Destination table (storefront_qr_code) UUID required: - destinationTableId required: true parameters: - schema: type: string format: uuid in: path name: tabId required: true description: Source tab UUID responses: "200": description: Tab moved or merged successfully content: application/json: schema: description: Tab moved or merged successfully type: object properties: status: type: string enum: - success data: type: object properties: success: type: boolean message: type: string sourceTabId: type: string format: uuid destinationTabId: type: string format: uuid movedItemCount: type: integer tabMerged: type: boolean required: - success - message - sourceTabId - destinationTabId - movedItemCount - tabMerged meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{tabId}/payment-split: post: summary: Set payment split tags: - Tabs description: >- Set payment split for a tab (switches to AMOUNT mode). This endpoint allows users to split the entire tab bill evenly among multiple people. When a split is set, the tab switches from ITEM mode to AMOUNT mode. **Constraints:** - Split can only be set when no payments have been made yet - Split can be changed until someone locks items for checkout - Split value must be between 2 and 10 - Tab must have items (total_amount_cents > 0) requestBody: content: application/json: schema: type: object required: - payment_split properties: payment_split: type: integer minimum: 2 maximum: 10 description: Number of ways to split the tab (2-10) required: true parameters: - schema: type: string format: uuid in: path name: tabId required: true description: The UUID of the tab responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: tabId: type: string format: uuid paymentMode: type: string enum: - AMOUNT paymentSplit: type: integer description: Number of splits totalAmountCents: type: integer description: Total tab amount in cents splitAmountCents: type: integer description: Amount per split in cents (rounded up) remainingBalanceCents: type: integer description: Remaining balance in cents paidSplits: type: integer description: Number of splits already paid remainingSplits: type: integer description: Number of splits remaining meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Clear payment split tags: - Tabs description: >- Clear payment split for a tab (reverts to ITEM mode). This endpoint allows users to cancel/clear a previously set payment split. When cleared, the tab switches from AMOUNT mode back to ITEM mode. **Constraints:** - Can only be cleared when no payments have been made yet - Cannot be cleared while items are locked for checkout - Tab must currently be in AMOUNT mode (split mode) **Use cases:** - User changed their mind about splitting - Split was set by mistake - Group decided to pay individually instead parameters: - schema: type: string format: uuid in: path name: tabId required: true description: The UUID of the tab responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: tabId: type: string format: uuid paymentMode: type: string enum: - ITEM description: Payment mode after clearing (always ITEM) previousPaymentSplit: type: integer nullable: true description: The previous split value that was cleared clearedSelections: type: boolean description: Whether Redis selections were cleared meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/{tabId}/purchases: get: summary: Get purchases for a tab tags: - Tabs description: >- Get all confirmed purchases for a specific tab, including payer information and totals. Used to display payment history in the POS tab view. **Permissions:** 🔵 `purchases.read` parameters: - schema: type: number in: query name: locationId required: true description: Location ID - schema: type: string format: uuid in: path name: tabId required: true description: Tab UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: purchases: type: array items: type: object properties: id: type: number description: Purchase ID intentId: type: string description: Payment intent ID purchasedAt: type: string format: date-time description: When the purchase was completed state: type: string description: Purchase state currencyCode: type: string description: Currency code (e.g., SEK) payerUuid: type: string format: uuid nullable: true description: Tab member UUID who paid payerName: type: string nullable: true description: Name of the payer payerEmail: type: string nullable: true description: Email of the payer psp: type: string nullable: true description: Payment service provider (e.g. adyen, swish, gift_card, cash, prepaid, invoice, softpay) totalAmountCents: type: number description: Total purchase amount in cents lineItemCount: type: number description: Number of line items in the purchase required: - id - intentId - purchasedAt - state - totalAmountCents - lineItemCount description: List of purchases for this tab summary: type: object properties: totalPaidCents: type: number description: Total amount paid across all purchases in cents purchaseCount: type: number description: Number of purchases totalItemCount: type: number description: Total number of line items across all purchases required: - totalPaidCents - purchaseCount - totalItemCount required: - purchases - summary meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/check-exists: post: summary: Check if tab exists for QR code (without joining) tags: - Tabs description: >- Checks if an active tab exists for a QR code WITHOUT joining the user to it. This is useful for instant-pay flows that want to show a "Join Tab" option but should not auto-join. Returns hasActiveTab: true/false with the tabId if one exists. **Permissions:** 🔵 `tabs.read` requestBody: content: application/json: schema: type: object properties: locationId: type: number description: Restaurant location ID qrCodeId: type: string format: uuid description: QR code UUID for the table required: - locationId - qrCodeId additionalProperties: false required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: hasActiveTab: type: boolean description: True if an active tab exists for this QR code tabId: type: string format: uuid nullable: true description: Tab UUID if exists, null otherwise tabMemberId: type: string format: uuid nullable: true description: Always null since this endpoint does not join the tab isNewMember: type: boolean description: Always false since this endpoint does not join the tab required: - hasActiveTab - tabId - tabMemberId - isNewMember additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/debug/recent: get: summary: "Debug: recent tabs" tags: - Tabs description: >- Debug endpoint that returns recent tabs with balance verification, item allocations, and purchase breakdowns. Useful for diagnosing tab balance discrepancies. **Permissions:** 🔵 `tabs.read` parameters: - schema: type: number minimum: 1 maximum: 20 default: 5 in: query name: limit required: false description: Number of recent tabs to return (max 20) - schema: type: number in: query name: locationId required: false description: Filter by location ID responses: "200": description: Debug info for recent tabs content: application/json: schema: description: Debug info for recent tabs type: object properties: status: type: string enum: - success data: type: object properties: tabs: type: array items: type: object additionalProperties: true query: type: object additionalProperties: true meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/join-if-existing: post: summary: Join existing tab for QR code tags: - Tabs description: >- Returns all active joinable tabs (≤7 days old) for the QR code. When exactly one tab exists, auto-joins the user. When multiple tabs exist, returns the list for user selection without joining (pass tabId in a second request to join a specific tab). Returns hasActiveTab:false if no active tabs exist. **Permissions:** 🔵 `tabs.read` requestBody: content: application/json: schema: type: object properties: locationId: type: number description: Restaurant location ID qrCodeId: type: string format: uuid description: QR code UUID for the table tabMember: type: object description: User identification using priority system properties: id: type: number description: User ID (authenticated users, priority 1) email: type: string format: email description: Email address (priority 2) phone: type: string description: Phone number (priority 3) identifier: type: string description: Device identifier (priority 4) tabId: type: string format: uuid description: Specific tab UUID to join (when user selects from multiple joinable tabs). Omit to auto-join or get the list. required: - locationId - qrCodeId - tabMember additionalProperties: false required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: hasActiveTab: type: boolean description: True if one or more active tabs exist at this QR code, false otherwise tabId: type: string format: uuid nullable: true description: Tab UUID the user was joined to (null when multiple tabs exist and user must choose) tabMemberId: type: string format: uuid nullable: true description: Tab member UUID (null when user has not yet been joined to a specific tab) isNewMember: type: boolean description: True if user was just added as member, false if already member or no tab exists joinableTabs: type: array items: type: object properties: tabId: type: string format: uuid description: Tab UUID selectedPaymentFlow: type: string nullable: true description: open_tab or pay_upfront tableName: type: string nullable: true description: Table/QR code display name memberCount: type: number description: Number of members currently in this tab totalAmountCents: type: number description: Current total of the tab in cents createdAt: type: string format: date-time description: When the tab was created members: type: array description: Tab members with display names (for avatar display in join UI) items: type: object properties: userName: type: string nullable: true description: Member display name required: - userName required: - tabId - selectedPaymentFlow - tableName - memberCount - totalAmountCents - createdAt - members description: All active joinable tabs at this QR code (empty when none). Frontend shows selection drawer when length > 1. required: - hasActiveTab - tabId - tabMemberId - isNewMember - joinableTabs additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/mine: get: summary: List the authenticated guest's active tabs tags: - Tabs description: Returns all non-terminal tabs (latest_state NOT IN closed/settled/aborted) where the Bearer-authenticated guest user is a tab_member. Includes members and a minimal location stub. Identity resolves via the same JWT path as buyer endpoints (HS256 mobile or OIDC RS256 storefront). responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: tabs: type: array items: type: object properties: uuid: type: string format: uuid description: Tab UUID locationId: type: number description: Location ID latestState: type: string enum: - initiated - started - instant - closed - settled - aborted - action_required description: Current tab state selectedPaymentFlow: type: string nullable: true enum: - open_tab - pay_upfront description: "Payment flow (open_tab: pay later, pay_upfront: pay now/instant pay)" paymentMode: type: string enum: - ITEM - AMOUNT description: "Payment mode (ITEM: pay per item, AMOUNT: pay arbitrary amounts)" paymentSplit: type: number nullable: true minimum: 2 maximum: 10 description: Number of splits when in AMOUNT mode (2-10), null when in ITEM mode totalAmountCents: type: number description: Total order amount in cents paidAmountCents: type: number description: Total paid amount in cents remainingBalanceCents: type: number description: Remaining balance to be paid in cents storefrontQrCodeId: type: string nullable: true description: Table/QR code UUID if applicable bookingId: type: string format: uuid nullable: true description: UUID of the booking/reservation that created this tab, if any. Null for tabs not created from a reservation. bookingConfirmationCode: type: string nullable: true description: Confirmation code of the linked booking, when the tab is bound to one. Used by the storefront to deep-link back to the booking confirmation page. tabMembers: type: array items: type: object properties: uuid: type: string format: uuid description: Tab member UUID storefrontSessionId: type: string nullable: true description: Storefront session ID initiator: type: boolean description: Whether this member initiated the tab memberType: type: string description: Member type (guest, user, etc.) userId: type: number nullable: true description: User ID if authenticated retailUserId: type: number nullable: true description: Retail user ID if applicable clientId: type: string nullable: true description: Client identifier (user UUID for identification) userEmail: type: string nullable: true description: User email (canonical, never overridden per-location) userName: type: string nullable: true description: Override-merged display name (falls back through retailer.name → ulo.display_name → users.name) isEnrolledInLoyalty: type: boolean description: Whether user is enrolled in location loyalty program createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - initiator - memberType - isEnrolledInLoyalty - createdAt - updatedAt description: Tab members memberCount: type: number description: Number of guest tab_members (party size; excludes staff) kitchenDispatches: type: array items: type: object properties: uuid: type: string format: uuid description: Kitchen dispatch UUID tabId: type: string format: uuid description: Tab UUID locationId: type: number description: Location ID dailyOrderNumber: type: number nullable: true description: Daily order number latestState: type: string description: Current state of the dispatch createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp kitchenDispatchItems: type: array items: type: object properties: uuid: type: string format: uuid description: Kitchen dispatch item UUID kitchenDispatchId: type: string format: uuid description: Kitchen dispatch UUID saleItemId: type: number nullable: true description: Sale item ID itemId: type: number nullable: true description: Inventory item ID tabMemberId: type: string nullable: true description: Tab member UUID who ordered this parentKitchenDispatchItemId: type: string nullable: true description: Parent kitchen dispatch item UUID (for nested items) price: type: number description: Item price in cents basePrice: type: number description: Base price before modifications in cents discount: type: number nullable: true description: Discount amount in cents quantity: type: number description: Quantity ordered quantityCents: type: number nullable: true description: Quantity in cents (for fractional items) splitOfKdi: type: string format: uuid nullable: true description: UUID of original item if this is a split item (for grouping) tabSettlementId: type: string nullable: true description: Settlement UUID if paid settlementState: type: string nullable: true description: Settlement state (payment_in_progress, settled) status: type: string nullable: true description: Item status itemState: type: string nullable: true description: Kitchen-side item state ('aborted' = voided) voidedQuantityCents: type: number nullable: true description: Voided slice in cents (read from platform_events) — null when not aborted paidAmount: type: number nullable: true description: Amount paid for this item in cents createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp itemTitle: type: string nullable: true description: Item title from inventory itemTitlePrep: type: string nullable: true description: Item prep name from inventory itemDescription: type: string nullable: true description: Item description from inventory itemImageUrl: type: string nullable: true description: Item image URL from inventory tabMember: type: object nullable: true description: Guest/user information for the person who ordered this item properties: uuid: type: string format: uuid description: Tab member UUID name: type: string description: Member name email: type: string description: Member email phone: type: string description: Member phone number imageUrl: type: string description: Member profile image URL memberType: type: string description: Member type (guest, user, etc.) userId: type: number nullable: true description: User ID if authenticated user retailUserId: type: number nullable: true description: Retailer user ID if staff member comments: type: array description: Comments on this item items: type: object properties: comment: type: string createdAt: type: string format: date-time tabMemberUUID: type: string nullable: true uuid: type: string format: uuid variants: type: array description: Variants/modifications on this item items: type: object properties: id: type: number name: type: string price: type: number description: Price in cents (positive or negative) quantityCents: type: number nullable: true description: Quantity in cents (100 = 1.0). NULL = default 1.0 priceCents: type: number nullable: true description: Price at time of order in cents. NULL = look up from variants table required: - uuid - kitchenDispatchId - price - basePrice - quantity - createdAt - updatedAt description: Items in this dispatch required: - uuid - tabId - locationId - latestState - createdAt - updatedAt - kitchenDispatchItems description: Kitchen dispatches with items vouchers: type: array items: type: object properties: id: type: number description: tab_vouchers.id (use with DELETE /vouchers/applied/:id) discountId: type: number description: discounts.id discountCode: type: string description: Voucher code as entered appliedAt: type: string format: date-time voucherName: type: string nullable: true description: discounts.name (internal name) voucherType: type: string nullable: true typeSpecification: type: object nullable: true additionalProperties: true maxDiscountAmountCents: type: number nullable: true maxUses: type: number nullable: true timesUsed: type: number hasUsesLeft: type: boolean description: "Computed: maxUses null/0 OR timesUsed < maxUses" remainingBalanceCents: type: number nullable: true description: For gift cards displayTitle: type: string nullable: true description: Guest-facing title displayDescription: type: string nullable: true description: Guest-facing description displayImageUrl: type: string nullable: true description: Thumbnail URL required: - id - discountId - discountCode - appliedAt - timesUsed - hasUsesLeft description: Vouchers attached to this tab (from POS or storefront) notes: type: array items: type: object properties: uuid: type: string format: uuid description: Note UUID entityType: type: string description: Entity type (tab, user) entityId: type: string description: Entity ID (tab UUID or user ID) note: type: string description: Note content locationId: type: number description: Location ID sortOrder: type: number description: Sort order (0 = first/top) createdByRetailerUserId: type: number nullable: true description: Retailer user who created the note createdByName: type: string nullable: true description: Name of user who created the note updatedByRetailerUserId: type: number nullable: true description: Retailer user who last updated the note updatedByName: type: string nullable: true description: Name of user who last updated the note createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - entityType - entityId - note - locationId - sortOrder - createdAt - updatedAt description: Notes attached to this tab createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp location: type: object properties: id: type: number description: Location ID name: type: string description: Guest-facing location name (e.g. "Café Saturnus") logoImageUrl: type: string nullable: true description: Location logo URL for guest UI currency: type: string nullable: true description: ISO 4217 currency code (e.g. SEK) timezone: type: string nullable: true description: IANA timezone (e.g. Europe/Stockholm) slug: type: string nullable: true description: Location URL slug for storefront deep links required: - id - name - logoImageUrl - currency - timezone required: - uuid - locationId - latestState - paymentMode - totalAmountCents - paidAmountCents - remainingBalanceCents - tabMembers - location - createdAt - updatedAt required: - tabs meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/mine/{id}: get: summary: Get a single tab the authenticated guest is a member of tags: - Tabs description: Returns the same tab shape as GET /tabs/:id (members + items + location stub) but gated on tab_members.user_id matching the Bearer-authenticated guest. Returns 404 when the user is not a member of the tab. parameters: - schema: type: string format: uuid in: path name: id required: true description: Tab UUID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: uuid: type: string format: uuid description: Tab UUID locationId: type: number description: Location ID latestState: type: string enum: - initiated - started - instant - closed - settled - aborted - action_required description: Current tab state selectedPaymentFlow: type: string nullable: true enum: - open_tab - pay_upfront description: "Payment flow (open_tab: pay later, pay_upfront: pay now/instant pay)" paymentMode: type: string enum: - ITEM - AMOUNT description: "Payment mode (ITEM: pay per item, AMOUNT: pay arbitrary amounts)" paymentSplit: type: number nullable: true minimum: 2 maximum: 10 description: Number of splits when in AMOUNT mode (2-10), null when in ITEM mode totalAmountCents: type: number description: Total order amount in cents paidAmountCents: type: number description: Total paid amount in cents remainingBalanceCents: type: number description: Remaining balance to be paid in cents storefrontQrCodeId: type: string nullable: true description: Table/QR code UUID if applicable bookingId: type: string format: uuid nullable: true description: UUID of the booking/reservation that created this tab, if any. Null for tabs not created from a reservation. bookingConfirmationCode: type: string nullable: true description: Confirmation code of the linked booking, when the tab is bound to one. Used by the storefront to deep-link back to the booking confirmation page. tabMembers: type: array items: type: object properties: uuid: type: string format: uuid description: Tab member UUID storefrontSessionId: type: string nullable: true description: Storefront session ID initiator: type: boolean description: Whether this member initiated the tab memberType: type: string description: Member type (guest, user, etc.) userId: type: number nullable: true description: User ID if authenticated retailUserId: type: number nullable: true description: Retail user ID if applicable clientId: type: string nullable: true description: Client identifier (user UUID for identification) userEmail: type: string nullable: true description: User email (canonical, never overridden per-location) userName: type: string nullable: true description: Override-merged display name (falls back through retailer.name → ulo.display_name → users.name) isEnrolledInLoyalty: type: boolean description: Whether user is enrolled in location loyalty program createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - initiator - memberType - isEnrolledInLoyalty - createdAt - updatedAt description: Tab members memberCount: type: number description: Number of guest tab_members (party size; excludes staff) kitchenDispatches: type: array items: type: object properties: uuid: type: string format: uuid description: Kitchen dispatch UUID tabId: type: string format: uuid description: Tab UUID locationId: type: number description: Location ID dailyOrderNumber: type: number nullable: true description: Daily order number latestState: type: string description: Current state of the dispatch createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp kitchenDispatchItems: type: array items: type: object properties: uuid: type: string format: uuid description: Kitchen dispatch item UUID kitchenDispatchId: type: string format: uuid description: Kitchen dispatch UUID saleItemId: type: number nullable: true description: Sale item ID itemId: type: number nullable: true description: Inventory item ID tabMemberId: type: string nullable: true description: Tab member UUID who ordered this parentKitchenDispatchItemId: type: string nullable: true description: Parent kitchen dispatch item UUID (for nested items) price: type: number description: Item price in cents basePrice: type: number description: Base price before modifications in cents discount: type: number nullable: true description: Discount amount in cents quantity: type: number description: Quantity ordered quantityCents: type: number nullable: true description: Quantity in cents (for fractional items) splitOfKdi: type: string format: uuid nullable: true description: UUID of original item if this is a split item (for grouping) tabSettlementId: type: string nullable: true description: Settlement UUID if paid settlementState: type: string nullable: true description: Settlement state (payment_in_progress, settled) status: type: string nullable: true description: Item status itemState: type: string nullable: true description: Kitchen-side item state ('aborted' = voided) voidedQuantityCents: type: number nullable: true description: Voided slice in cents (read from platform_events) — null when not aborted paidAmount: type: number nullable: true description: Amount paid for this item in cents createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp itemTitle: type: string nullable: true description: Item title from inventory itemTitlePrep: type: string nullable: true description: Item prep name from inventory itemDescription: type: string nullable: true description: Item description from inventory itemImageUrl: type: string nullable: true description: Item image URL from inventory tabMember: type: object nullable: true description: Guest/user information for the person who ordered this item properties: uuid: type: string format: uuid description: Tab member UUID name: type: string description: Member name email: type: string description: Member email phone: type: string description: Member phone number imageUrl: type: string description: Member profile image URL memberType: type: string description: Member type (guest, user, etc.) userId: type: number nullable: true description: User ID if authenticated user retailUserId: type: number nullable: true description: Retailer user ID if staff member comments: type: array description: Comments on this item items: type: object properties: comment: type: string createdAt: type: string format: date-time tabMemberUUID: type: string nullable: true uuid: type: string format: uuid variants: type: array description: Variants/modifications on this item items: type: object properties: id: type: number name: type: string price: type: number description: Price in cents (positive or negative) quantityCents: type: number nullable: true description: Quantity in cents (100 = 1.0). NULL = default 1.0 priceCents: type: number nullable: true description: Price at time of order in cents. NULL = look up from variants table required: - uuid - kitchenDispatchId - price - basePrice - quantity - createdAt - updatedAt description: Items in this dispatch required: - uuid - tabId - locationId - latestState - createdAt - updatedAt - kitchenDispatchItems description: Kitchen dispatches with items vouchers: type: array items: type: object properties: id: type: number description: tab_vouchers.id (use with DELETE /vouchers/applied/:id) discountId: type: number description: discounts.id discountCode: type: string description: Voucher code as entered appliedAt: type: string format: date-time voucherName: type: string nullable: true description: discounts.name (internal name) voucherType: type: string nullable: true typeSpecification: type: object nullable: true additionalProperties: true maxDiscountAmountCents: type: number nullable: true maxUses: type: number nullable: true timesUsed: type: number hasUsesLeft: type: boolean description: "Computed: maxUses null/0 OR timesUsed < maxUses" remainingBalanceCents: type: number nullable: true description: For gift cards displayTitle: type: string nullable: true description: Guest-facing title displayDescription: type: string nullable: true description: Guest-facing description displayImageUrl: type: string nullable: true description: Thumbnail URL required: - id - discountId - discountCode - appliedAt - timesUsed - hasUsesLeft description: Vouchers attached to this tab (from POS or storefront) notes: type: array items: type: object properties: uuid: type: string format: uuid description: Note UUID entityType: type: string description: Entity type (tab, user) entityId: type: string description: Entity ID (tab UUID or user ID) note: type: string description: Note content locationId: type: number description: Location ID sortOrder: type: number description: Sort order (0 = first/top) createdByRetailerUserId: type: number nullable: true description: Retailer user who created the note createdByName: type: string nullable: true description: Name of user who created the note updatedByRetailerUserId: type: number nullable: true description: Retailer user who last updated the note updatedByName: type: string nullable: true description: Name of user who last updated the note createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - entityType - entityId - note - locationId - sortOrder - createdAt - updatedAt description: Notes attached to this tab createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp location: type: object properties: id: type: number description: Location ID name: type: string description: Guest-facing location name (e.g. "Café Saturnus") logoImageUrl: type: string nullable: true description: Location logo URL for guest UI currency: type: string nullable: true description: ISO 4217 currency code (e.g. SEK) timezone: type: string nullable: true description: IANA timezone (e.g. Europe/Stockholm) slug: type: string nullable: true description: Location URL slug for storefront deep links required: - id - name - logoImageUrl - currency - timezone kitchenDispatchItems: type: array items: type: object properties: uuid: type: string format: uuid description: Kitchen dispatch item UUID kitchenDispatchId: type: string format: uuid description: Kitchen dispatch UUID saleItemId: type: number nullable: true description: Sale item ID itemId: type: number nullable: true description: Inventory item ID tabMemberId: type: string nullable: true description: Tab member UUID who ordered this parentKitchenDispatchItemId: type: string nullable: true description: Parent kitchen dispatch item UUID (for nested items) price: type: number description: Item price in cents basePrice: type: number description: Base price before modifications in cents discount: type: number nullable: true description: Discount amount in cents quantity: type: number description: Quantity ordered quantityCents: type: number nullable: true description: Quantity in cents (for fractional items) splitOfKdi: type: string format: uuid nullable: true description: UUID of original item if this is a split item (for grouping) tabSettlementId: type: string nullable: true description: Settlement UUID if paid settlementState: type: string nullable: true description: Settlement state (payment_in_progress, settled) status: type: string nullable: true description: Item status itemState: type: string nullable: true description: Kitchen-side item state ('aborted' = voided) voidedQuantityCents: type: number nullable: true description: Voided slice in cents (read from platform_events) — null when not aborted paidAmount: type: number nullable: true description: Amount paid for this item in cents createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp itemTitle: type: string nullable: true description: Item title from inventory itemTitlePrep: type: string nullable: true description: Item prep name from inventory itemDescription: type: string nullable: true description: Item description from inventory itemImageUrl: type: string nullable: true description: Item image URL from inventory tabMember: type: object nullable: true description: Guest/user information for the person who ordered this item properties: uuid: type: string format: uuid description: Tab member UUID name: type: string description: Member name email: type: string description: Member email phone: type: string description: Member phone number imageUrl: type: string description: Member profile image URL memberType: type: string description: Member type (guest, user, etc.) userId: type: number nullable: true description: User ID if authenticated user retailUserId: type: number nullable: true description: Retailer user ID if staff member comments: type: array description: Comments on this item items: type: object properties: comment: type: string createdAt: type: string format: date-time tabMemberUUID: type: string nullable: true uuid: type: string format: uuid variants: type: array description: Variants/modifications on this item items: type: object properties: id: type: number name: type: string price: type: number description: Price in cents (positive or negative) quantityCents: type: number nullable: true description: Quantity in cents (100 = 1.0). NULL = default 1.0 priceCents: type: number nullable: true description: Price at time of order in cents. NULL = look up from variants table required: - uuid - kitchenDispatchId - price - basePrice - quantity - createdAt - updatedAt description: Items currently on the tab. required: - uuid - locationId - latestState - paymentMode - totalAmountCents - paidAmountCents - remainingBalanceCents - tabMembers - location - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/reconnect-payment: post: summary: Reconnect orphaned Adyen payment tags: - Tabs description: >- Reconnect a payment that was authorized in Adyen but not recorded in Karma (due to terminal timeout). Creates a new purchase using the existing Adyen PSP reference. Karmeleon-only. **Permissions:** 🟠 `tabs.update` requestBody: content: application/json: schema: type: object required: - tab_id - psp_reference properties: tab_id: type: string format: uuid description: UUID of the tab to reconnect payment for psp_reference: type: string description: Adyen PSP reference from the orphaned authorization terminal_id: type: string format: uuid description: Terminal ID (optional, for audit trail) amount_cents: type: number minimum: 1 description: Amount in cents (optional, defaults to remaining balance) required: true responses: "200": description: Payment reconnected successfully content: application/json: schema: description: Payment reconnected successfully type: object properties: status: type: string enum: - success data: type: object properties: purchase_intent_id: type: string format: uuid tab_settlement_id: type: string format: uuid tab_id: type: string format: uuid psp_reference: type: string amount_cents: type: number reconnected: type: boolean meta: type: object "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tabs/resolve: post: summary: Resolve tab for user tags: - Tabs description: >- Find existing tab or create new tab for a user. Handles QR code tables, user resolution with priority system (id > email > phone > identifier), tab member management, and order channel routing. Perfect for storefront integration before item commits. **Permissions:** 🟢 `tabs.create` requestBody: content: application/json: schema: type: object properties: locationId: type: number description: Location ID for the tab qrCodeId: type: string nullable: true description: QR code UUID (for table orders) tabType: type: string enum: - table - takeaway - over_the_counter description: Type of tab to create paymentFlow: type: string enum: - open_tab - pay_upfront description: Payment timing (open_tab = pay later, pay_upfront = pay now) orderChannel: type: string enum: - ONLINE - QR - KIOSK - POS description: Order channel (ONLINE = web interface, QR = QR code scan, KIOSK = self-service, POS = point of sale) tabMember: type: object properties: id: type: number description: User ID (Priority 1 - existing user) email: type: string format: email description: Email address (Priority 2 - finds or creates user) phone: type: string description: Phone number (Priority 3 - finds or creates user) identifier: type: string description: Device identifier (Priority 4 - creates anonymous user) language: type: string description: BCP-47 locale code detected from the guest's browser (e.g. en, sv, fr) additionalProperties: false description: "User identification with priority-based resolution: id > email > phone > identifier" required: - locationId - qrCodeId - tabType - paymentFlow - orderChannel - tabMember additionalProperties: false required: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: tabId: type: string format: uuid description: Resolved tab UUID tabMemberId: type: string format: uuid description: Tab member UUID for this user isNewTab: type: boolean description: True if tab was newly created isNewTabMember: type: boolean description: True if tab member was newly created tab: type: object properties: uuid: type: string format: uuid description: Tab UUID locationId: type: number description: Location ID latestState: type: string enum: - initiated - started - instant - closed - settled - aborted - action_required description: Current tab state selectedPaymentFlow: type: string nullable: true enum: - open_tab - pay_upfront description: "Payment flow (open_tab: pay later, pay_upfront: pay now/instant pay)" paymentMode: type: string enum: - ITEM - AMOUNT description: "Payment mode (ITEM: pay per item, AMOUNT: pay arbitrary amounts)" paymentSplit: type: number nullable: true minimum: 2 maximum: 10 description: Number of splits when in AMOUNT mode (2-10), null when in ITEM mode totalAmountCents: type: number description: Total order amount in cents paidAmountCents: type: number description: Total paid amount in cents remainingBalanceCents: type: number description: Remaining balance to be paid in cents storefrontQrCodeId: type: string nullable: true description: Table/QR code UUID if applicable bookingId: type: string format: uuid nullable: true description: UUID of the booking/reservation that created this tab, if any. Null for tabs not created from a reservation. bookingConfirmationCode: type: string nullable: true description: Confirmation code of the linked booking, when the tab is bound to one. Used by the storefront to deep-link back to the booking confirmation page. tabMembers: type: array items: type: object properties: uuid: type: string format: uuid description: Tab member UUID storefrontSessionId: type: string nullable: true description: Storefront session ID initiator: type: boolean description: Whether this member initiated the tab memberType: type: string description: Member type (guest, user, etc.) userId: type: number nullable: true description: User ID if authenticated retailUserId: type: number nullable: true description: Retail user ID if applicable clientId: type: string nullable: true description: Client identifier (user UUID for identification) userEmail: type: string nullable: true description: User email (canonical, never overridden per-location) userName: type: string nullable: true description: Override-merged display name (falls back through retailer.name → ulo.display_name → users.name) isEnrolledInLoyalty: type: boolean description: Whether user is enrolled in location loyalty program createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - initiator - memberType - isEnrolledInLoyalty - createdAt - updatedAt description: Tab members memberCount: type: number description: Number of guest tab_members (party size; excludes staff) kitchenDispatches: type: array items: type: object properties: uuid: type: string format: uuid description: Kitchen dispatch UUID tabId: type: string format: uuid description: Tab UUID locationId: type: number description: Location ID dailyOrderNumber: type: number nullable: true description: Daily order number latestState: type: string description: Current state of the dispatch createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp kitchenDispatchItems: type: array items: type: object properties: uuid: type: string format: uuid description: Kitchen dispatch item UUID kitchenDispatchId: type: string format: uuid description: Kitchen dispatch UUID saleItemId: type: number nullable: true description: Sale item ID itemId: type: number nullable: true description: Inventory item ID tabMemberId: type: string nullable: true description: Tab member UUID who ordered this parentKitchenDispatchItemId: type: string nullable: true description: Parent kitchen dispatch item UUID (for nested items) price: type: number description: Item price in cents basePrice: type: number description: Base price before modifications in cents discount: type: number nullable: true description: Discount amount in cents quantity: type: number description: Quantity ordered quantityCents: type: number nullable: true description: Quantity in cents (for fractional items) splitOfKdi: type: string format: uuid nullable: true description: UUID of original item if this is a split item (for grouping) tabSettlementId: type: string nullable: true description: Settlement UUID if paid settlementState: type: string nullable: true description: Settlement state (payment_in_progress, settled) status: type: string nullable: true description: Item status itemState: type: string nullable: true description: Kitchen-side item state ('aborted' = voided) voidedQuantityCents: type: number nullable: true description: Voided slice in cents (read from platform_events) — null when not aborted paidAmount: type: number nullable: true description: Amount paid for this item in cents createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp itemTitle: type: string nullable: true description: Item title from inventory itemTitlePrep: type: string nullable: true description: Item prep name from inventory itemDescription: type: string nullable: true description: Item description from inventory itemImageUrl: type: string nullable: true description: Item image URL from inventory tabMember: type: object nullable: true description: Guest/user information for the person who ordered this item properties: uuid: type: string format: uuid description: Tab member UUID name: type: string description: Member name email: type: string description: Member email phone: type: string description: Member phone number imageUrl: type: string description: Member profile image URL memberType: type: string description: Member type (guest, user, etc.) userId: type: number nullable: true description: User ID if authenticated user retailUserId: type: number nullable: true description: Retailer user ID if staff member comments: type: array description: Comments on this item items: type: object properties: comment: type: string createdAt: type: string format: date-time tabMemberUUID: type: string nullable: true uuid: type: string format: uuid variants: type: array description: Variants/modifications on this item items: type: object properties: id: type: number name: type: string price: type: number description: Price in cents (positive or negative) quantityCents: type: number nullable: true description: Quantity in cents (100 = 1.0). NULL = default 1.0 priceCents: type: number nullable: true description: Price at time of order in cents. NULL = look up from variants table required: - uuid - kitchenDispatchId - price - basePrice - quantity - createdAt - updatedAt description: Items in this dispatch required: - uuid - tabId - locationId - latestState - createdAt - updatedAt - kitchenDispatchItems description: Kitchen dispatches with items vouchers: type: array items: type: object properties: id: type: number description: tab_vouchers.id (use with DELETE /vouchers/applied/:id) discountId: type: number description: discounts.id discountCode: type: string description: Voucher code as entered appliedAt: type: string format: date-time voucherName: type: string nullable: true description: discounts.name (internal name) voucherType: type: string nullable: true typeSpecification: type: object nullable: true additionalProperties: true maxDiscountAmountCents: type: number nullable: true maxUses: type: number nullable: true timesUsed: type: number hasUsesLeft: type: boolean description: "Computed: maxUses null/0 OR timesUsed < maxUses" remainingBalanceCents: type: number nullable: true description: For gift cards displayTitle: type: string nullable: true description: Guest-facing title displayDescription: type: string nullable: true description: Guest-facing description displayImageUrl: type: string nullable: true description: Thumbnail URL required: - id - discountId - discountCode - appliedAt - timesUsed - hasUsesLeft description: Vouchers attached to this tab (from POS or storefront) notes: type: array items: type: object properties: uuid: type: string format: uuid description: Note UUID entityType: type: string description: Entity type (tab, user) entityId: type: string description: Entity ID (tab UUID or user ID) note: type: string description: Note content locationId: type: number description: Location ID sortOrder: type: number description: Sort order (0 = first/top) createdByRetailerUserId: type: number nullable: true description: Retailer user who created the note createdByName: type: string nullable: true description: Name of user who created the note updatedByRetailerUserId: type: number nullable: true description: Retailer user who last updated the note updatedByName: type: string nullable: true description: Name of user who last updated the note createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - entityType - entityId - note - locationId - sortOrder - createdAt - updatedAt description: Notes attached to this tab createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - locationId - latestState - paymentMode - totalAmountCents - paidAmountCents - remainingBalanceCents - tabMembers - createdAt - updatedAt tabMembers: type: array items: type: object properties: uuid: type: string format: uuid description: Tab member UUID storefrontSessionId: type: string nullable: true description: Storefront session ID initiator: type: boolean description: Whether this member initiated the tab memberType: type: string description: Member type (guest, user, etc.) userId: type: number nullable: true description: User ID if authenticated retailUserId: type: number nullable: true description: Retail user ID if applicable clientId: type: string nullable: true description: Client identifier (user UUID for identification) userEmail: type: string nullable: true description: User email (canonical, never overridden per-location) userName: type: string nullable: true description: Override-merged display name (falls back through retailer.name → ulo.display_name → users.name) isEnrolledInLoyalty: type: boolean description: Whether user is enrolled in location loyalty program createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - uuid - initiator - memberType - isEnrolledInLoyalty - createdAt - updatedAt description: All current tab members required: - tabId - tabMemberId - isNewTab - isNewTabMember - tab - tabMembers additionalProperties: false meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/terminals: get: summary: List payment terminals tags: - Terminals description: |- Get all payment terminals for a location **Permissions:** 🔵 `terminals.read` parameters: - schema: type: string in: query name: locationId required: true description: Location ID to fetch terminals for responses: "200": description: Terminals fetched successfully content: application/json: schema: description: Terminals fetched successfully type: object properties: status: type: string enum: - success data: type: array items: type: object properties: id: type: string format: uuid description: Terminal UUID externalId: type: string description: External terminal ID from payment provider locationId: type: integer description: Location ID this terminal belongs to createdAt: type: string format: date-time description: Terminal creation timestamp updatedAt: type: string format: date-time description: Terminal last update timestamp title: type: string description: Terminal display name type: oneOf: - type: string enum: - p400plus - s1f2 - s1u2 - s1e2l - v400cplus - v400m - any description: Terminal hardware type - type: "null" description: Terminal hardware type (null if not specified) required: - id - externalId - locationId - createdAt - updatedAt - title - type description: Array of terminals meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: responses: "200": description: Default Response /api/v1/terminals/statuses: get: summary: Get terminal statuses tags: - Terminals description: |- Get real-time connection status for all terminals at a location **Permissions:** 🔵 `terminals.read` parameters: - schema: type: string in: query name: locationId required: true description: Location ID to fetch terminal statuses for responses: "200": description: Terminal statuses fetched successfully content: application/json: schema: description: Terminal statuses fetched successfully type: object properties: status: type: string enum: - success data: type: object properties: terminals: type: array items: type: object properties: id: type: string format: uuid description: Terminal UUID externalId: type: string description: External terminal ID from payment provider locationId: type: integer description: Location ID this terminal belongs to createdAt: type: string format: date-time description: Terminal creation timestamp updatedAt: type: string format: date-time description: Terminal last update timestamp title: type: string description: Terminal display name type: oneOf: - type: string enum: - p400plus - s1f2 - s1u2 - s1e2l - v400cplus - v400m - any description: Terminal hardware type - type: "null" description: Terminal hardware type (null if not specified) required: - id - externalId - locationId - createdAt - updatedAt - title - type description: Array of terminals message: type: string description: Information about status updates required: - terminals - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/locations/{locationId}/time-slots/{date}: get: summary: Get time slots for a location on a specific date tags: - Time Slots description: > Generates available time slots for pickup/ordering at a location on a specific date. Time slots are generated based on: - The location's opening hours from the schedules system - The location's configured time slot duration (e.g., 10 or 15 minutes) - Any exceptions (holidays, special closures) If the location is closed on the requested date (either by regular hours or exception), an empty time slots array is returned. **Note:** This endpoint requires API key authentication. parameters: - schema: type: string in: path name: locationId required: true description: Location ID - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ in: path name: date required: true description: Date in YYYY-MM-DD format responses: "200": description: Time slots retrieved successfully content: application/json: schema: description: Time slots retrieved successfully type: object properties: status: type: string enum: - success data: type: object properties: timeSlots: type: array items: type: object properties: startsAt: type: string format: date-time description: Slot start time (ISO 8601) endsAt: type: string format: date-time description: Slot end time (ISO 8601) capacities: type: object nullable: true properties: orders: type: object nullable: true properties: capacity: type: number description: Maximum allowed capacity count: type: number description: Current count required: - capacity - count items: type: object nullable: true properties: capacity: type: number description: Maximum allowed capacity count: type: number description: Current count required: - capacity - count required: - orders - items required: - startsAt - endsAt description: List of available time slots required: - timeSlots meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tokens/balance: get: tags: - Tokens description: Get token balance and limits for a location parameters: - schema: type: number in: query name: locationId required: true description: Location ID to get token balance for x-internal: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: locationId: type: number balance: type: number description: Current token balance monthlyLimit: type: number nullable: true description: Monthly token limit (null = unlimited) dailyLimit: type: number nullable: true description: Daily token limit (null = unlimited) totalUsed: type: number description: Total tokens used (lifetime) usageToday: type: number description: Tokens used today usageThisMonth: type: number description: Tokens used this month lastResetAt: type: string format: date-time nullable: true meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/tokens/usage: get: tags: - Tokens description: Get token usage history with filtering and pagination parameters: - schema: type: number in: query name: locationId required: true description: Location ID to get usage for - schema: type: string format: date-time in: query name: startDate required: false description: Filter from this date (ISO 8601) - schema: type: string format: date-time in: query name: endDate required: false description: Filter to this date (ISO 8601) - schema: type: string enum: - llm_input - llm_output - bigquery - image_gen - content_gen in: query name: transactionType required: false description: Filter by transaction type - schema: type: number default: 1 minimum: 1 in: query name: page required: false description: Page number - schema: type: number default: 50 minimum: 1 maximum: 1000 in: query name: limit required: false description: Items per page (max 1000) x-internal: true responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: transactions: type: array items: type: object properties: id: type: number transactionType: type: string tokensUsed: type: number costCents: type: number nullable: true serviceName: type: string nullable: true metadata: type: object nullable: true createdAt: type: string format: date-time createdBy: type: object nullable: true properties: id: type: number name: type: string pagination: type: object properties: page: type: number limit: type: number totalItems: type: number totalPages: type: number summary: type: object properties: totalTokens: type: number totalCostCents: type: number byType: type: object additionalProperties: type: number meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/translations/inventory: get: tags: - Translations description: Get translated inventory items by location and locale with ID-keyed response for simple client merging parameters: - schema: type: number in: query name: locationId required: true description: Location ID - schema: type: string enum: - en - sv - no - fi - es - de - fr - ar - pl - ru - zh - ja in: query name: locale required: true description: Target language code - schema: type: boolean default: false in: query name: includeVariants required: false description: Include variant group translations - schema: type: number default: 1 minimum: 1 in: query name: page required: false description: Page number for pagination - schema: type: number default: 100 minimum: 1 maximum: 1000 in: query name: limit required: false description: Items per page (max 1000) responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: inventory: type: object description: ID-keyed inventory translations (item ID → translations) additionalProperties: type: object properties: title: type: string description: Translated item title description: type: string description: Translated item description ingredients: type: string description: Translated item ingredients required: - title variants: type: object description: ID-keyed variant group translations (variant group ID → translations) additionalProperties: type: object properties: title: type: string description: Translated variant group title choices: type: object description: ID-keyed choice translations (choice ID → translations) additionalProperties: type: object properties: title: type: string description: Translated choice title required: - title required: - title - choices metadata: type: object properties: totalItems: type: number description: Total number of items translated uniqueStrings: type: number description: Number of unique strings (after deduplication) cacheHits: type: number description: Number of translations served from cache cacheMisses: type: number description: Number of translations fetched from Google Translate executionTimeMs: type: number description: Total execution time in milliseconds required: - totalItems - uniqueStrings - cacheHits - cacheMisses - executionTimeMs required: - inventory - variants - metadata meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid parameters content: application/json: schema: type: object description: Bad Request - Invalid parameters properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object description: Forbidden - Insufficient permissions properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string "500": description: Internal Server Error content: application/json: schema: type: object description: Internal Server Error properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string /api/v1/variant-groups: get: summary: List variant groups tags: - Variant Groups description: |- List variant groups with optional filtering **Permissions:** 🔵 `variant_groups.read` parameters: - schema: type: number in: query name: locationId required: false description: Filter by location ID - schema: type: string enum: - EXTRA - VARIANT in: query name: type required: false description: Filter by group type - schema: type: boolean default: true in: query name: includeVariants required: false description: Include variants in response - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: number minimum: 1 maximum: 100 default: 20 in: query name: limit required: false description: Items per page responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: variantGroups: type: array items: type: object properties: id: type: number description: Unique variant group ID locationId: type: number description: Location ID this group belongs to name: type: string description: Variant group name type: type: string enum: - EXTRA - VARIANT description: "Group type (EXTRA: add-ons, VARIANT: alternatives)" description: type: string nullable: true description: Group description min: type: number minimum: 0 description: Minimum number of variants that must be selected (0 = optional) max: type: number nullable: true description: Maximum number of variants that can be selected (null = unlimited) isVisible: type: boolean description: Whether the variant group is visible in UI useChildCoursing: type: boolean description: When true, item-based variant children commit with their own coursing_order instead of inheriting the parent item's variants: type: array items: type: object properties: id: type: number description: Unique variant ID variantGroupId: type: number description: Variant group ID this belongs to name: type: string description: Variant name price: type: number nullable: true description: Price modifier in cents (null for item-based variants) defaultSelection: type: boolean description: Whether this is selected by default description: type: string nullable: true description: Variant description rank: type: number nullable: true description: Display order rank itemId: type: number nullable: true description: Reference to inventory item (for item-based variants) quantity: type: number description: "Legacy: default quantity as integer (use quantityCents instead)" allowQuantityChange: type: boolean description: Whether guests can change the quantity minQuantity: type: number nullable: true description: "Legacy: minimum quantity as integer (use minQuantityCents instead)" maxQuantity: type: number nullable: true description: "Legacy: maximum quantity as integer (use maxQuantityCents instead)" quantityCents: type: number description: Default quantity in cents (100 = 1.0, 50 = 0.5) minQuantityCents: type: number nullable: true description: Minimum quantity in cents (only applies if allowQuantityChange is true) maxQuantityCents: type: number nullable: true description: Maximum quantity in cents (only applies if allowQuantityChange is true) required: - id - variantGroupId - name - defaultSelection - quantity - allowQuantityChange - quantityCents description: Variants in this group required: - id - locationId - name - type - min - isVisible - useChildCoursing - variants pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages required: - variantGroups - pagination meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: summary: Create variant group tags: - Variant Groups description: |- Create a new variant group with variants **Permissions:** 🟢 `variant_groups.create` requestBody: content: application/json: schema: type: object properties: locationId: type: number description: Location ID name: type: string minLength: 1 description: Group name type: type: string enum: - EXTRA - VARIANT description: type: string nullable: true min: type: number minimum: 0 default: 0 max: type: number nullable: true minimum: 1 isVisible: type: boolean default: true useChildCoursing: type: boolean default: false description: When true, item-based variant children commit with their own coursing_order variants: type: array items: type: object properties: name: type: string minLength: 1 description: Variant name price: type: number nullable: true description: Price modifier in cents defaultSelection: type: boolean default: false description: type: string nullable: true rank: type: number nullable: true itemId: type: number nullable: true description: Reference to inventory item quantity: type: number default: 1 minimum: 1 description: "Legacy: default quantity as integer" allowQuantityChange: type: boolean default: false quantityCents: type: number default: 100 minimum: 1 description: Default quantity in cents (100 = 1.0, 50 = 0.5). Takes precedence over quantity. minQuantityCents: type: number nullable: true description: Minimum quantity in cents maxQuantityCents: type: number nullable: true description: Maximum quantity in cents required: - name description: Initial variants for this group required: - locationId - name - type - variants required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Unique variant group ID locationId: type: number description: Location ID this group belongs to name: type: string description: Variant group name type: type: string enum: - EXTRA - VARIANT description: "Group type (EXTRA: add-ons, VARIANT: alternatives)" description: type: string nullable: true description: Group description min: type: number minimum: 0 description: Minimum number of variants that must be selected (0 = optional) max: type: number nullable: true description: Maximum number of variants that can be selected (null = unlimited) isVisible: type: boolean description: Whether the variant group is visible in UI useChildCoursing: type: boolean description: When true, item-based variant children commit with their own coursing_order instead of inheriting the parent item's variants: type: array items: type: object properties: id: type: number description: Unique variant ID variantGroupId: type: number description: Variant group ID this belongs to name: type: string description: Variant name price: type: number nullable: true description: Price modifier in cents (null for item-based variants) defaultSelection: type: boolean description: Whether this is selected by default description: type: string nullable: true description: Variant description rank: type: number nullable: true description: Display order rank itemId: type: number nullable: true description: Reference to inventory item (for item-based variants) quantity: type: number description: "Legacy: default quantity as integer (use quantityCents instead)" allowQuantityChange: type: boolean description: Whether guests can change the quantity minQuantity: type: number nullable: true description: "Legacy: minimum quantity as integer (use minQuantityCents instead)" maxQuantity: type: number nullable: true description: "Legacy: maximum quantity as integer (use maxQuantityCents instead)" quantityCents: type: number description: Default quantity in cents (100 = 1.0, 50 = 0.5) minQuantityCents: type: number nullable: true description: Minimum quantity in cents (only applies if allowQuantityChange is true) maxQuantityCents: type: number nullable: true description: Maximum quantity in cents (only applies if allowQuantityChange is true) required: - id - variantGroupId - name - defaultSelection - quantity - allowQuantityChange - quantityCents description: Variants in this group required: - id - locationId - name - type - min - isVisible - useChildCoursing - variants meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/variant-groups/{id}: get: summary: Get variant group tags: - Variant Groups description: |- Get a single variant group by ID with its variants **Permissions:** 🔵 `variant_groups.read` parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: id required: true description: Variant group ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Unique variant group ID locationId: type: number description: Location ID this group belongs to name: type: string description: Variant group name type: type: string enum: - EXTRA - VARIANT description: "Group type (EXTRA: add-ons, VARIANT: alternatives)" description: type: string nullable: true description: Group description min: type: number minimum: 0 description: Minimum number of variants that must be selected (0 = optional) max: type: number nullable: true description: Maximum number of variants that can be selected (null = unlimited) isVisible: type: boolean description: Whether the variant group is visible in UI useChildCoursing: type: boolean description: When true, item-based variant children commit with their own coursing_order instead of inheriting the parent item's variants: type: array items: type: object properties: id: type: number description: Unique variant ID variantGroupId: type: number description: Variant group ID this belongs to name: type: string description: Variant name price: type: number nullable: true description: Price modifier in cents (null for item-based variants) defaultSelection: type: boolean description: Whether this is selected by default description: type: string nullable: true description: Variant description rank: type: number nullable: true description: Display order rank itemId: type: number nullable: true description: Reference to inventory item (for item-based variants) quantity: type: number description: "Legacy: default quantity as integer (use quantityCents instead)" allowQuantityChange: type: boolean description: Whether guests can change the quantity minQuantity: type: number nullable: true description: "Legacy: minimum quantity as integer (use minQuantityCents instead)" maxQuantity: type: number nullable: true description: "Legacy: maximum quantity as integer (use maxQuantityCents instead)" quantityCents: type: number description: Default quantity in cents (100 = 1.0, 50 = 0.5) minQuantityCents: type: number nullable: true description: Minimum quantity in cents (only applies if allowQuantityChange is true) maxQuantityCents: type: number nullable: true description: Maximum quantity in cents (only applies if allowQuantityChange is true) required: - id - variantGroupId - name - defaultSelection - quantity - allowQuantityChange - quantityCents description: Variants in this group required: - id - locationId - name - type - min - isVisible - useChildCoursing - variants meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: summary: Update variant group tags: - Variant Groups description: |- Update an existing variant group **Permissions:** 🟠 `variant_groups.update` requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 description: type: string nullable: true min: type: number minimum: 0 max: type: number nullable: true minimum: 1 isVisible: type: boolean useChildCoursing: type: boolean description: When true, item-based variant children commit with their own coursing_order parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: id required: true description: Variant group ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: number description: Unique variant group ID locationId: type: number description: Location ID this group belongs to name: type: string description: Variant group name type: type: string enum: - EXTRA - VARIANT description: "Group type (EXTRA: add-ons, VARIANT: alternatives)" description: type: string nullable: true description: Group description min: type: number minimum: 0 description: Minimum number of variants that must be selected (0 = optional) max: type: number nullable: true description: Maximum number of variants that can be selected (null = unlimited) isVisible: type: boolean description: Whether the variant group is visible in UI useChildCoursing: type: boolean description: When true, item-based variant children commit with their own coursing_order instead of inheriting the parent item's variants: type: array items: type: object properties: id: type: number description: Unique variant ID variantGroupId: type: number description: Variant group ID this belongs to name: type: string description: Variant name price: type: number nullable: true description: Price modifier in cents (null for item-based variants) defaultSelection: type: boolean description: Whether this is selected by default description: type: string nullable: true description: Variant description rank: type: number nullable: true description: Display order rank itemId: type: number nullable: true description: Reference to inventory item (for item-based variants) quantity: type: number description: "Legacy: default quantity as integer (use quantityCents instead)" allowQuantityChange: type: boolean description: Whether guests can change the quantity minQuantity: type: number nullable: true description: "Legacy: minimum quantity as integer (use minQuantityCents instead)" maxQuantity: type: number nullable: true description: "Legacy: maximum quantity as integer (use maxQuantityCents instead)" quantityCents: type: number description: Default quantity in cents (100 = 1.0, 50 = 0.5) minQuantityCents: type: number nullable: true description: Minimum quantity in cents (only applies if allowQuantityChange is true) maxQuantityCents: type: number nullable: true description: Maximum quantity in cents (only applies if allowQuantityChange is true) required: - id - variantGroupId - name - defaultSelection - quantity - allowQuantityChange - quantityCents description: Variants in this group required: - id - locationId - name - type - min - isVisible - useChildCoursing - variants meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete variant group tags: - Variant Groups description: |- Delete a variant group and its variants **Permissions:** 🔴 `variant_groups.delete` parameters: - schema: type: string pattern: ^[0-9]+$ in: path name: id required: true description: Variant group ID responses: "200": description: Variant group successfully deleted content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: deleted: type: boolean meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/vouchers: get: summary: List vouchers tags: - Vouchers description: |- List all vouchers with optional filters and pagination **Permissions:** 🔵 `vouchers.read` parameters: - schema: type: number in: query name: location_id required: false description: Filter by location ID - schema: type: number in: query name: company_id required: false description: Filter by company ID - schema: type: string enum: - DISCOUNT_CODE - GIFT_CARD - PROMOTION - LOYALTY_REWARD - CAMPAIGN - REFERRAL in: query name: voucher_type required: false description: Filter by voucher type - schema: type: boolean in: query name: enabled required: false description: Filter by enabled status - schema: type: boolean in: query name: is_template required: false description: Filter by template status - schema: type: string in: query name: code required: false description: Exact code match - schema: type: string in: query name: search required: false description: Search in name or code - schema: type: boolean in: query name: include_restrictions required: false description: Include restrictions in response - schema: type: number default: 1 minimum: 1 in: query name: page required: false - schema: type: number default: 50 minimum: 1 maximum: 1000 in: query name: limit required: false - schema: type: string default: created_at in: query name: sort required: false - schema: type: string enum: - ASC - DESC default: DESC in: query name: order required: false responses: "200": description: List of vouchers content: application/json: schema: description: List of vouchers type: object properties: status: type: string enum: - success data: type: object properties: vouchers: type: array items: type: object properties: id: type: number locationId: type: number nullable: true companyId: type: number nullable: true name: type: string code: type: string enabled: type: boolean voucherType: type: string enum: - DISCOUNT_CODE - GIFT_CARD - PROMOTION - LOYALTY_REWARD - CAMPAIGN - REFERRAL balanceMode: type: string enum: - NONE - DECREMENTAL typeSpecification: type: object properties: type: type: string enum: - percentage - fixed - balance - free_item - fixed_price - formula amountInBasisPoints: type: number description: For percentage discounts (10000 = 100%) amountInCents: type: number description: For fixed amount discounts freeItemIds: type: array items: type: number description: Free-item product IDs (multi-select). Any matching cart item is free up to freeItemQuantity per line. freeItemQuantity: type: number description: Per-line cap for free items (defaults to 1) freeItemId: type: number description: DEPRECATED — use freeItemIds. Retained for legacy vouchers. targetItemIds: type: array items: type: number description: "For fixed_price action: items repriced down to fixedPriceCents." fixedPriceCents: type: number description: "For fixed_price action: target per-unit base price in cents." formula: type: object properties: type: type: string enum: - buy_x_get_y - tiered - spend_threshold - bundle - combo_groups rules: type: object description: "Formula-specific rules. For combo_groups: { groups: [{ quantity, itemIds?, tagIds?, variantIds? }], bundlePriceCents }." required: - type maxUses: type: number nullable: true timesUsed: type: number perUserUses: type: number nullable: true minOrderAmountCents: type: number nullable: true maxDiscountAmountCents: type: number nullable: true initialBalanceCents: type: number nullable: true remainingBalanceCents: type: number nullable: true canCombine: type: boolean autoApply: type: boolean validFrom: type: string format: date-time validUntil: type: string format: date-time nullable: true displayTitle: type: string nullable: true displayDescription: type: string nullable: true displayImageUrl: type: string nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time restrictions: type: array items: type: object properties: id: type: number discountId: type: number restrictionType: type: string enum: - INCLUDE_ITEM - EXCLUDE_ITEM - INCLUDE_TAG - EXCLUDE_TAG - INCLUDE_LAYOUT - EXCLUDE_LAYOUT - INCLUDE_VARIANT - EXCLUDE_VARIANT - REQUIRE_ITEM - REQUIRE_ITEM_WITH_VARIANTS - REQUIRE_TAG - MIN_ITEM_COUNT entityId: type: number quantity: type: number nullable: true variantIds: type: array items: type: number nullable: true description: Required variant ids on the same line for REQUIRE_ITEM_WITH_VARIANTS rows. createdAt: type: string format: date-time userRestrictions: type: array items: type: object properties: id: type: number discountId: type: number restrictionType: type: string enum: - EMAIL - PHONE - USER_ID - SEGMENT_ID value: type: string createdAt: type: string format: date-time pagination: type: object properties: page: type: number limit: type: number total: type: number totalPages: type: number meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "400": description: Bad Request - Invalid input content: application/json: schema: description: Bad Request - Invalid input type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: description: Unauthorized - Missing or invalid API key type: object "403": description: Forbidden - Insufficient permissions content: application/json: schema: description: Forbidden - Insufficient permissions type: object "404": description: Not Found - Resource not found content: application/json: schema: description: Not Found - Resource not found type: object "500": description: Internal Server Error content: application/json: schema: description: Internal Server Error type: object post: summary: Create voucher tags: - Vouchers description: |- Create a new voucher with optional restrictions **Permissions:** 🟢 `vouchers.create` requestBody: content: application/json: schema: type: object required: - name - code - voucherType - typeSpecification properties: locationId: type: number description: Location ID (required if companyId not set) companyId: type: number description: Company ID (required if locationId not set) name: type: string description: Internal voucher name code: type: string description: Voucher code (will be uppercased) enabled: type: boolean default: true voucherType: type: string enum: - DISCOUNT_CODE - GIFT_CARD - PROMOTION - LOYALTY_REWARD - CAMPAIGN - REFERRAL balanceMode: type: string enum: - NONE - DECREMENTAL default: NONE typeSpecification: type: object properties: type: type: string enum: - percentage - fixed - balance - free_item - fixed_price - formula amountInBasisPoints: type: number description: For percentage discounts (10000 = 100%) amountInCents: type: number description: For fixed amount discounts freeItemIds: type: array items: type: number description: Free-item product IDs (multi-select). Any matching cart item is free up to freeItemQuantity per line. freeItemQuantity: type: number description: Per-line cap for free items (defaults to 1) freeItemId: type: number description: DEPRECATED — use freeItemIds. Retained for legacy vouchers. targetItemIds: type: array items: type: number description: "For fixed_price action: items repriced down to fixedPriceCents." fixedPriceCents: type: number description: "For fixed_price action: target per-unit base price in cents." formula: type: object properties: type: type: string enum: - buy_x_get_y - tiered - spend_threshold - bundle - combo_groups rules: type: object description: "Formula-specific rules. For combo_groups: { groups: [{ quantity, itemIds?, tagIds?, variantIds? }], bundlePriceCents }." required: - type maxUses: type: number description: Total usage limit perUserUses: type: number description: Per-user usage limit minOrderAmountCents: type: number description: Minimum order amount in cents maxDiscountAmountCents: type: number description: Maximum discount cap in cents initialBalanceCents: type: number description: Initial balance for gift cards canCombine: type: boolean default: false autoApply: type: boolean default: false validFrom: type: string format: date-time validUntil: type: string format: date-time displayTitle: type: string description: Guest-facing title displayDescription: type: string description: Guest-facing description displayImageUrl: type: string description: Gift card image URL alwaysVisible: type: boolean default: false description: Show promotion even when requirements not met isTemplate: type: boolean default: false description: Whether this is a template voucher templateVoucherId: type: number description: Parent template voucher ID restrictions: type: array items: type: object properties: restrictionType: type: string enum: - INCLUDE_ITEM - EXCLUDE_ITEM - INCLUDE_TAG - EXCLUDE_TAG - INCLUDE_LAYOUT - EXCLUDE_LAYOUT - INCLUDE_VARIANT - EXCLUDE_VARIANT - REQUIRE_ITEM - REQUIRE_ITEM_WITH_VARIANTS - REQUIRE_TAG - MIN_ITEM_COUNT entityId: type: number description: Item/tag/layout ID (0 for MIN_ITEM_COUNT) quantity: type: number description: Required quantity for REQUIRE_ITEM / REQUIRE_ITEM_WITH_VARIANTS / MIN_ITEM_COUNT variantIds: type: array items: type: number description: "For REQUIRE_ITEM_WITH_VARIANTS: variant ids that must ALL be selected on the same cart line as the item." required: - restrictionType - entityId userRestrictions: type: array items: type: object properties: restrictionType: type: string enum: - EMAIL - PHONE - USER_ID - SEGMENT_ID value: type: string description: Email/phone/user_id/segment_id required: - restrictionType - value required: true responses: "201": description: Voucher created successfully content: application/json: schema: description: Voucher created successfully type: object properties: status: type: string enum: - success data: type: object properties: id: type: number locationId: type: number nullable: true companyId: type: number nullable: true name: type: string code: type: string enabled: type: boolean voucherType: type: string enum: - DISCOUNT_CODE - GIFT_CARD - PROMOTION - LOYALTY_REWARD - CAMPAIGN - REFERRAL balanceMode: type: string enum: - NONE - DECREMENTAL typeSpecification: type: object properties: type: type: string enum: - percentage - fixed - balance - free_item - fixed_price - formula amountInBasisPoints: type: number description: For percentage discounts (10000 = 100%) amountInCents: type: number description: For fixed amount discounts freeItemIds: type: array items: type: number description: Free-item product IDs (multi-select). Any matching cart item is free up to freeItemQuantity per line. freeItemQuantity: type: number description: Per-line cap for free items (defaults to 1) freeItemId: type: number description: DEPRECATED — use freeItemIds. Retained for legacy vouchers. targetItemIds: type: array items: type: number description: "For fixed_price action: items repriced down to fixedPriceCents." fixedPriceCents: type: number description: "For fixed_price action: target per-unit base price in cents." formula: type: object properties: type: type: string enum: - buy_x_get_y - tiered - spend_threshold - bundle - combo_groups rules: type: object description: "Formula-specific rules. For combo_groups: { groups: [{ quantity, itemIds?, tagIds?, variantIds? }], bundlePriceCents }." required: - type maxUses: type: number nullable: true timesUsed: type: number perUserUses: type: number nullable: true minOrderAmountCents: type: number nullable: true maxDiscountAmountCents: type: number nullable: true initialBalanceCents: type: number nullable: true remainingBalanceCents: type: number nullable: true canCombine: type: boolean autoApply: type: boolean validFrom: type: string format: date-time validUntil: type: string format: date-time nullable: true displayTitle: type: string nullable: true displayDescription: type: string nullable: true displayImageUrl: type: string nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time restrictions: type: array items: type: object properties: id: type: number discountId: type: number restrictionType: type: string enum: - INCLUDE_ITEM - EXCLUDE_ITEM - INCLUDE_TAG - EXCLUDE_TAG - INCLUDE_LAYOUT - EXCLUDE_LAYOUT - INCLUDE_VARIANT - EXCLUDE_VARIANT - REQUIRE_ITEM - REQUIRE_ITEM_WITH_VARIANTS - REQUIRE_TAG - MIN_ITEM_COUNT entityId: type: number quantity: type: number nullable: true variantIds: type: array items: type: number nullable: true description: Required variant ids on the same line for REQUIRE_ITEM_WITH_VARIANTS rows. createdAt: type: string format: date-time userRestrictions: type: array items: type: object properties: id: type: number discountId: type: number restrictionType: type: string enum: - EMAIL - PHONE - USER_ID - SEGMENT_ID value: type: string createdAt: type: string format: date-time meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "400": description: Bad Request - Invalid input content: application/json: schema: description: Bad Request - Invalid input type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: description: Unauthorized - Missing or invalid API key type: object "403": description: Forbidden - Insufficient permissions content: application/json: schema: description: Forbidden - Insufficient permissions type: object "404": description: Not Found - Resource not found content: application/json: schema: description: Not Found - Resource not found type: object "409": description: Conflict - Duplicate voucher code content: application/json: schema: description: Conflict - Duplicate voucher code type: object "500": description: Internal Server Error content: application/json: schema: description: Internal Server Error type: object /api/v1/vouchers/{id}: get: summary: Get voucher tags: - Vouchers description: >- Get single voucher with full details including restrictions and usage statistics **Permissions:** 🔵 `vouchers.read` parameters: - schema: type: string in: path name: id required: true description: Voucher ID responses: "200": description: Voucher details content: application/json: schema: description: Voucher details type: object properties: status: type: string enum: - success data: type: object properties: id: type: number locationId: type: number nullable: true companyId: type: number nullable: true name: type: string code: type: string enabled: type: boolean voucherType: type: string enum: - DISCOUNT_CODE - GIFT_CARD - PROMOTION - LOYALTY_REWARD - CAMPAIGN - REFERRAL balanceMode: type: string enum: - NONE - DECREMENTAL typeSpecification: type: object properties: type: type: string enum: - percentage - fixed - balance - free_item - fixed_price - formula amountInBasisPoints: type: number description: For percentage discounts (10000 = 100%) amountInCents: type: number description: For fixed amount discounts freeItemIds: type: array items: type: number description: Free-item product IDs (multi-select). Any matching cart item is free up to freeItemQuantity per line. freeItemQuantity: type: number description: Per-line cap for free items (defaults to 1) freeItemId: type: number description: DEPRECATED — use freeItemIds. Retained for legacy vouchers. targetItemIds: type: array items: type: number description: "For fixed_price action: items repriced down to fixedPriceCents." fixedPriceCents: type: number description: "For fixed_price action: target per-unit base price in cents." formula: type: object properties: type: type: string enum: - buy_x_get_y - tiered - spend_threshold - bundle - combo_groups rules: type: object description: "Formula-specific rules. For combo_groups: { groups: [{ quantity, itemIds?, tagIds?, variantIds? }], bundlePriceCents }." required: - type maxUses: type: number nullable: true timesUsed: type: number perUserUses: type: number nullable: true minOrderAmountCents: type: number nullable: true maxDiscountAmountCents: type: number nullable: true initialBalanceCents: type: number nullable: true remainingBalanceCents: type: number nullable: true canCombine: type: boolean autoApply: type: boolean validFrom: type: string format: date-time validUntil: type: string format: date-time nullable: true displayTitle: type: string nullable: true displayDescription: type: string nullable: true displayImageUrl: type: string nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time restrictions: type: array items: type: object properties: id: type: number discountId: type: number restrictionType: type: string enum: - INCLUDE_ITEM - EXCLUDE_ITEM - INCLUDE_TAG - EXCLUDE_TAG - INCLUDE_LAYOUT - EXCLUDE_LAYOUT - INCLUDE_VARIANT - EXCLUDE_VARIANT - REQUIRE_ITEM - REQUIRE_ITEM_WITH_VARIANTS - REQUIRE_TAG - MIN_ITEM_COUNT entityId: type: number quantity: type: number nullable: true variantIds: type: array items: type: number nullable: true description: Required variant ids on the same line for REQUIRE_ITEM_WITH_VARIANTS rows. createdAt: type: string format: date-time userRestrictions: type: array items: type: object properties: id: type: number discountId: type: number restrictionType: type: string enum: - EMAIL - PHONE - USER_ID - SEGMENT_ID value: type: string createdAt: type: string format: date-time usageStats: type: object properties: totalUses: type: number uniqueUsers: type: number totalDiscountedCents: type: number averageDiscountCents: type: number meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "400": description: Bad Request - Invalid input content: application/json: schema: description: Bad Request - Invalid input type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: description: Unauthorized - Missing or invalid API key type: object "403": description: Forbidden - Insufficient permissions content: application/json: schema: description: Forbidden - Insufficient permissions type: object "404": description: Not Found - Resource not found content: application/json: schema: description: Not Found - Resource not found type: object "500": description: Internal Server Error content: application/json: schema: description: Internal Server Error type: object put: summary: Update voucher tags: - Vouchers description: |- Update an existing voucher **Permissions:** 🟠 `vouchers.update` requestBody: content: application/json: schema: type: object properties: name: type: string code: type: string enabled: type: boolean voucherType: type: string enum: - DISCOUNT_CODE - GIFT_CARD - PROMOTION - LOYALTY_REWARD - CAMPAIGN - REFERRAL typeSpecification: type: object properties: type: type: string enum: - percentage - fixed - balance - free_item - fixed_price - formula amountInBasisPoints: type: number description: For percentage discounts (10000 = 100%) amountInCents: type: number description: For fixed amount discounts freeItemIds: type: array items: type: number description: Free-item product IDs (multi-select). Any matching cart item is free up to freeItemQuantity per line. freeItemQuantity: type: number description: Per-line cap for free items (defaults to 1) freeItemId: type: number description: DEPRECATED — use freeItemIds. Retained for legacy vouchers. targetItemIds: type: array items: type: number description: "For fixed_price action: items repriced down to fixedPriceCents." fixedPriceCents: type: number description: "For fixed_price action: target per-unit base price in cents." formula: type: object properties: type: type: string enum: - buy_x_get_y - tiered - spend_threshold - bundle - combo_groups rules: type: object description: "Formula-specific rules. For combo_groups: { groups: [{ quantity, itemIds?, tagIds?, variantIds? }], bundlePriceCents }." required: - type maxUses: type: number perUserUses: type: number minOrderAmountCents: type: number maxDiscountAmountCents: type: number canCombine: type: boolean autoApply: type: boolean displayTitle: type: string displayDescription: type: string displayImageUrl: type: string alwaysVisible: type: boolean isTemplate: type: boolean templateVoucherId: type: number initialBalanceCents: type: number remainingBalanceCents: type: number balanceMode: type: string enum: - NONE - DECREMENTAL validFrom: type: string validUntil: type: string restrictions: type: array items: type: object properties: restrictionType: type: string enum: - INCLUDE_ITEM - EXCLUDE_ITEM - INCLUDE_TAG - EXCLUDE_TAG - INCLUDE_LAYOUT - EXCLUDE_LAYOUT - INCLUDE_VARIANT - EXCLUDE_VARIANT - REQUIRE_ITEM - REQUIRE_ITEM_WITH_VARIANTS - REQUIRE_TAG - MIN_ITEM_COUNT entityId: type: number quantity: type: number description: Required quantity for REQUIRE_ITEM / REQUIRE_ITEM_WITH_VARIANTS / MIN_ITEM_COUNT variantIds: type: array items: type: number description: "For REQUIRE_ITEM_WITH_VARIANTS: variant ids that must ALL be selected on the same cart line." userRestrictions: type: array items: type: object properties: restrictionType: type: string enum: - EMAIL - PHONE - USER_ID - SEGMENT_ID value: type: string parameters: - schema: type: string in: path name: id required: true description: Voucher ID responses: "200": description: Voucher updated successfully content: application/json: schema: description: Voucher updated successfully type: object properties: status: type: string enum: - success data: type: object properties: id: type: number locationId: type: number nullable: true companyId: type: number nullable: true name: type: string code: type: string enabled: type: boolean voucherType: type: string enum: - DISCOUNT_CODE - GIFT_CARD - PROMOTION - LOYALTY_REWARD - CAMPAIGN - REFERRAL balanceMode: type: string enum: - NONE - DECREMENTAL typeSpecification: type: object properties: type: type: string enum: - percentage - fixed - balance - free_item - fixed_price - formula amountInBasisPoints: type: number description: For percentage discounts (10000 = 100%) amountInCents: type: number description: For fixed amount discounts freeItemIds: type: array items: type: number description: Free-item product IDs (multi-select). Any matching cart item is free up to freeItemQuantity per line. freeItemQuantity: type: number description: Per-line cap for free items (defaults to 1) freeItemId: type: number description: DEPRECATED — use freeItemIds. Retained for legacy vouchers. targetItemIds: type: array items: type: number description: "For fixed_price action: items repriced down to fixedPriceCents." fixedPriceCents: type: number description: "For fixed_price action: target per-unit base price in cents." formula: type: object properties: type: type: string enum: - buy_x_get_y - tiered - spend_threshold - bundle - combo_groups rules: type: object description: "Formula-specific rules. For combo_groups: { groups: [{ quantity, itemIds?, tagIds?, variantIds? }], bundlePriceCents }." required: - type maxUses: type: number nullable: true timesUsed: type: number perUserUses: type: number nullable: true minOrderAmountCents: type: number nullable: true maxDiscountAmountCents: type: number nullable: true initialBalanceCents: type: number nullable: true remainingBalanceCents: type: number nullable: true canCombine: type: boolean autoApply: type: boolean validFrom: type: string format: date-time validUntil: type: string format: date-time nullable: true displayTitle: type: string nullable: true displayDescription: type: string nullable: true displayImageUrl: type: string nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time restrictions: type: array items: type: object properties: id: type: number discountId: type: number restrictionType: type: string enum: - INCLUDE_ITEM - EXCLUDE_ITEM - INCLUDE_TAG - EXCLUDE_TAG - INCLUDE_LAYOUT - EXCLUDE_LAYOUT - INCLUDE_VARIANT - EXCLUDE_VARIANT - REQUIRE_ITEM - REQUIRE_ITEM_WITH_VARIANTS - REQUIRE_TAG - MIN_ITEM_COUNT entityId: type: number quantity: type: number nullable: true variantIds: type: array items: type: number nullable: true description: Required variant ids on the same line for REQUIRE_ITEM_WITH_VARIANTS rows. createdAt: type: string format: date-time userRestrictions: type: array items: type: object properties: id: type: number discountId: type: number restrictionType: type: string enum: - EMAIL - PHONE - USER_ID - SEGMENT_ID value: type: string createdAt: type: string format: date-time meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "400": description: Bad Request - Invalid input content: application/json: schema: description: Bad Request - Invalid input type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: description: Unauthorized - Missing or invalid API key type: object "403": description: Forbidden - Insufficient permissions content: application/json: schema: description: Forbidden - Insufficient permissions type: object "404": description: Not Found - Resource not found content: application/json: schema: description: Not Found - Resource not found type: object "500": description: Internal Server Error content: application/json: schema: description: Internal Server Error type: object delete: summary: Delete voucher tags: - Vouchers description: |- Soft delete (disable) a voucher **Permissions:** 🔴 `vouchers.delete` parameters: - schema: type: string in: path name: id required: true description: Voucher ID responses: "200": description: Voucher deleted successfully content: application/json: schema: description: Voucher deleted successfully type: object properties: status: type: string enum: - success data: type: object properties: message: type: string id: type: number meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "400": description: Bad Request - Invalid input content: application/json: schema: description: Bad Request - Invalid input type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: description: Unauthorized - Missing or invalid API key type: object "403": description: Forbidden - Insufficient permissions content: application/json: schema: description: Forbidden - Insufficient permissions type: object "404": description: Not Found - Resource not found content: application/json: schema: description: Not Found - Resource not found type: object "500": description: Internal Server Error content: application/json: schema: description: Internal Server Error type: object /api/v1/vouchers/{id}/send-email: post: summary: Send voucher email tags: - Vouchers description: |- Send voucher code and QR code via email to a recipient **Permissions:** 🟠 `vouchers.update` requestBody: content: application/json: schema: type: object required: - email properties: email: type: string format: email description: Recipient email address personal_message: type: string description: Optional personal message (for gift cards) required: true parameters: - schema: type: string in: path name: id required: true description: Voucher ID responses: "200": description: Email sent successfully content: application/json: schema: description: Email sent successfully type: object properties: status: type: string enum: - success data: type: object properties: success: type: boolean meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "400": description: Bad Request - Invalid input content: application/json: schema: description: Bad Request - Invalid input type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: description: Unauthorized - Missing or invalid API key type: object "403": description: Forbidden - Insufficient permissions content: application/json: schema: description: Forbidden - Insufficient permissions type: object "404": description: Not Found - Resource not found content: application/json: schema: description: Not Found - Resource not found type: object "500": description: Internal Server Error content: application/json: schema: description: Internal Server Error type: object /api/v1/vouchers/applied/{id}: delete: summary: Remove applied voucher tags: - Vouchers description: Remove an uncommitted applied voucher from a tab parameters: - schema: type: string in: path name: id required: true description: Applied voucher (tab_voucher) ID responses: "200": description: Voucher removed successfully content: application/json: schema: description: Voucher removed successfully type: object properties: status: type: string enum: - success data: type: object properties: message: type: string id: type: string meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "400": description: Bad Request - Invalid input content: application/json: schema: description: Bad Request - Invalid input type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: description: Unauthorized - Missing or invalid API key type: object "403": description: Forbidden - Insufficient permissions content: application/json: schema: description: Forbidden - Insufficient permissions type: object "404": description: Not Found - Resource not found content: application/json: schema: description: Not Found - Resource not found type: object "500": description: Internal Server Error content: application/json: schema: description: Internal Server Error type: object /api/v1/vouchers/apply: post: summary: Apply voucher tags: - Vouchers description: Apply a validated voucher to a tab requestBody: content: application/json: schema: type: object required: - codes - locationId properties: codes: type: array items: type: string description: Voucher codes to apply locationId: type: number description: Location ID tabId: type: string description: Tab UUID kitchenDispatchId: type: string description: Kitchen dispatch UUID items: type: array items: type: object properties: inventoryItemId: type: number quantity: type: number priceCents: type: number variantIds: type: array items: type: number tagIds: type: array items: type: number description: Items to validate against userId: type: number description: User ID for tracking email: type: string description: Email for tracking phone: type: string description: Phone for tracking required: true responses: "200": description: Voucher applied successfully content: application/json: schema: description: Voucher applied successfully type: object properties: status: type: string enum: - success data: type: object properties: applied: type: array items: type: object properties: code: type: string success: type: boolean reservationId: type: string tabVoucherId: type: number description: tab_vouchers.id (only present for tab-scoped applies; pair with DELETE /vouchers/applied/:id to remove) voucherId: type: number discountAmountCents: type: number failed: type: array items: type: object properties: code: type: string success: type: boolean error: type: string message: type: string summary: type: object properties: totalRequested: type: number successCount: type: number failureCount: type: number meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "400": description: Bad Request - Invalid input content: application/json: schema: description: Bad Request - Invalid input type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: description: Unauthorized - Missing or invalid API key type: object "403": description: Forbidden - Insufficient permissions content: application/json: schema: description: Forbidden - Insufficient permissions type: object "404": description: Not Found - Resource not found content: application/json: schema: description: Not Found - Resource not found type: object "500": description: Internal Server Error content: application/json: schema: description: Internal Server Error type: object "501": description: Not Implemented - Feature under development content: application/json: schema: description: Not Implemented - Feature under development type: object /api/v1/vouchers/consume: post: summary: Consume vouchers tags: - Vouchers description: Consume (commit) previously reserved voucher reservations requestBody: content: application/json: schema: type: object properties: reservationIds: type: array items: type: string description: Reservation IDs to consume tabId: type: string description: Tab UUID responses: "200": description: Vouchers consumed successfully content: application/json: schema: description: Vouchers consumed successfully type: object properties: status: type: string enum: - success data: type: object additionalProperties: true meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "400": description: Bad Request - Invalid input content: application/json: schema: description: Bad Request - Invalid input type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: description: Unauthorized - Missing or invalid API key type: object "403": description: Forbidden - Insufficient permissions content: application/json: schema: description: Forbidden - Insufficient permissions type: object "404": description: Not Found - Resource not found content: application/json: schema: description: Not Found - Resource not found type: object "500": description: Internal Server Error content: application/json: schema: description: Internal Server Error type: object /api/v1/vouchers/eligible: post: summary: Get eligible vouchers tags: - Vouchers description: >- Get vouchers eligible for a location/tab. Returns promotions and user-restricted vouchers. **Permissions:** 🔵 `vouchers.read` requestBody: content: application/json: schema: type: object required: - locationId properties: locationId: type: number description: Location ID (required) tabId: type: string description: Tab UUID - will fetch user IDs from tab members userIds: type: array items: type: number description: Direct user IDs to check for user-restricted vouchers items: type: array description: Cart items. When provided, vouchers are filtered against item/tag/variant/layout restrictions, required items, and minimum order amount — only vouchers that would pass at reservation time are returned. items: type: object required: - item_id - quantity - price_cents properties: item_id: type: number description: Inventory item ID quantity: type: number description: Quantity price_cents: type: number description: Total price per unit in cents (including modifiers/variants) base_price_cents: type: number description: Base price per unit in cents (excluding modifiers/variants). Used for bundle deals. tags: type: array items: type: number description: Tag IDs variant_ids: type: array items: type: number description: Variant IDs applied to this line (for variant-based restrictions) layout_id: type: number description: Layout ID this item was added from totalAmountCents: type: number description: Total order amount in cents. Used for min order validation when items array is empty (e.g. tab-level checks). layoutId: type: string description: Current browsing layout UUID. Used for INCLUDE_LAYOUT/EXCLUDE_LAYOUT restriction filtering at SQL level. required: true responses: "200": description: List of eligible vouchers content: application/json: schema: description: List of eligible vouchers type: object properties: status: type: string enum: - success data: type: object properties: vouchers: type: array items: type: object properties: id: type: number code: type: string name: type: string voucherType: type: string enum: - DISCOUNT_CODE - GIFT_CARD - PROMOTION - LOYALTY_REWARD - CAMPAIGN - REFERRAL isPromotion: type: boolean description: True if voucher_type = PROMOTION isUserVoucher: type: boolean description: True if voucher has USER_ID restriction matching provided users isLoyaltyRestricted: type: boolean description: True if voucher has a discount_loyalty_restrictions row (tier or enrollment required) alwaysVisible: type: boolean description: Show even when requirements not met autoApply: type: boolean description: Apply automatically when conditions are met (vs. requiring manual selection) typeSpecification: type: object properties: type: type: string enum: - percentage - fixed - balance - free_item - fixed_price - formula amountInBasisPoints: type: number description: For percentage discounts (10000 = 100%) amountInCents: type: number description: For fixed amount discounts freeItemIds: type: array items: type: number description: Free-item product IDs (multi-select). Any matching cart item is free up to freeItemQuantity per line. freeItemQuantity: type: number description: Per-line cap for free items (defaults to 1) freeItemId: type: number description: DEPRECATED — use freeItemIds. Retained for legacy vouchers. targetItemIds: type: array items: type: number description: "For fixed_price action: items repriced down to fixedPriceCents." fixedPriceCents: type: number description: "For fixed_price action: target per-unit base price in cents." formula: type: object properties: type: type: string enum: - buy_x_get_y - tiered - spend_threshold - bundle - combo_groups rules: type: object description: "Formula-specific rules. For combo_groups: { groups: [{ quantity, itemIds?, tagIds?, variantIds? }], bundlePriceCents }." required: - type nullable: true displayTitle: type: string nullable: true displayDescription: type: string nullable: true displayImageUrl: type: string nullable: true maxDiscountAmountCents: type: number nullable: true remainingBalanceCents: type: number nullable: true maxUses: type: number nullable: true timesUsed: type: number hasUsesLeft: type: boolean description: True if maxUses is null OR timesUsed < maxUses restrictions: type: array items: type: object properties: type: type: string enum: - INCLUDE_ITEM - EXCLUDE_ITEM - INCLUDE_TAG - EXCLUDE_TAG - INCLUDE_LAYOUT - EXCLUDE_LAYOUT - INCLUDE_VARIANT - EXCLUDE_VARIANT - REQUIRE_ITEM - REQUIRE_ITEM_WITH_VARIANTS - REQUIRE_TAG - MIN_ITEM_COUNT description: Restriction kind. INCLUDE/EXCLUDE_ITEM gates which items receive the discount; REQUIRE_ITEM/REQUIRE_TAG gates whether the voucher applies at all; INCLUDE/EXCLUDE_LAYOUT scopes by POS layout. entityId: type: string description: Numeric id (as string) for ITEM/TAG types, UUID for LAYOUT types. quantity: type: number nullable: true description: Required quantity for REQUIRE_ITEM / REQUIRE_TAG. Null for INCLUDE/EXCLUDE rules. description: Item/tag/layout restrictions for this voucher. Frontend resolves entity ids → titles via the inventory cache to surface "what to buy to unlock this promo" without a follow-up call. meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "400": description: Bad Request - Invalid input content: application/json: schema: description: Bad Request - Invalid input type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: description: Unauthorized - Missing or invalid API key type: object "403": description: Forbidden - Insufficient permissions content: application/json: schema: description: Forbidden - Insufficient permissions type: object "404": description: Not Found - Resource not found content: application/json: schema: description: Not Found - Resource not found type: object "500": description: Internal Server Error content: application/json: schema: description: Internal Server Error type: object /api/v1/vouchers/release: post: summary: Release vouchers tags: - Vouchers description: Release (cancel) previously reserved voucher reservations requestBody: content: application/json: schema: type: object properties: reservationIds: type: array items: type: string description: Reservation IDs to release tabId: type: string description: Tab UUID responses: "200": description: Vouchers released successfully content: application/json: schema: description: Vouchers released successfully type: object properties: status: type: string enum: - success data: type: object additionalProperties: true meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "400": description: Bad Request - Invalid input content: application/json: schema: description: Bad Request - Invalid input type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: description: Unauthorized - Missing or invalid API key type: object "403": description: Forbidden - Insufficient permissions content: application/json: schema: description: Forbidden - Insufficient permissions type: object "404": description: Not Found - Resource not found content: application/json: schema: description: Not Found - Resource not found type: object "500": description: Internal Server Error content: application/json: schema: description: Internal Server Error type: object /api/v1/vouchers/reservations: get: summary: Get voucher reservations tags: - Vouchers description: Get active voucher reservations for a tab or kitchen dispatch parameters: - schema: type: string in: query name: tabId required: false description: Tab UUID - schema: type: string in: query name: kitchenDispatchId required: false description: Kitchen dispatch UUID responses: "200": description: List of reservations content: application/json: schema: description: List of reservations type: object properties: status: type: string enum: - success data: type: object properties: reservations: type: array items: type: object additionalProperties: true meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "400": description: Bad Request - Invalid input content: application/json: schema: description: Bad Request - Invalid input type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: description: Unauthorized - Missing or invalid API key type: object "403": description: Forbidden - Insufficient permissions content: application/json: schema: description: Forbidden - Insufficient permissions type: object "404": description: Not Found - Resource not found content: application/json: schema: description: Not Found - Resource not found type: object "500": description: Internal Server Error content: application/json: schema: description: Internal Server Error type: object /api/v1/vouchers/search: get: summary: Search vouchers tags: - Vouchers description: Search vouchers by code or name for POS lookup parameters: - schema: type: string in: query name: q required: true description: Search query (code or name) - schema: type: number in: query name: location_id required: false description: Filter by location ID - schema: type: number default: 10 minimum: 1 maximum: 50 in: query name: limit required: false description: Max results to return responses: "200": description: Matching vouchers content: application/json: schema: description: Matching vouchers type: object properties: status: type: string enum: - success data: type: object properties: vouchers: type: array items: type: object properties: id: type: number locationId: type: number nullable: true companyId: type: number nullable: true name: type: string code: type: string enabled: type: boolean voucherType: type: string enum: - DISCOUNT_CODE - GIFT_CARD - PROMOTION - LOYALTY_REWARD - CAMPAIGN - REFERRAL balanceMode: type: string enum: - NONE - DECREMENTAL typeSpecification: type: object properties: type: type: string enum: - percentage - fixed - balance - free_item - fixed_price - formula amountInBasisPoints: type: number description: For percentage discounts (10000 = 100%) amountInCents: type: number description: For fixed amount discounts freeItemIds: type: array items: type: number description: Free-item product IDs (multi-select). Any matching cart item is free up to freeItemQuantity per line. freeItemQuantity: type: number description: Per-line cap for free items (defaults to 1) freeItemId: type: number description: DEPRECATED — use freeItemIds. Retained for legacy vouchers. targetItemIds: type: array items: type: number description: "For fixed_price action: items repriced down to fixedPriceCents." fixedPriceCents: type: number description: "For fixed_price action: target per-unit base price in cents." formula: type: object properties: type: type: string enum: - buy_x_get_y - tiered - spend_threshold - bundle - combo_groups rules: type: object description: "Formula-specific rules. For combo_groups: { groups: [{ quantity, itemIds?, tagIds?, variantIds? }], bundlePriceCents }." required: - type maxUses: type: number nullable: true timesUsed: type: number perUserUses: type: number nullable: true minOrderAmountCents: type: number nullable: true maxDiscountAmountCents: type: number nullable: true initialBalanceCents: type: number nullable: true remainingBalanceCents: type: number nullable: true canCombine: type: boolean autoApply: type: boolean validFrom: type: string format: date-time validUntil: type: string format: date-time nullable: true displayTitle: type: string nullable: true displayDescription: type: string nullable: true displayImageUrl: type: string nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "400": description: Bad Request - Invalid input content: application/json: schema: description: Bad Request - Invalid input type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: description: Unauthorized - Missing or invalid API key type: object "403": description: Forbidden - Insufficient permissions content: application/json: schema: description: Forbidden - Insufficient permissions type: object "404": description: Not Found - Resource not found content: application/json: schema: description: Not Found - Resource not found type: object "500": description: Internal Server Error content: application/json: schema: description: Internal Server Error type: object /api/v1/vouchers/validate: post: summary: Validate voucher(s) tags: - Vouchers description: Validate one or more voucher codes against a tab or specific kitchen dispatch items. requestBody: content: application/json: schema: type: object required: - codes - locationId properties: codes: type: array description: Array of voucher codes to validate items: type: string locationId: type: number description: Location ID includePromotions: type: boolean description: Include auto-apply promotions for this location context: type: object description: Validation context properties: tabId: type: string description: Tab UUID kitchenDispatchItems: type: array description: Kitchen dispatch item UUIDs for split payments items: type: string totalAmountCents: type: number description: Total amount in cents for discount calculation items: type: array description: Uncommitted items to validate against items: type: object required: - inventoryItemId - quantity - priceCents properties: inventoryItemId: type: number description: Inventory item ID quantity: type: number description: Item quantity priceCents: type: number description: Item price in cents variantIds: type: array items: type: number description: Variant IDs tagIds: type: array items: type: number description: Tag IDs required: true responses: "200": description: Validation results for all voucher codes content: application/json: schema: description: Validation results for all voucher codes type: object properties: status: type: string enum: - success data: type: object properties: validations: type: array description: Validation results for each voucher code (in order) items: type: object properties: code: type: string description: The voucher code valid: type: boolean description: Whether this voucher is valid error: type: string nullable: true description: Error code if invalid (NOT_FOUND, INTERNAL_ERROR, etc.) message: type: string nullable: true description: Human-readable error/status message voucher: type: object properties: id: type: number locationId: type: number nullable: true companyId: type: number nullable: true name: type: string code: type: string enabled: type: boolean voucherType: type: string enum: - DISCOUNT_CODE - GIFT_CARD - PROMOTION - LOYALTY_REWARD - CAMPAIGN - REFERRAL balanceMode: type: string enum: - NONE - DECREMENTAL typeSpecification: type: object properties: type: type: string enum: - percentage - fixed - balance - free_item - fixed_price - formula amountInBasisPoints: type: number description: For percentage discounts (10000 = 100%) amountInCents: type: number description: For fixed amount discounts freeItemIds: type: array items: type: number description: Free-item product IDs (multi-select). Any matching cart item is free up to freeItemQuantity per line. freeItemQuantity: type: number description: Per-line cap for free items (defaults to 1) freeItemId: type: number description: DEPRECATED — use freeItemIds. Retained for legacy vouchers. targetItemIds: type: array items: type: number description: "For fixed_price action: items repriced down to fixedPriceCents." fixedPriceCents: type: number description: "For fixed_price action: target per-unit base price in cents." formula: type: object properties: type: type: string enum: - buy_x_get_y - tiered - spend_threshold - bundle - combo_groups rules: type: object description: "Formula-specific rules. For combo_groups: { groups: [{ quantity, itemIds?, tagIds?, variantIds? }], bundlePriceCents }." required: - type maxUses: type: number nullable: true timesUsed: type: number perUserUses: type: number nullable: true minOrderAmountCents: type: number nullable: true maxDiscountAmountCents: type: number nullable: true initialBalanceCents: type: number nullable: true remainingBalanceCents: type: number nullable: true canCombine: type: boolean autoApply: type: boolean validFrom: type: string format: date-time validUntil: type: string format: date-time nullable: true displayTitle: type: string nullable: true displayDescription: type: string nullable: true displayImageUrl: type: string nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time nullable: true description: Voucher details (if found) discount: type: object nullable: true description: Discount calculation details properties: estimatedDiscountCents: type: number description: Estimated discount in cents discountType: type: string description: Type of discount (percentage, fixed, free_item, etc.) newTotalCents: type: number nullable: true description: New running total after this voucher (for sequential validation) orderIndex: type: number description: Index position in the validation order (0-indexed) meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "400": description: Bad Request - Invalid input content: application/json: schema: description: Bad Request - Invalid input type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: description: Unauthorized - Missing or invalid API key type: object "403": description: Forbidden - Insufficient permissions content: application/json: schema: description: Forbidden - Insufficient permissions type: object "404": description: Not Found - Resource not found content: application/json: schema: description: Not Found - Resource not found type: object "500": description: Internal Server Error content: application/json: schema: description: Internal Server Error type: object /api/v1/webhooks/logs: get: summary: List webhook logs tags: - Webhooks description: List webhook delivery logs with optional filtering parameters: - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: number minimum: 1 maximum: 100 default: 20 in: query name: limit required: false description: Items per page - schema: type: string in: query name: subscriptionId required: false description: Filter by subscription ID - schema: type: string in: query name: event required: false description: Filter by event type - schema: type: string enum: - pending - success - failed - retrying in: query name: status required: false description: Filter by delivery status - schema: type: string in: query name: resourceId required: false description: Filter by resource ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: logs: type: array items: type: object properties: id: type: string description: Unique log ID subscriptionId: type: string description: Subscription ID event: type: string description: Event type that triggered webhook resourceId: type: string description: ID of the resource that changed status: type: string enum: - pending - success - failed - retrying description: Delivery status attempts: type: number description: Number of delivery attempts responseCode: type: number nullable: true description: HTTP response code from webhook endpoint errorMessage: type: string nullable: true description: Error message if delivery failed deliveredAt: type: string format: date-time nullable: true description: Successful delivery timestamp createdAt: type: string format: date-time description: Creation timestamp required: - id - subscriptionId - event - resourceId - status - attempts - createdAt pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages required: - logs - pagination meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/webhooks/subscriptions: get: summary: List webhook subscriptions tags: - Webhooks description: |- List webhook subscriptions with optional filtering **Permissions:** 🔵 `webhooks.read` parameters: - schema: type: number minimum: 1 default: 1 in: query name: page required: false description: Page number - schema: type: number minimum: 1 maximum: 100 default: 20 in: query name: limit required: false description: Items per page - schema: type: boolean in: query name: active required: false description: Filter by active status - schema: type: string in: query name: event required: false description: Filter by event type responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: subscriptions: type: array items: type: object properties: id: type: string description: Unique subscription ID url: type: string format: uri description: Webhook URL endpoint events: type: array items: type: string description: List of event types to subscribe to (e.g., "inventory.created", "order.completed") secret: type: string description: Webhook secret for signature verification active: type: boolean description: Whether subscription is active createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - id - url - events - active - createdAt - updatedAt pagination: type: object properties: page: type: number minimum: 1 limit: type: number minimum: 1 maximum: 100 total: type: number minimum: 0 totalPages: type: number minimum: 0 required: - page - limit - total - totalPages required: - subscriptions - pagination meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 post: summary: Create webhook subscription tags: - Webhooks description: |- Create a new webhook subscription **Permissions:** 🟢 `webhooks.create` requestBody: content: application/json: schema: type: object properties: url: type: string format: uri pattern: ^https:// description: Webhook URL (must be HTTPS) events: type: array items: type: string minItems: 1 description: List of event types to subscribe to secret: type: string minLength: 16 description: Webhook secret for signature verification (min 16 characters) active: type: boolean default: true description: Whether subscription is active required: - url - events - secret required: true responses: "201": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string description: Unique subscription ID url: type: string format: uri description: Webhook URL endpoint events: type: array items: type: string description: List of event types to subscribe to (e.g., "inventory.created", "order.completed") secret: type: string description: Webhook secret for signature verification active: type: boolean description: Whether subscription is active createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - id - url - events - active - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/webhooks/subscriptions/{id}: get: summary: Get webhook subscription tags: - Webhooks description: |- Get a single webhook subscription by ID **Permissions:** 🔵 `webhooks.read` parameters: - schema: type: string in: path name: id required: true description: Webhook subscription ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string description: Unique subscription ID url: type: string format: uri description: Webhook URL endpoint events: type: array items: type: string description: List of event types to subscribe to (e.g., "inventory.created", "order.completed") secret: type: string description: Webhook secret for signature verification active: type: boolean description: Whether subscription is active createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - id - url - events - active - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 put: summary: Update webhook subscription tags: - Webhooks description: |- Update an existing webhook subscription **Permissions:** 🟠 `webhooks.update` requestBody: content: application/json: schema: type: object properties: url: type: string format: uri pattern: ^https:// events: type: array items: type: string minItems: 1 secret: type: string minLength: 16 active: type: boolean parameters: - schema: type: string in: path name: id required: true description: Webhook subscription ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: id: type: string description: Unique subscription ID url: type: string format: uri description: Webhook URL endpoint events: type: array items: type: string description: List of event types to subscribe to (e.g., "inventory.created", "order.completed") secret: type: string description: Webhook secret for signature verification active: type: boolean description: Whether subscription is active createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - id - url - events - active - createdAt - updatedAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 delete: summary: Delete webhook subscription tags: - Webhooks description: |- Delete a webhook subscription **Permissions:** 🔴 `webhooks.delete` parameters: - schema: type: string in: path name: id required: true description: Webhook subscription ID responses: "200": description: Subscription successfully deleted content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: deleted: type: boolean meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 /api/v1/webhooks/subscriptions/{id}/stats: get: summary: Get webhook subscription stats tags: - Webhooks description: |- Get delivery statistics for a webhook subscription **Permissions:** 🔵 `webhooks.read` parameters: - schema: type: string in: path name: id required: true description: Webhook subscription ID responses: "200": description: Default Response content: application/json: schema: type: object properties: status: type: string enum: - success data: type: object properties: totalDeliveries: type: number description: Total number of deliveries successCount: type: number description: Number of successful deliveries failedCount: type: number description: Number of failed deliveries retryingCount: type: number description: Number of deliveries currently retrying successRate: type: number description: Success rate percentage dailyStats: type: array items: type: object properties: date: type: string format: date description: Date (YYYY-MM-DD) success: type: number description: Successful deliveries on this date failed: type: number description: Failed deliveries on this date required: - date - success - failed description: Daily delivery stats for the last 30 days lastDeliveredAt: type: string format: date-time nullable: true description: Last successful delivery timestamp required: - totalDeliveries - successCount - failedCount - retryingCount - successRate - dailyStats - lastDeliveredAt meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - data - meta "400": description: Bad Request - Invalid input parameters content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_INPUT message: Invalid request parameters meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 5 "401": description: Unauthorized - Missing or invalid API key content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INVALID_API_KEY message: Invalid API key provided meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 3 "403": description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INSUFFICIENT_PERMISSIONS message: You do not have permission to access this resource meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 4 "404": description: Not Found - Resource does not exist content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RESOURCE_NOT_FOUND message: The requested resource was not found meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 2 "429": description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded. Please try again later. meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 1 "500": description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true required: - code - message meta: type: object properties: requestId: type: string timestamp: type: string format: date-time executionTimeMs: type: number required: - requestId - timestamp - executionTimeMs required: - status - error - meta example: status: error error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred meta: requestId: req_123456 timestamp: 2025-01-15T10:30:00.000Z executionTimeMs: 10 servers: - url: https://common-api.karma.life description: Production - url: https://common-api.beta.karma.life description: Beta - url: https://common-api.development.karma.life description: Development security: - ApiKeyAuth: [] tags: - name: Alerts description: System notifications and warnings - name: Analytics description: Enterprise real-time analytics with BigQuery - name: Automations description: Drip campaign automations with visual flow editor - name: Bookings description: Table reservations and booking management - name: Bookings - Optimization description: AI-powered booking table optimization - name: Bookings - Settings description: Location booking settings and configuration - name: Bookings - Users description: Guest user search and creation for bookings - name: Bookings - Waitlist description: Booking waitlist management - name: Capacity Settings description: Time slot capacity configuration and limits - name: Channels description: Sales channels (dine-in, takeaway, delivery) - name: Coursings description: Multi-course meal sequencing - name: Custom Tags description: Labels and categorization - name: Customers description: Location-scoped guest user records, overrides, and editing - name: CWI description: Company-Wide Items (CWI) management via EAN - name: Data Streaming description: Real-time data streaming and sync - name: Extended Waiting Time description: Extended waiting times during busy periods - name: Inventory description: Menu items, products, and modifiers - name: Invoices description: Invoice management, recipients, and location settings - name: Location Maps description: Floor plans and seating layouts - name: Locations description: Location management and creation - name: Loyalty Programs description: Customer loyalty programs, points, tiers, and rewards - name: Menu Layouts description: Menu structure and organization - name: Notes description: Notes attached to tabs and orders - name: Orders description: Customer orders and order management - name: Payment Methods description: User payment methods management - name: Permissions description: Permission registry and management - name: Print Templates description: Print template management for receipts and tickets - name: Printers description: Receipt and ticket printer management with CloudPRNT URLs - name: Public description: Simplified endpoints for external integrations — place orders without complex setup - name: Purchases description: Purchase history and transaction details - name: Reporting description: Purchase summary reports and financial reporting - name: Retailer Users description: Retailer user management and invitations - name: Reviews description: Customer reviews and feedback for purchases - name: Roles description: Role management with permission assignment - name: Schedules description: Operating hours and special schedules - name: Settlements description: Tab settlements and payment groupings - name: Statistics description: Sales statistics, time series, and aggregated data - name: Table Groups description: Table grouping and floor plans - name: Tables description: Restaurant table management - name: Tabs description: Customer tabs and running bills - name: Terminals description: Payment terminal management - name: Time Slots description: Available time slots for orders and bookings - name: Translations description: Multi-language translations for inventory and menus - name: Users description: End user management and lookup - name: Variant Groups description: Product options and modifiers - name: Vouchers description: Discount vouchers and promotions - name: Webhooks description: Webhook subscriptions and event notifications