{
  "openapi": "3.0.3",
  "info": {
    "title": "POS API",
    "version": "1.0.0",
    "description": "All responses use `{ success, message, data, meta }`; errors use `{ success: false, message, error: { code, details, requestId } }`. Lists accept `page`, `limit`, `sort` and `fields`."
  },
  "servers": [
    {
      "url": "https://your-store.example.com/api/v1",
      "description": "Replace with your store address"
    }
  ],
  "tags": [
    {
      "name": "auth",
      "description": "Get an access token with a username and password, or use an API key created in Online store > API & Webhooks. Send either as `Authorization: Bearer <token>` (API keys may also use `X-API-Key`).",
      "x-displayName": "Authentication"
    },
    {
      "name": "users",
      "description": "Staff accounts. Password hashes, two-factor secrets and session data are never returned. API keys need the `admin` scope.",
      "x-displayName": "Users"
    },
    {
      "name": "stores",
      "description": "Stores (branches). Without the pos.stores permission you only see the store your account is assigned to. API keys need the `pos` scope.",
      "x-displayName": "Stores"
    },
    {
      "name": "products",
      "description": "Products, variants, prices and stock. Reading needs pos.products or pos.pos; changes need pos.products. Cost prices are only shown with pos.products. API keys need the `pos` scope.",
      "x-displayName": "Products & inventory"
    },
    {
      "name": "orders",
      "description": "Sales orders and refunds. Reading needs pos.sales or pos.pos; selling needs pos.pos. Orders are created in your store with catalogue prices. API keys need the `pos` scope.",
      "x-displayName": "Orders & refunds"
    },
    {
      "name": "customers",
      "description": "CRM customers, with loyalty balances. Reading needs crm.customers (or pos.pos, for looking up customers at the till); changes need crm.addcustomer. API keys need the `crm` scope.",
      "x-displayName": "Customers"
    },
    {
      "name": "crm",
      "description": "Leads (crm.leads), support tickets (crm.view), the loyalty report (crm.loyalty) and a customer timeline. API keys need the `crm` scope.",
      "x-displayName": "CRM"
    },
    {
      "name": "hr",
      "description": "Employees (hr.employees), attendance (hr.attendance), leave (hr.leaves) and payroll (hr.payroll). Read only. API keys need the `hr` scope.",
      "x-displayName": "Human resources"
    },
    {
      "name": "finance",
      "description": "Read-only access to the Finance module. Each list needs the matching Finance permission (e.g. financial.finexpenses). API keys need the `finance` scope.",
      "x-displayName": "Finance"
    },
    {
      "name": "projects",
      "description": "Projects (project.project) and tasks (project.alltask), limited to the ones you take part in. API keys need the `projects` scope.",
      "x-displayName": "Projects"
    },
    {
      "name": "reports",
      "description": "Sales reports (pos.report or pos.sales). Cancelled and refunded orders are left out. Default period: the last 30 days. API keys need the `reports` scope.",
      "x-displayName": "Reports"
    },
    {
      "name": "admin",
      "description": "Activity log, permissions and settings. API keys need the `admin` scope.",
      "x-displayName": "Administration"
    },
    {
      "name": "notifications",
      "description": "Your own in-app notifications (the bell). No extra permission needed. API keys need the `notifications` scope, or plain read/write.",
      "x-displayName": "Notifications"
    },
    {
      "name": "webhooks",
      "description": "Send events to other systems. Each delivery is a signed JSON POST (see the X-Webhook-Signature header: HMAC-SHA256 of \"<timestamp>.<body>\" with the webhook secret), retried with growing delays when the receiver is down. Needs pos.onlinestore; API keys need the `admin` scope.",
      "x-displayName": "Webhooks & events"
    },
    {
      "name": "ai",
      "description": "Questions about sales, stock, customers, finance, HR and projects, answered from this installation's data without any internet service. API keys need the `ai` scope (or plain read) plus the scope of the data asked about.",
      "x-displayName": "Assistant"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Access token from POST /auth/token, or an API key."
      },
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API key from Online store > API & Webhooks."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "message": {
            "type": "string"
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "details": {},
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Error": {
        "description": "Error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "bearer": []
    },
    {
      "apiKey": []
    }
  ],
  "paths": {
    "/auth/token": {
      "post": {
        "operationId": "auth.token",
        "tags": [
          "auth"
        ],
        "summary": "Get an access token",
        "description": "Signs in with a username and password (and the 6-digit code when two-factor sign-in is on) and returns a bearer token valid for 12 hours. The token is shown only once. Five wrong passwords in a row disable the account, as on the sign-in page.\n\nNo authentication needed.",
        "parameters": [],
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "token": "mtk_<token shown once>",
                        "tokenType": "Bearer",
                        "expiresAt": "2026-10-02T21:30:00.000Z",
                        "expiresIn": 43200,
                        "user": {
                          "id": "66f1c2a9e4b0a1b2c3d4e502",
                          "username": "jane",
                          "name": "Jane Doe"
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": null,
        "x-scope": null,
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "username": {
                    "type": "string",
                    "maxLength": 100,
                    "example": "jane"
                  },
                  "password": {
                    "type": "string",
                    "maxLength": 200,
                    "example": "••••••••"
                  },
                  "otp": {
                    "type": "string",
                    "pattern": "^\\d{6}$",
                    "description": "Two-factor code, when enabled for the account."
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 80,
                    "description": "Label for this token, e.g. \"Warehouse scanner\"."
                  }
                },
                "required": [
                  "username",
                  "password"
                ]
              }
            }
          }
        }
      }
    },
    "/auth/me": {
      "get": {
        "operationId": "auth.me",
        "tags": [
          "auth"
        ],
        "summary": "Current user and credential",
        "description": "The user the request acts as, their permissions, and the credential used (type, name, scopes, expiry).\n\nAny signed-in user.\n\nScope: `auth:read`.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "user": {
                          "id": "66f1c2a9e4b0a1b2c3d4e502",
                          "username": "jane",
                          "name": "Jane Doe",
                          "email": "jane@example.com",
                          "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                          "storeName": "Main Street",
                          "isSuperAdmin": false,
                          "permissions": {
                            "pos": {
                              "pos": "1",
                              "products": "1",
                              "sales": "1"
                            },
                            "crm": {
                              "customers": "1"
                            }
                          },
                          "twoFactorEnabled": true
                        },
                        "credential": {
                          "type": "token",
                          "id": "66f1c2a9e4b0a1b2c3d4e517",
                          "name": "Warehouse scanner",
                          "scopes": [
                            "*"
                          ],
                          "expiresAt": "2026-10-02T21:30:00.000Z"
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": null,
        "x-scope": "auth:read"
      }
    },
    "/auth/tokens": {
      "get": {
        "operationId": "auth.tokens.list",
        "tags": [
          "auth"
        ],
        "summary": "List your access tokens",
        "description": "Tokens you created with /auth/token (not their values).\n\nAny signed-in user.\n\nScope: `auth:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e517",
                          "name": "Warehouse scanner",
                          "scopes": [
                            "*"
                          ],
                          "createdAt": "2026-10-01T09:30:00.000Z",
                          "expiresAt": "2026-10-02T21:30:00.000Z",
                          "lastUsedAt": "2026-10-02T14:05:00.000Z",
                          "lastIp": "102.89.1.20",
                          "revoked": false,
                          "current": true
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": null,
        "x-scope": "auth:read"
      }
    },
    "/auth/tokens/{id}": {
      "delete": {
        "operationId": "auth.tokens.revoke",
        "tags": [
          "auth"
        ],
        "summary": "Revoke one of your tokens",
        "description": "Revoked tokens stop working at once. Use the id `current` to revoke the token making the request (sign out).\n\nAny signed-in user.\n\nScope: `auth:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^([a-f0-9]{24}|current)$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e517",
                        "revoked": true
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": null,
        "x-scope": "auth:read"
      }
    },
    "/users": {
      "get": {
        "operationId": "users.list",
        "tags": [
          "users"
        ],
        "summary": "List users",
        "description": "Permission: `admin.admin` or `admin.view`.\n\nScope: `admin:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "active",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "description": "Only active (true) or disabled (false) users."
            },
            "description": "Only active (true) or disabled (false) users."
          },
          {
            "name": "storeId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$",
              "description": "Only users assigned to this store."
            },
            "description": "Only users assigned to this store."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e502",
                          "username": "jane",
                          "name": "Jane Doe",
                          "email": "jane@example.com",
                          "mobile": "08012345678",
                          "address": "",
                          "active": true,
                          "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                          "storeName": "Main Street",
                          "isSuperAdmin": false,
                          "lastLoginAt": "2026-10-02T14:05:00.000Z",
                          "passwordChangedAt": "2026-10-01T09:30:00.000Z",
                          "createdAt": "2026-10-01T09:30:00.000Z",
                          "updatedAt": "2026-10-02T14:05:00.000Z"
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "admin",
          "keys": [
            "admin",
            "view"
          ]
        },
        "x-scope": "admin:read"
      },
      "post": {
        "operationId": "users.create",
        "tags": [
          "users"
        ],
        "summary": "Create a user",
        "description": "New users start with no permissions. They are created disabled unless `active` is true and you may approve users (admin.switch), as on the Admin page.\n\nPermission: `admin.add`.\n\nScope: `admin:write`.",
        "parameters": [],
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e502",
                        "username": "jane",
                        "name": "Jane Doe",
                        "email": "jane@example.com",
                        "mobile": "08012345678",
                        "address": "",
                        "active": true,
                        "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                        "storeName": "Main Street",
                        "isSuperAdmin": false,
                        "lastLoginAt": "2026-10-02T14:05:00.000Z",
                        "passwordChangedAt": "2026-10-01T09:30:00.000Z",
                        "createdAt": "2026-10-01T09:30:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z",
                        "permissions": {
                          "pos": {
                            "pos": "1",
                            "products": "1",
                            "sales": "1"
                          },
                          "crm": {
                            "customers": "1"
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "admin",
          "keys": "add"
        },
        "x-scope": "admin:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "username": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 50,
                    "pattern": "^[A-Za-z0-9._-]+$"
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 200
                  },
                  "mobile": {
                    "type": "string",
                    "pattern": "^[0-9+]{7,15}$"
                  },
                  "address": {
                    "type": "string",
                    "maxLength": 300
                  },
                  "password": {
                    "type": "string",
                    "maxLength": 128,
                    "description": "At least 8 characters with upper and lower case letters, a number and a symbol."
                  },
                  "storeId": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{24}$"
                  },
                  "active": {
                    "type": "boolean",
                    "default": false
                  }
                },
                "required": [
                  "username",
                  "name",
                  "email",
                  "mobile",
                  "password",
                  "storeId"
                ]
              }
            }
          }
        }
      }
    },
    "/users/{id}": {
      "get": {
        "operationId": "users.get",
        "tags": [
          "users"
        ],
        "summary": "Get a user (with permissions)",
        "description": "Permission: `admin.admin` or `admin.view`.\n\nScope: `admin:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e502",
                        "username": "jane",
                        "name": "Jane Doe",
                        "email": "jane@example.com",
                        "mobile": "08012345678",
                        "address": "",
                        "active": true,
                        "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                        "storeName": "Main Street",
                        "isSuperAdmin": false,
                        "lastLoginAt": "2026-10-02T14:05:00.000Z",
                        "passwordChangedAt": "2026-10-01T09:30:00.000Z",
                        "createdAt": "2026-10-01T09:30:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z",
                        "permissions": {
                          "pos": {
                            "pos": "1",
                            "products": "1",
                            "sales": "1"
                          },
                          "crm": {
                            "customers": "1"
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "admin",
          "keys": [
            "admin",
            "view"
          ]
        },
        "x-scope": "admin:read"
      },
      "patch": {
        "operationId": "users.update",
        "tags": [
          "users"
        ],
        "summary": "Update a user",
        "description": "Send only the fields to change. Changing `active` needs admin.switch; you cannot disable your own account.\n\nPermission: `admin.edit`.\n\nScope: `admin:write`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e502",
                        "username": "jane",
                        "name": "Jane Doe",
                        "email": "jane@example.com",
                        "mobile": "08012345678",
                        "address": "",
                        "active": true,
                        "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                        "storeName": "Main Street",
                        "isSuperAdmin": false,
                        "lastLoginAt": "2026-10-02T14:05:00.000Z",
                        "passwordChangedAt": "2026-10-01T09:30:00.000Z",
                        "createdAt": "2026-10-01T09:30:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z",
                        "permissions": {
                          "pos": {
                            "pos": "1",
                            "products": "1",
                            "sales": "1"
                          },
                          "crm": {
                            "customers": "1"
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "admin",
          "keys": "edit"
        },
        "x-scope": "admin:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 200
                  },
                  "mobile": {
                    "type": "string",
                    "pattern": "^[0-9+]{7,15}$"
                  },
                  "address": {
                    "type": "string",
                    "maxLength": 300
                  },
                  "storeId": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{24}$"
                  },
                  "active": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/users/{id}/permissions": {
      "put": {
        "operationId": "users.permissions",
        "tags": [
          "users"
        ],
        "summary": "Replace a user's permissions",
        "description": "Send the complete set, e.g. `{ \"permissions\": { \"pos\": { \"pos\": true, \"products\": true }, \"crm\": { \"customers\": true } } }`. Menus and keys are listed by GET /admin/permissions. You cannot change your own permissions.\n\nPermission: `admin.permission`.\n\nScope: `admin:write`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e502",
                        "username": "jane",
                        "name": "Jane Doe",
                        "email": "jane@example.com",
                        "mobile": "08012345678",
                        "address": "",
                        "active": true,
                        "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                        "storeName": "Main Street",
                        "isSuperAdmin": false,
                        "lastLoginAt": "2026-10-02T14:05:00.000Z",
                        "passwordChangedAt": "2026-10-01T09:30:00.000Z",
                        "createdAt": "2026-10-01T09:30:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z",
                        "permissions": {
                          "pos": {
                            "pos": "1",
                            "products": "1",
                            "sales": "1"
                          },
                          "crm": {
                            "customers": "1"
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "admin",
          "keys": "permission"
        },
        "x-scope": "admin:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "permissions": {
                    "type": "object"
                  }
                },
                "required": [
                  "permissions"
                ]
              }
            }
          }
        }
      }
    },
    "/stores": {
      "get": {
        "operationId": "stores.list",
        "tags": [
          "stores"
        ],
        "summary": "List stores",
        "description": "Any signed-in user.\n\nScope: `pos:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e501",
                          "name": "Main Street",
                          "type": "retail",
                          "status": "active",
                          "address": "12 Market Road",
                          "city": "Lagos",
                          "state": "Lagos",
                          "zip": "",
                          "phone": "08012345678",
                          "email": "main@example.com",
                          "manager": "Jane Doe",
                          "timezone": "Africa/Lagos",
                          "currencySymbol": "NGN",
                          "vatRate": 7.5,
                          "stockControl": true,
                          "paymentBeforeOrder": true,
                          "onlineOrders": true,
                          "shipping": false,
                          "confirmationEmails": true,
                          "businessHours": null,
                          "createdAt": "2026-10-01T09:30:00.000Z",
                          "updatedAt": "2026-10-02T14:05:00.000Z"
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": null,
        "x-scope": "pos:read"
      }
    },
    "/stores/{id}": {
      "get": {
        "operationId": "stores.get",
        "tags": [
          "stores"
        ],
        "summary": "Get a store",
        "description": "Any signed-in user.\n\nScope: `pos:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e501",
                        "name": "Main Street",
                        "type": "retail",
                        "status": "active",
                        "address": "12 Market Road",
                        "city": "Lagos",
                        "state": "Lagos",
                        "zip": "",
                        "phone": "08012345678",
                        "email": "main@example.com",
                        "manager": "Jane Doe",
                        "timezone": "Africa/Lagos",
                        "currencySymbol": "NGN",
                        "vatRate": 7.5,
                        "stockControl": true,
                        "paymentBeforeOrder": true,
                        "onlineOrders": true,
                        "shipping": false,
                        "confirmationEmails": true,
                        "businessHours": null,
                        "createdAt": "2026-10-01T09:30:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": null,
        "x-scope": "pos:read"
      }
    },
    "/products": {
      "get": {
        "operationId": "products.list",
        "tags": [
          "products"
        ],
        "summary": "List products",
        "description": "Permission: `pos.products` or `pos.pos`.\n\nScope: `pos:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "store",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 30,
              "pattern": "^(all|current|[a-f0-9]{24})$",
              "description": "\"all\" or a store id (needs pos.stores). Default: your store."
            },
            "description": "\"all\" or a store id (needs pos.stores). Default: your store."
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "brand",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "inactive",
                "discontinued",
                "draft"
              ]
            }
          },
          {
            "name": "sku",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 60,
              "description": "Exact product or variant SKU."
            },
            "description": "Exact product or variant SKU."
          },
          {
            "name": "barcode",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 60
            }
          },
          {
            "name": "stock",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "out",
                "low",
                "in"
              ],
              "description": "Products with at least one variant at this stock level."
            },
            "description": "Products with at least one variant at this stock level."
          },
          {
            "name": "expiry",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "expired",
                "expiring",
                "none"
              ],
              "description": "\"expiring\" = within the configured window."
            },
            "description": "\"expiring\" = within the configured window."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e503",
                          "name": "Rice 5kg",
                          "sku": "RICE5",
                          "barcode": "6151234567890",
                          "description": "Long-grain parboiled rice.",
                          "category": "Food",
                          "subcategory": "Grains",
                          "kitchenCategory": "",
                          "brand": "Golden Penny",
                          "status": "active",
                          "tags": [
                            "staple"
                          ],
                          "images": [],
                          "weight": 5,
                          "expiryDate": "2027-06-30",
                          "expiryStatus": "valid",
                          "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                          "storeName": "Main Street",
                          "totalQuantity": 42,
                          "variants": [
                            {
                              "id": "66f1c2a9e4b0a1b2c3d4e504",
                              "variantId": "v_1a2b3c4d5e6f",
                              "name": "Rice 5kg",
                              "sku": "RICE5",
                              "price": 6500,
                              "compareAtPrice": 7000,
                              "currency": "NGN",
                              "quantity": 42,
                              "threshold": 5,
                              "stockLevel": "in",
                              "location": "Aisle 3",
                              "isActive": true,
                              "attributes": {
                                "size": "5kg"
                              },
                              "cost": 5200
                            }
                          ],
                          "createdAt": "2026-10-01T09:30:00.000Z",
                          "updatedAt": "2026-10-02T14:05:00.000Z"
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": [
            "products",
            "pos"
          ]
        },
        "x-scope": "pos:read"
      },
      "post": {
        "operationId": "products.create",
        "tags": [
          "products"
        ],
        "summary": "Create a product",
        "description": "Creates the product in your store (or `storeId`, with pos.stores). Images are added in the app.\n\nPermission: `pos.products`.\n\nScope: `pos:write`.",
        "parameters": [],
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e503",
                        "name": "Rice 5kg",
                        "sku": "RICE5",
                        "barcode": "6151234567890",
                        "description": "Long-grain parboiled rice.",
                        "category": "Food",
                        "subcategory": "Grains",
                        "kitchenCategory": "",
                        "brand": "Golden Penny",
                        "status": "active",
                        "tags": [
                          "staple"
                        ],
                        "images": [],
                        "weight": 5,
                        "expiryDate": "2027-06-30",
                        "expiryStatus": "valid",
                        "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                        "storeName": "Main Street",
                        "totalQuantity": 42,
                        "variants": [
                          {
                            "id": "66f1c2a9e4b0a1b2c3d4e504",
                            "variantId": "v_1a2b3c4d5e6f",
                            "name": "Rice 5kg",
                            "sku": "RICE5",
                            "price": 6500,
                            "compareAtPrice": 7000,
                            "currency": "NGN",
                            "quantity": 42,
                            "threshold": 5,
                            "stockLevel": "in",
                            "location": "Aisle 3",
                            "isActive": true,
                            "attributes": {
                              "size": "5kg"
                            },
                            "cost": 5200
                          }
                        ],
                        "createdAt": "2026-10-01T09:30:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": "products"
        },
        "x-scope": "pos:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "sku": {
                    "type": "string",
                    "maxLength": 60,
                    "pattern": "^[A-Za-z0-9._-]+$"
                  },
                  "barcode": {
                    "type": "string",
                    "maxLength": 60
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 5000
                  },
                  "category": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "subcategory": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "kitchenCategory": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "brand": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "active",
                      "inactive",
                      "discontinued",
                      "draft"
                    ],
                    "default": "active"
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 50
                    },
                    "maxItems": 30
                  },
                  "weight": {
                    "type": "number",
                    "minimum": 0
                  },
                  "expiryDate": {
                    "type": "string",
                    "maxLength": 10,
                    "pattern": "^(\\d{4}-\\d{2}-\\d{2})?$",
                    "description": "YYYY-MM-DD; empty string clears it."
                  },
                  "currency": {
                    "type": "string",
                    "maxLength": 10,
                    "description": "Defaults to the store's currency."
                  },
                  "storeId": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{24}$"
                  },
                  "variants": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "maxLength": 100
                        },
                        "sku": {
                          "type": "string",
                          "maxLength": 60
                        },
                        "price": {
                          "type": "number",
                          "minimum": 0
                        },
                        "compareAtPrice": {
                          "type": "number",
                          "minimum": 0
                        },
                        "cost": {
                          "type": "number",
                          "minimum": 0
                        },
                        "quantity": {
                          "type": "integer",
                          "minimum": 0,
                          "default": 0
                        },
                        "threshold": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "location": {
                          "type": "string",
                          "maxLength": 100
                        },
                        "attributes": {
                          "type": "object",
                          "description": "e.g. { \"size\": \"M\", \"color\": \"red\" }"
                        }
                      },
                      "required": [
                        "price"
                      ]
                    },
                    "minItems": 1,
                    "maxItems": 50
                  }
                },
                "required": [
                  "name",
                  "sku",
                  "category",
                  "variants"
                ]
              }
            }
          }
        }
      }
    },
    "/products/{id}": {
      "get": {
        "operationId": "products.get",
        "tags": [
          "products"
        ],
        "summary": "Get a product",
        "description": "Permission: `pos.products` or `pos.pos`.\n\nScope: `pos:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e503",
                        "name": "Rice 5kg",
                        "sku": "RICE5",
                        "barcode": "6151234567890",
                        "description": "Long-grain parboiled rice.",
                        "category": "Food",
                        "subcategory": "Grains",
                        "kitchenCategory": "",
                        "brand": "Golden Penny",
                        "status": "active",
                        "tags": [
                          "staple"
                        ],
                        "images": [],
                        "weight": 5,
                        "expiryDate": "2027-06-30",
                        "expiryStatus": "valid",
                        "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                        "storeName": "Main Street",
                        "totalQuantity": 42,
                        "variants": [
                          {
                            "id": "66f1c2a9e4b0a1b2c3d4e504",
                            "variantId": "v_1a2b3c4d5e6f",
                            "name": "Rice 5kg",
                            "sku": "RICE5",
                            "price": 6500,
                            "compareAtPrice": 7000,
                            "currency": "NGN",
                            "quantity": 42,
                            "threshold": 5,
                            "stockLevel": "in",
                            "location": "Aisle 3",
                            "isActive": true,
                            "attributes": {
                              "size": "5kg"
                            },
                            "cost": 5200
                          }
                        ],
                        "createdAt": "2026-10-01T09:30:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": [
            "products",
            "pos"
          ]
        },
        "x-scope": "pos:read"
      },
      "patch": {
        "operationId": "products.update",
        "tags": [
          "products"
        ],
        "summary": "Update product details",
        "description": "Send only the fields to change. Prices and stock are changed per variant (see below).\n\nPermission: `pos.products`.\n\nScope: `pos:write`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e503",
                        "name": "Rice 5kg",
                        "sku": "RICE5",
                        "barcode": "6151234567890",
                        "description": "Long-grain parboiled rice.",
                        "category": "Food",
                        "subcategory": "Grains",
                        "kitchenCategory": "",
                        "brand": "Golden Penny",
                        "status": "active",
                        "tags": [
                          "staple"
                        ],
                        "images": [],
                        "weight": 5,
                        "expiryDate": "2027-06-30",
                        "expiryStatus": "valid",
                        "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                        "storeName": "Main Street",
                        "totalQuantity": 42,
                        "variants": [
                          {
                            "id": "66f1c2a9e4b0a1b2c3d4e504",
                            "variantId": "v_1a2b3c4d5e6f",
                            "name": "Rice 5kg",
                            "sku": "RICE5",
                            "price": 6500,
                            "compareAtPrice": 7000,
                            "currency": "NGN",
                            "quantity": 42,
                            "threshold": 5,
                            "stockLevel": "in",
                            "location": "Aisle 3",
                            "isActive": true,
                            "attributes": {
                              "size": "5kg"
                            },
                            "cost": 5200
                          }
                        ],
                        "createdAt": "2026-10-01T09:30:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": "products"
        },
        "x-scope": "pos:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "barcode": {
                    "type": "string",
                    "maxLength": 60
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 5000
                  },
                  "category": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "subcategory": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "kitchenCategory": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "brand": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "active",
                      "inactive",
                      "discontinued",
                      "draft"
                    ]
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 50
                    },
                    "maxItems": 30
                  },
                  "weight": {
                    "type": "number",
                    "minimum": 0
                  },
                  "expiryDate": {
                    "type": "string",
                    "maxLength": 10,
                    "pattern": "^(\\d{4}-\\d{2}-\\d{2})?$",
                    "description": "YYYY-MM-DD; empty string clears it."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/products/{id}/variants/{variantId}": {
      "patch": {
        "operationId": "products.variant.update",
        "tags": [
          "products"
        ],
        "summary": "Update a variant (price, threshold…)",
        "description": "`variantId` may be the variant id, its variantId or its SKU. Use the stock endpoint to change quantities.\n\nPermission: `pos.products`.\n\nScope: `pos:write`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          },
          {
            "name": "variantId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 80
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e503",
                        "name": "Rice 5kg",
                        "sku": "RICE5",
                        "barcode": "6151234567890",
                        "description": "Long-grain parboiled rice.",
                        "category": "Food",
                        "subcategory": "Grains",
                        "kitchenCategory": "",
                        "brand": "Golden Penny",
                        "status": "active",
                        "tags": [
                          "staple"
                        ],
                        "images": [],
                        "weight": 5,
                        "expiryDate": "2027-06-30",
                        "expiryStatus": "valid",
                        "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                        "storeName": "Main Street",
                        "totalQuantity": 42,
                        "variants": [
                          {
                            "id": "66f1c2a9e4b0a1b2c3d4e504",
                            "variantId": "v_1a2b3c4d5e6f",
                            "name": "Rice 5kg",
                            "sku": "RICE5",
                            "price": 6500,
                            "compareAtPrice": 7000,
                            "currency": "NGN",
                            "quantity": 42,
                            "threshold": 5,
                            "stockLevel": "in",
                            "location": "Aisle 3",
                            "isActive": true,
                            "attributes": {
                              "size": "5kg"
                            },
                            "cost": 5200
                          }
                        ],
                        "createdAt": "2026-10-01T09:30:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": "products"
        },
        "x-scope": "pos:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "price": {
                    "type": "number",
                    "minimum": 0
                  },
                  "compareAtPrice": {
                    "type": "number",
                    "minimum": 0
                  },
                  "cost": {
                    "type": "number",
                    "minimum": 0
                  },
                  "threshold": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "location": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "isActive": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/products/{id}/stock": {
      "post": {
        "operationId": "products.stock",
        "tags": [
          "products"
        ],
        "summary": "Adjust stock",
        "description": "Either `adjustment` (e.g. 10 received, -2 damaged) or `quantity` (stock count). Stock never goes below zero; an adjustment that would is refused with 409. Low and out-of-stock alerts are raised as in the app.\n\nPermission: `pos.products`.\n\nScope: `pos:write`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "productId": "66f1c2a9e4b0a1b2c3d4e503",
                        "variantId": "66f1c2a9e4b0a1b2c3d4e504",
                        "before": 42,
                        "after": 52,
                        "stockLevel": "in"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": "products"
        },
        "x-scope": "pos:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "variantId": {
                    "type": "string",
                    "maxLength": 80,
                    "description": "Required when the product has several variants."
                  },
                  "adjustment": {
                    "type": "integer",
                    "minimum": -1000000,
                    "maximum": 1000000
                  },
                  "quantity": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 100000000
                  },
                  "reason": {
                    "type": "string",
                    "maxLength": 200,
                    "example": "Stock count"
                  }
                },
                "required": [
                  "reason"
                ]
              }
            }
          }
        }
      }
    },
    "/inventory/summary": {
      "get": {
        "operationId": "inventory.summary",
        "tags": [
          "products"
        ],
        "summary": "Inventory alerts summary",
        "description": "Counts of expired, expiring, out-of-stock and low-stock items (as on the inventory dashboard).\n\nPermission: `pos.products` or `pos.pos`.\n\nScope: `pos:read`.",
        "parameters": [
          {
            "name": "store",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 30,
              "pattern": "^(all|current|[a-f0-9]{24})$",
              "description": "\"all\" or a store id (needs pos.stores). Default: your store."
            },
            "description": "\"all\" or a store id (needs pos.stores). Default: your store."
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 365,
              "description": "Expiring window in days."
            },
            "description": "Expiring window in days."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "days": 30,
                        "expired": 1,
                        "expiring": 3,
                        "out": 2,
                        "low": 5,
                        "stores": [
                          "66f1c2a9e4b0a1b2c3d4e501"
                        ]
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": [
            "products",
            "pos"
          ]
        },
        "x-scope": "pos:read"
      }
    },
    "/inventory/report": {
      "get": {
        "operationId": "inventory.report",
        "tags": [
          "products"
        ],
        "summary": "Inventory alert list",
        "description": "One row per affected product (expiry) or variant (stock).\n\nPermission: `pos.products` or `pos.pos`.\n\nScope: `pos:read`.",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "expired",
                "expiring",
                "out",
                "low"
              ]
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 365
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "store",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 30,
              "pattern": "^(all|current|[a-f0-9]{24})$",
              "description": "\"all\" or a store id (needs pos.stores). Default: your store."
            },
            "description": "\"all\" or a store id (needs pos.stores). Default: your store."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "productId": "66f1c2a9e4b0a1b2c3d4e503",
                          "name": "Rice 5kg",
                          "sku": "RICE5",
                          "category": "Food",
                          "variant": "Rice 5kg",
                          "variantSku": "RICE5",
                          "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                          "storeName": "Main Street",
                          "status": "low",
                          "quantity": 4,
                          "threshold": 5,
                          "location": "Aisle 3",
                          "expiryDate": "2027-06-30T00:00:00.000Z",
                          "daysLeft": 271,
                          "type": "low"
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": [
            "products",
            "pos"
          ]
        },
        "x-scope": "pos:read"
      }
    },
    "/orders": {
      "get": {
        "operationId": "orders.list",
        "tags": [
          "orders"
        ],
        "summary": "List orders",
        "description": "Permission: `pos.sales` or `pos.pos`.\n\nScope: `pos:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "confirmed",
                "processing",
                "shipped",
                "delivered",
                "cancelled",
                "refunded",
                "on_hold"
              ]
            }
          },
          {
            "name": "paymentStatus",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "authorized",
                "paid",
                "partially_refunded",
                "refunded",
                "failed",
                "cancelled"
              ]
            }
          },
          {
            "name": "customerId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          },
          {
            "name": "orderNumber",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 60
            }
          },
          {
            "name": "source",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pos",
                "web",
                "mobile",
                "api",
                "other"
              ]
            }
          },
          {
            "name": "store",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 30,
              "pattern": "^(all|current|[a-f0-9]{24})$",
              "description": "\"all\" or a store id (needs pos.stores). Default: your store."
            },
            "description": "\"all\" or a store id (needs pos.stores). Default: your store."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e505",
                          "orderNumber": "ORD1790904240356987",
                          "status": "confirmed",
                          "source": "api",
                          "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                          "storeName": "Main Street",
                          "customer": {
                            "id": "66f1c2a9e4b0a1b2c3d4e506",
                            "name": "Ada Obi",
                            "email": "ada@example.com",
                            "phone": "08098765432"
                          },
                          "items": [
                            {
                              "productId": "66f1c2a9e4b0a1b2c3d4e503",
                              "variantId": "v_1a2b3c4d5e6f",
                              "sku": "RICE5",
                              "name": "Rice 5kg",
                              "quantity": 2,
                              "unitPrice": {
                                "amount": 6500,
                                "currency": "NGN"
                              },
                              "total": {
                                "amount": 13000,
                                "currency": "NGN"
                              }
                            }
                          ],
                          "subtotal": {
                            "amount": 13000,
                            "currency": "NGN"
                          },
                          "discount": null,
                          "tax": {
                            "amount": 975,
                            "rate": 7.5
                          },
                          "shipping": null,
                          "total": {
                            "amount": 13975,
                            "currency": "NGN"
                          },
                          "payment": {
                            "method": "cash",
                            "status": "paid",
                            "paidAt": "2026-10-02T14:05:00.000Z"
                          },
                          "fulfillmentStatus": "unfulfilled",
                          "refundStatus": null,
                          "staff": {
                            "id": "66f1c2a9e4b0a1b2c3d4e502",
                            "name": "Jane Doe"
                          },
                          "note": "",
                          "statusHistory": [
                            {
                              "status": "confirmed",
                              "at": "2026-10-02T14:05:00.000Z",
                              "by": "Jane Doe",
                              "note": null
                            }
                          ],
                          "createdAt": "2026-10-02T14:05:00.000Z",
                          "updatedAt": "2026-10-02T14:05:00.000Z"
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": [
            "sales",
            "pos"
          ]
        },
        "x-scope": "pos:read"
      },
      "post": {
        "operationId": "orders.create",
        "tags": [
          "orders"
        ],
        "summary": "Create an order (sale)",
        "description": "Sells products from your store. Prices come from the catalogue and tax from the store VAT rate; coupons, automatic discounts and loyalty points are applied as on the POS screen. When the store takes payment before the order, the order is recorded as paid with `payment.method`.\n\nPermission: `pos.pos`.\n\nScope: `pos:write`.",
        "parameters": [],
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e505",
                        "orderNumber": "ORD1790904240356987",
                        "status": "confirmed",
                        "source": "api",
                        "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                        "storeName": "Main Street",
                        "customer": {
                          "id": "66f1c2a9e4b0a1b2c3d4e506",
                          "name": "Ada Obi",
                          "email": "ada@example.com",
                          "phone": "08098765432"
                        },
                        "items": [
                          {
                            "productId": "66f1c2a9e4b0a1b2c3d4e503",
                            "variantId": "v_1a2b3c4d5e6f",
                            "sku": "RICE5",
                            "name": "Rice 5kg",
                            "quantity": 2,
                            "unitPrice": {
                              "amount": 6500,
                              "currency": "NGN"
                            },
                            "total": {
                              "amount": 13000,
                              "currency": "NGN"
                            }
                          }
                        ],
                        "subtotal": {
                          "amount": 13000,
                          "currency": "NGN"
                        },
                        "discount": null,
                        "tax": {
                          "amount": 975,
                          "rate": 7.5
                        },
                        "shipping": null,
                        "total": {
                          "amount": 13975,
                          "currency": "NGN"
                        },
                        "payment": {
                          "method": "cash",
                          "status": "paid",
                          "paidAt": "2026-10-02T14:05:00.000Z"
                        },
                        "fulfillmentStatus": "unfulfilled",
                        "refundStatus": null,
                        "staff": {
                          "id": "66f1c2a9e4b0a1b2c3d4e502",
                          "name": "Jane Doe"
                        },
                        "note": "",
                        "statusHistory": [
                          {
                            "status": "confirmed",
                            "at": "2026-10-02T14:05:00.000Z",
                            "by": "Jane Doe",
                            "note": null
                          }
                        ],
                        "createdAt": "2026-10-02T14:05:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z",
                        "loyalty": {
                          "redeemedPoints": 0,
                          "redeemedValue": 0,
                          "earnedPoints": 139,
                          "balance": 459
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": "pos"
        },
        "x-scope": "pos:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "productId": {
                          "type": "string",
                          "pattern": "^[a-f0-9]{24}$"
                        },
                        "variantId": {
                          "type": "string",
                          "maxLength": 80,
                          "description": "Needed when the product has several variants (id, variantId or SKU)."
                        },
                        "quantity": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 100000
                        }
                      },
                      "required": [
                        "productId",
                        "quantity"
                      ]
                    },
                    "minItems": 1,
                    "maxItems": 200
                  },
                  "customerId": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{24}$",
                    "description": "CRM customer (for loyalty points and receipts)."
                  },
                  "payment": {
                    "type": "object",
                    "properties": {
                      "method": {
                        "type": "string",
                        "enum": [
                          "cash",
                          "credit_card",
                          "debit_card",
                          "digital_wallet",
                          "bank_transfer",
                          "check",
                          "other"
                        ],
                        "default": "cash"
                      }
                    }
                  },
                  "couponCode": {
                    "type": "string",
                    "maxLength": 50
                  },
                  "loyaltyRedeemPoints": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Points to redeem (needs customerId)."
                  }
                },
                "required": [
                  "items"
                ]
              }
            }
          }
        }
      }
    },
    "/orders/{id}": {
      "get": {
        "operationId": "orders.get",
        "tags": [
          "orders"
        ],
        "summary": "Get an order",
        "description": "Permission: `pos.sales` or `pos.pos`.\n\nScope: `pos:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e505",
                        "orderNumber": "ORD1790904240356987",
                        "status": "confirmed",
                        "source": "api",
                        "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                        "storeName": "Main Street",
                        "customer": {
                          "id": "66f1c2a9e4b0a1b2c3d4e506",
                          "name": "Ada Obi",
                          "email": "ada@example.com",
                          "phone": "08098765432"
                        },
                        "items": [
                          {
                            "productId": "66f1c2a9e4b0a1b2c3d4e503",
                            "variantId": "v_1a2b3c4d5e6f",
                            "sku": "RICE5",
                            "name": "Rice 5kg",
                            "quantity": 2,
                            "unitPrice": {
                              "amount": 6500,
                              "currency": "NGN"
                            },
                            "total": {
                              "amount": 13000,
                              "currency": "NGN"
                            }
                          }
                        ],
                        "subtotal": {
                          "amount": 13000,
                          "currency": "NGN"
                        },
                        "discount": null,
                        "tax": {
                          "amount": 975,
                          "rate": 7.5
                        },
                        "shipping": null,
                        "total": {
                          "amount": 13975,
                          "currency": "NGN"
                        },
                        "payment": {
                          "method": "cash",
                          "status": "paid",
                          "paidAt": "2026-10-02T14:05:00.000Z"
                        },
                        "fulfillmentStatus": "unfulfilled",
                        "refundStatus": null,
                        "staff": {
                          "id": "66f1c2a9e4b0a1b2c3d4e502",
                          "name": "Jane Doe"
                        },
                        "note": "",
                        "statusHistory": [
                          {
                            "status": "confirmed",
                            "at": "2026-10-02T14:05:00.000Z",
                            "by": "Jane Doe",
                            "note": null
                          }
                        ],
                        "createdAt": "2026-10-02T14:05:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": [
            "sales",
            "pos"
          ]
        },
        "x-scope": "pos:read"
      }
    },
    "/orders/{id}/cancel": {
      "post": {
        "operationId": "orders.cancel",
        "tags": [
          "orders"
        ],
        "summary": "Cancel an order",
        "description": "Same rules as the POS screen: orders being prepared, fulfilled or already refunded cannot be cancelled. Paid orders are refunded and loyalty points reversed.\n\nPermission: `pos.pos`.\n\nScope: `pos:write`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e505",
                        "orderNumber": "ORD1790904240356987",
                        "status": "cancelled",
                        "source": "api",
                        "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                        "storeName": "Main Street",
                        "customer": {
                          "id": "66f1c2a9e4b0a1b2c3d4e506",
                          "name": "Ada Obi",
                          "email": "ada@example.com",
                          "phone": "08098765432"
                        },
                        "items": [
                          {
                            "productId": "66f1c2a9e4b0a1b2c3d4e503",
                            "variantId": "v_1a2b3c4d5e6f",
                            "sku": "RICE5",
                            "name": "Rice 5kg",
                            "quantity": 2,
                            "unitPrice": {
                              "amount": 6500,
                              "currency": "NGN"
                            },
                            "total": {
                              "amount": 13000,
                              "currency": "NGN"
                            }
                          }
                        ],
                        "subtotal": {
                          "amount": 13000,
                          "currency": "NGN"
                        },
                        "discount": null,
                        "tax": {
                          "amount": 975,
                          "rate": 7.5
                        },
                        "shipping": null,
                        "total": {
                          "amount": 13975,
                          "currency": "NGN"
                        },
                        "payment": {
                          "method": "cash",
                          "status": "paid",
                          "paidAt": "2026-10-02T14:05:00.000Z"
                        },
                        "fulfillmentStatus": "unfulfilled",
                        "refundStatus": null,
                        "staff": {
                          "id": "66f1c2a9e4b0a1b2c3d4e502",
                          "name": "Jane Doe"
                        },
                        "note": "",
                        "statusHistory": [
                          {
                            "status": "confirmed",
                            "at": "2026-10-02T14:05:00.000Z",
                            "by": "Jane Doe",
                            "note": null
                          },
                          {
                            "status": "cancelled",
                            "at": "2026-10-02T14:05:00.000Z",
                            "by": "Jane Doe",
                            "note": "Customer changed their mind"
                          }
                        ],
                        "createdAt": "2026-10-02T14:05:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": "pos"
        },
        "x-scope": "pos:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string",
                    "maxLength": 300
                  }
                }
              }
            }
          }
        }
      }
    },
    "/orders/{id}/payments": {
      "post": {
        "operationId": "orders.pay",
        "tags": [
          "orders"
        ],
        "summary": "Record a payment",
        "description": "Permission: `pos.pos`.\n\nScope: `pos:write`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e505",
                        "orderNumber": "ORD1790904240356987",
                        "status": "confirmed",
                        "source": "api",
                        "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                        "storeName": "Main Street",
                        "customer": {
                          "id": "66f1c2a9e4b0a1b2c3d4e506",
                          "name": "Ada Obi",
                          "email": "ada@example.com",
                          "phone": "08098765432"
                        },
                        "items": [
                          {
                            "productId": "66f1c2a9e4b0a1b2c3d4e503",
                            "variantId": "v_1a2b3c4d5e6f",
                            "sku": "RICE5",
                            "name": "Rice 5kg",
                            "quantity": 2,
                            "unitPrice": {
                              "amount": 6500,
                              "currency": "NGN"
                            },
                            "total": {
                              "amount": 13000,
                              "currency": "NGN"
                            }
                          }
                        ],
                        "subtotal": {
                          "amount": 13000,
                          "currency": "NGN"
                        },
                        "discount": null,
                        "tax": {
                          "amount": 975,
                          "rate": 7.5
                        },
                        "shipping": null,
                        "total": {
                          "amount": 13975,
                          "currency": "NGN"
                        },
                        "payment": {
                          "method": "cash",
                          "status": "paid",
                          "paidAt": "2026-10-02T14:05:00.000Z"
                        },
                        "fulfillmentStatus": "unfulfilled",
                        "refundStatus": null,
                        "staff": {
                          "id": "66f1c2a9e4b0a1b2c3d4e502",
                          "name": "Jane Doe"
                        },
                        "note": "",
                        "statusHistory": [
                          {
                            "status": "confirmed",
                            "at": "2026-10-02T14:05:00.000Z",
                            "by": "Jane Doe",
                            "note": null
                          }
                        ],
                        "createdAt": "2026-10-02T14:05:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": "pos"
        },
        "x-scope": "pos:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "amount": {
                    "type": "number",
                    "minimum": 0.01
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "cash",
                      "credit_card",
                      "debit_card",
                      "digital_wallet",
                      "bank_transfer",
                      "check",
                      "other"
                    ]
                  }
                },
                "required": [
                  "amount",
                  "method"
                ]
              }
            }
          }
        }
      }
    },
    "/orders/{id}/fulfill": {
      "post": {
        "operationId": "orders.fulfill",
        "tags": [
          "orders"
        ],
        "summary": "Mark an order fulfilled",
        "description": "Permission: `pos.shipping` or `pos.pos`.\n\nScope: `pos:write`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e505",
                        "orderNumber": "ORD1790904240356987",
                        "status": "completed",
                        "source": "api",
                        "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                        "storeName": "Main Street",
                        "customer": {
                          "id": "66f1c2a9e4b0a1b2c3d4e506",
                          "name": "Ada Obi",
                          "email": "ada@example.com",
                          "phone": "08098765432"
                        },
                        "items": [
                          {
                            "productId": "66f1c2a9e4b0a1b2c3d4e503",
                            "variantId": "v_1a2b3c4d5e6f",
                            "sku": "RICE5",
                            "name": "Rice 5kg",
                            "quantity": 2,
                            "unitPrice": {
                              "amount": 6500,
                              "currency": "NGN"
                            },
                            "total": {
                              "amount": 13000,
                              "currency": "NGN"
                            }
                          }
                        ],
                        "subtotal": {
                          "amount": 13000,
                          "currency": "NGN"
                        },
                        "discount": null,
                        "tax": {
                          "amount": 975,
                          "rate": 7.5
                        },
                        "shipping": null,
                        "total": {
                          "amount": 13975,
                          "currency": "NGN"
                        },
                        "payment": {
                          "method": "cash",
                          "status": "paid",
                          "paidAt": "2026-10-02T14:05:00.000Z"
                        },
                        "fulfillmentStatus": "fulfilled",
                        "refundStatus": null,
                        "staff": {
                          "id": "66f1c2a9e4b0a1b2c3d4e502",
                          "name": "Jane Doe"
                        },
                        "note": "",
                        "statusHistory": [
                          {
                            "status": "confirmed",
                            "at": "2026-10-02T14:05:00.000Z",
                            "by": "Jane Doe",
                            "note": null
                          }
                        ],
                        "createdAt": "2026-10-02T14:05:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": [
            "shipping",
            "pos"
          ]
        },
        "x-scope": "pos:write"
      }
    },
    "/refunds": {
      "get": {
        "operationId": "refunds.list",
        "tags": [
          "orders"
        ],
        "summary": "List refunds",
        "description": "Permission: `pos.refund` or `pos.sales`.\n\nScope: `pos:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          },
          {
            "name": "orderId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e507",
                          "refundNumber": "REF-1002",
                          "orderId": "66f1c2a9e4b0a1b2c3d4e505",
                          "orderNumber": "ORD1790904240356987",
                          "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                          "status": "completed",
                          "method": "original",
                          "reason": "damaged",
                          "amount": {
                            "amount": 6500,
                            "currency": "NGN"
                          },
                          "items": [
                            {
                              "productId": "66f1c2a9e4b0a1b2c3d4e503",
                              "name": "Rice 5kg",
                              "quantity": 1
                            }
                          ],
                          "customer": {
                            "id": "66f1c2a9e4b0a1b2c3d4e506",
                            "name": "Ada Obi"
                          },
                          "processedAt": "2026-10-02T14:05:00.000Z",
                          "createdAt": "2026-10-02T14:05:00.000Z"
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": [
            "refund",
            "sales"
          ]
        },
        "x-scope": "pos:read"
      }
    },
    "/refunds/{id}": {
      "get": {
        "operationId": "refunds.get",
        "tags": [
          "orders"
        ],
        "summary": "Get a refund",
        "description": "Permission: `pos.refund` or `pos.sales`.\n\nScope: `pos:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e507",
                        "refundNumber": "REF-1002",
                        "orderId": "66f1c2a9e4b0a1b2c3d4e505",
                        "orderNumber": "ORD1790904240356987",
                        "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                        "status": "completed",
                        "method": "original",
                        "reason": "damaged",
                        "amount": {
                          "amount": 6500,
                          "currency": "NGN"
                        },
                        "items": [
                          {
                            "productId": "66f1c2a9e4b0a1b2c3d4e503",
                            "name": "Rice 5kg",
                            "quantity": 1
                          }
                        ],
                        "customer": {
                          "id": "66f1c2a9e4b0a1b2c3d4e506",
                          "name": "Ada Obi"
                        },
                        "processedAt": "2026-10-02T14:05:00.000Z",
                        "createdAt": "2026-10-02T14:05:00.000Z"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": [
            "refund",
            "sales"
          ]
        },
        "x-scope": "pos:read"
      }
    },
    "/customers": {
      "get": {
        "operationId": "customers.list",
        "tags": [
          "customers"
        ],
        "summary": "List customers",
        "description": "Permission: `crm.customers` or `crm.addcustomer` or `crm.support` or `pos.pos`.\n\nScope: `crm:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          },
          {
            "name": "email",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "email"
            }
          },
          {
            "name": "phone",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 30
            }
          },
          {
            "name": "membershipTier",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "Bronze",
                "Silver",
                "Gold"
              ]
            }
          },
          {
            "name": "active",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e506",
                          "customerCode": "C-1001",
                          "name": "Ada Obi",
                          "email": "ada@example.com",
                          "phone": "08098765432",
                          "address": "4 Allen Avenue, Ikeja",
                          "taxId": "",
                          "membershipTier": "Silver",
                          "loyaltyPoints": 320,
                          "loyaltyLifetimePoints": 1450,
                          "balance": 0,
                          "minimumOrder": 0,
                          "active": true,
                          "reps": [
                            {
                              "id": "66f1c2a9e4b0a1b2c3d4e502",
                              "name": "Jane Doe"
                            }
                          ],
                          "createdBy": "Jane Doe",
                          "createdAt": "2026-10-01T09:30:00.000Z",
                          "updatedAt": "2026-10-02T14:05:00.000Z"
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": [
          {
            "plugin": "crm",
            "keys": [
              "customers",
              "addcustomer",
              "support"
            ]
          },
          {
            "plugin": "pos",
            "keys": "pos"
          }
        ],
        "x-scope": "crm:read"
      },
      "post": {
        "operationId": "customers.create",
        "tags": [
          "customers"
        ],
        "summary": "Create a customer",
        "description": "Email, phone and customer code must be unique. A welcome email is sent when that setting is on.\n\nPermission: `crm.addcustomer`.\n\nScope: `crm:write`.",
        "parameters": [],
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e506",
                        "customerCode": "C-1001",
                        "name": "Ada Obi",
                        "email": "ada@example.com",
                        "phone": "08098765432",
                        "address": "4 Allen Avenue, Ikeja",
                        "taxId": "",
                        "membershipTier": "Silver",
                        "loyaltyPoints": 320,
                        "loyaltyLifetimePoints": 1450,
                        "balance": 0,
                        "minimumOrder": 0,
                        "active": true,
                        "reps": [
                          {
                            "id": "66f1c2a9e4b0a1b2c3d4e502",
                            "name": "Jane Doe"
                          }
                        ],
                        "createdBy": "Jane Doe",
                        "createdAt": "2026-10-01T09:30:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "crm",
          "keys": "addcustomer"
        },
        "x-scope": "crm:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 150
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 200
                  },
                  "phone": {
                    "type": "string",
                    "maxLength": 30,
                    "pattern": "^[0-9+()\\s-]{5,30}$"
                  },
                  "customerCode": {
                    "type": "string",
                    "maxLength": 50,
                    "description": "Your own customer number. Generated when omitted."
                  },
                  "address": {
                    "type": "string",
                    "maxLength": 300
                  },
                  "taxId": {
                    "type": "string",
                    "maxLength": 50
                  },
                  "membershipTier": {
                    "type": "string",
                    "enum": [
                      "Bronze",
                      "Silver",
                      "Gold"
                    ],
                    "default": "Bronze"
                  },
                  "minimumOrder": {
                    "type": "number",
                    "minimum": 0
                  },
                  "active": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "name",
                  "phone"
                ]
              }
            }
          }
        }
      }
    },
    "/customers/{id}": {
      "get": {
        "operationId": "customers.get",
        "tags": [
          "customers"
        ],
        "summary": "Get a customer",
        "description": "Permission: `crm.customers` or `crm.addcustomer` or `crm.support` or `pos.pos`.\n\nScope: `crm:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e506",
                        "customerCode": "C-1001",
                        "name": "Ada Obi",
                        "email": "ada@example.com",
                        "phone": "08098765432",
                        "address": "4 Allen Avenue, Ikeja",
                        "taxId": "",
                        "membershipTier": "Silver",
                        "loyaltyPoints": 320,
                        "loyaltyLifetimePoints": 1450,
                        "balance": 0,
                        "minimumOrder": 0,
                        "active": true,
                        "reps": [
                          {
                            "id": "66f1c2a9e4b0a1b2c3d4e502",
                            "name": "Jane Doe"
                          }
                        ],
                        "createdBy": "Jane Doe",
                        "createdAt": "2026-10-01T09:30:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": [
          {
            "plugin": "crm",
            "keys": [
              "customers",
              "addcustomer",
              "support"
            ]
          },
          {
            "plugin": "pos",
            "keys": "pos"
          }
        ],
        "x-scope": "crm:read"
      },
      "patch": {
        "operationId": "customers.update",
        "tags": [
          "customers"
        ],
        "summary": "Update a customer",
        "description": "Send only the fields to change.\n\nPermission: `crm.addcustomer`.\n\nScope: `crm:write`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e506",
                        "customerCode": "C-1001",
                        "name": "Ada Obi",
                        "email": "ada@example.com",
                        "phone": "08098765432",
                        "address": "4 Allen Avenue, Ikeja",
                        "taxId": "",
                        "membershipTier": "Silver",
                        "loyaltyPoints": 320,
                        "loyaltyLifetimePoints": 1450,
                        "balance": 0,
                        "minimumOrder": 0,
                        "active": true,
                        "reps": [
                          {
                            "id": "66f1c2a9e4b0a1b2c3d4e502",
                            "name": "Jane Doe"
                          }
                        ],
                        "createdBy": "Jane Doe",
                        "createdAt": "2026-10-01T09:30:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "crm",
          "keys": "addcustomer"
        },
        "x-scope": "crm:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 150
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 200
                  },
                  "phone": {
                    "type": "string",
                    "maxLength": 30,
                    "pattern": "^[0-9+()\\s-]{5,30}$"
                  },
                  "customerCode": {
                    "type": "string",
                    "maxLength": 50,
                    "description": "Your own customer number. Generated when omitted."
                  },
                  "address": {
                    "type": "string",
                    "maxLength": 300
                  },
                  "taxId": {
                    "type": "string",
                    "maxLength": 50
                  },
                  "membershipTier": {
                    "type": "string",
                    "enum": [
                      "Bronze",
                      "Silver",
                      "Gold"
                    ]
                  },
                  "minimumOrder": {
                    "type": "number",
                    "minimum": 0
                  },
                  "active": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/customers/{id}/loyalty": {
      "get": {
        "operationId": "customers.loyalty",
        "tags": [
          "customers"
        ],
        "summary": "Loyalty balance and history",
        "description": "Permission: `crm.loyalty` or `crm.customers` or `pos.pos`.\n\nScope: `crm:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "earn",
                "redeem",
                "reverse",
                "restore",
                "adjust",
                "expire"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "summary": {
                          "customerId": "66f1c2a9e4b0a1b2c3d4e506",
                          "name": "Ada Obi",
                          "enabled": true,
                          "balance": 459,
                          "lifetime": 1589,
                          "value": 45.9,
                          "tier": "Silver",
                          "tierName": "Silver",
                          "nextTier": {
                            "key": "gold",
                            "name": "Gold",
                            "pointsNeeded": 3411
                          },
                          "redemption": {
                            "points": 100,
                            "value": 10
                          },
                          "redeemablePoints": 400,
                          "pointsPerAmount": 1,
                          "expiryMonths": 12
                        },
                        "history": [
                          {
                            "id": "66f1c2a9e4b0a1b2c3d4e508",
                            "type": "earn",
                            "points": 139,
                            "balanceAfter": 459,
                            "orderId": "66f1c2a9e4b0a1b2c3d4e505",
                            "orderNumber": "ORD1790904240356987",
                            "amount": 13975,
                            "description": "Earned on order ORD1790904240356987",
                            "source": "pos",
                            "by": "Jane Doe",
                            "createdAt": "2026-10-02T14:05:00.000Z",
                            "expiresAt": null
                          }
                        ]
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": [
          {
            "plugin": "crm",
            "keys": [
              "loyalty",
              "customers"
            ]
          },
          {
            "plugin": "pos",
            "keys": "pos"
          }
        ],
        "x-scope": "crm:read"
      }
    },
    "/customers/{id}/loyalty/adjustments": {
      "post": {
        "operationId": "customers.loyalty.adjust",
        "tags": [
          "customers"
        ],
        "summary": "Adjust loyalty points",
        "description": "Adds (positive) or removes (negative) points with a reason; recorded in the loyalty ledger. A balance cannot go below zero (409).\n\nPermission: `crm.loyaltyadjust`.\n\nScope: `crm:write`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "summary": {
                          "customerId": "66f1c2a9e4b0a1b2c3d4e506",
                          "name": "Ada Obi",
                          "enabled": true,
                          "balance": 459,
                          "lifetime": 1589,
                          "value": 45.9,
                          "tier": "Silver",
                          "tierName": "Silver",
                          "nextTier": {
                            "key": "gold",
                            "name": "Gold",
                            "pointsNeeded": 3411
                          },
                          "redemption": {
                            "points": 100,
                            "value": 10
                          },
                          "redeemablePoints": 400,
                          "pointsPerAmount": 1,
                          "expiryMonths": 12
                        },
                        "entry": {
                          "id": "66f1c2a9e4b0a1b2c3d4e508",
                          "type": "adjust",
                          "points": 50,
                          "balanceAfter": 509,
                          "orderId": null,
                          "orderNumber": null,
                          "amount": 0,
                          "description": "Goodwill for late delivery",
                          "source": "api",
                          "by": "Jane Doe",
                          "createdAt": "2026-10-02T14:05:00.000Z",
                          "expiresAt": null
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "crm",
          "keys": "loyaltyadjust"
        },
        "x-scope": "crm:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "points": {
                    "type": "integer",
                    "minimum": -1000000,
                    "maximum": 1000000
                  },
                  "reason": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 200
                  }
                },
                "required": [
                  "points",
                  "reason"
                ]
              }
            }
          }
        }
      }
    },
    "/crm/leads": {
      "get": {
        "operationId": "crm.leads.list",
        "tags": [
          "crm"
        ],
        "summary": "List leads",
        "description": "Permission: `crm.leads`.\n\nScope: `crm:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "Closed",
                "Not Contacted",
                "Contacted",
                "Lost",
                "Open"
              ]
            }
          },
          {
            "name": "priority",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "Low",
                "Medium",
                "High",
                "Urgent"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e509",
                          "name": "Bola Ade",
                          "company": "Ade Foods Ltd",
                          "email": "bola@adefoods.example",
                          "phone": "08031112222",
                          "status": "Contacted",
                          "priority": "High",
                          "source": "website",
                          "type": "wholesale",
                          "industry": "Retail",
                          "country": "Nigeria",
                          "state": "Lagos",
                          "expectedIncome": 2500000,
                          "currency": "NGN",
                          "probability": 60,
                          "owner": "Jane Doe",
                          "dueDate": "2026-10-15T00:00:00.000Z",
                          "lastContactedAt": "2026-10-01T09:30:00.000Z",
                          "nextFollowUpAt": "2026-10-05T10:00:00.000Z",
                          "closedAt": null,
                          "tags": [
                            "bulk"
                          ],
                          "createdAt": "2026-10-01T09:30:00.000Z",
                          "updatedAt": "2026-10-02T14:05:00.000Z"
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "crm",
          "keys": "leads"
        },
        "x-scope": "crm:read"
      }
    },
    "/crm/leads/{id}": {
      "get": {
        "operationId": "crm.leads.get",
        "tags": [
          "crm"
        ],
        "summary": "Get a lead (with recent activity)",
        "description": "Permission: `crm.leads`.\n\nScope: `crm:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e509",
                        "name": "Bola Ade",
                        "company": "Ade Foods Ltd",
                        "email": "bola@adefoods.example",
                        "phone": "08031112222",
                        "status": "Contacted",
                        "priority": "High",
                        "source": "website",
                        "type": "wholesale",
                        "industry": "Retail",
                        "country": "Nigeria",
                        "state": "Lagos",
                        "expectedIncome": 2500000,
                        "currency": "NGN",
                        "probability": 60,
                        "owner": "Jane Doe",
                        "dueDate": "2026-10-15T00:00:00.000Z",
                        "lastContactedAt": "2026-10-01T09:30:00.000Z",
                        "nextFollowUpAt": "2026-10-05T10:00:00.000Z",
                        "closedAt": null,
                        "tags": [
                          "bulk"
                        ],
                        "createdAt": "2026-10-01T09:30:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z",
                        "description": "Wants monthly supply of rice and oil.",
                        "website": "https://adefoods.example",
                        "activities": [
                          {
                            "type": "call",
                            "text": "Discussed pricing",
                            "by": "Jane Doe",
                            "at": "2026-10-01T09:30:00.000Z"
                          }
                        ]
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "crm",
          "keys": "leads"
        },
        "x-scope": "crm:read"
      }
    },
    "/crm/tickets": {
      "get": {
        "operationId": "crm.tickets.list",
        "tags": [
          "crm"
        ],
        "summary": "List support tickets",
        "description": "Permission: `crm.view` or `crm.support`.\n\nScope: `crm:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "answered",
                "closed"
              ]
            }
          },
          {
            "name": "customerId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e510",
                          "ticketNumber": "TCK-2041",
                          "title": "Wrong item delivered",
                          "category": "Delivery",
                          "status": "answered",
                          "customer": {
                            "id": "66f1c2a9e4b0a1b2c3d4e506",
                            "name": "Ada Obi",
                            "email": "ada@example.com"
                          },
                          "assignedTo": "Jane Doe",
                          "tag": "urgent",
                          "message": "I received beans instead of rice.",
                          "createdBy": "Jane Doe",
                          "createdAt": "2026-10-01T09:30:00.000Z",
                          "updatedAt": "2026-10-02T14:05:00.000Z"
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "crm",
          "keys": [
            "view",
            "support"
          ]
        },
        "x-scope": "crm:read"
      }
    },
    "/crm/tickets/{id}": {
      "get": {
        "operationId": "crm.tickets.get",
        "tags": [
          "crm"
        ],
        "summary": "Get a support ticket",
        "description": "Permission: `crm.view` or `crm.support`.\n\nScope: `crm:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e510",
                        "ticketNumber": "TCK-2041",
                        "title": "Wrong item delivered",
                        "category": "Delivery",
                        "status": "answered",
                        "customer": {
                          "id": "66f1c2a9e4b0a1b2c3d4e506",
                          "name": "Ada Obi",
                          "email": "ada@example.com"
                        },
                        "assignedTo": "Jane Doe",
                        "tag": "urgent",
                        "message": "I received beans instead of rice.",
                        "createdBy": "Jane Doe",
                        "createdAt": "2026-10-01T09:30:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "crm",
          "keys": [
            "view",
            "support"
          ]
        },
        "x-scope": "crm:read"
      }
    },
    "/crm/loyalty/report": {
      "get": {
        "operationId": "crm.loyalty.report",
        "tags": [
          "crm"
        ],
        "summary": "Loyalty programme report",
        "description": "Points issued, redeemed and outstanding, top earners and customers per tier for a period.\n\nPermission: `crm.loyalty`.\n\nScope: `crm:read`.",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "period": {
                          "from": "2026-09-01T00:00:00.000Z",
                          "to": "2026-09-30T23:59:59.999Z"
                        },
                        "enabled": true,
                        "totals": {
                          "earn": {
                            "points": 18450,
                            "count": 212,
                            "amount": 1845000
                          },
                          "redeem": {
                            "points": -4200,
                            "count": 31,
                            "amount": 420
                          },
                          "reverse": {
                            "points": -300,
                            "count": 2,
                            "amount": 30000
                          },
                          "restore": {
                            "points": 100,
                            "count": 1,
                            "amount": 10
                          },
                          "adjust": {
                            "points": 250,
                            "count": 3,
                            "amount": 0
                          },
                          "expire": {
                            "points": -120,
                            "count": 4,
                            "amount": 0
                          }
                        },
                        "pointsIssued": 18700,
                        "pointsRedeemed": 4200,
                        "redeemedValue": 420,
                        "outstandingPoints": 52310,
                        "outstandingCustomers": 418,
                        "outstandingValue": 5231,
                        "topEarners": [
                          {
                            "customerId": "66f1c2a9e4b0a1b2c3d4e506",
                            "name": "Ada Obi",
                            "points": 1390,
                            "orders": 9
                          }
                        ],
                        "tiers": [
                          {
                            "tier": "Bronze",
                            "customers": 301
                          },
                          {
                            "tier": "Silver",
                            "customers": 96
                          },
                          {
                            "tier": "Gold",
                            "customers": 21
                          }
                        ]
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "crm",
          "keys": "loyalty"
        },
        "x-scope": "crm:read"
      }
    },
    "/crm/customers/{id}/activity": {
      "get": {
        "operationId": "crm.customers.activity",
        "tags": [
          "crm"
        ],
        "summary": "Customer timeline",
        "description": "Latest orders, loyalty entries and support tickets for one customer, newest first.\n\nPermission: `crm.customers` or `crm.support` or `crm.loyalty`.\n\nScope: `crm:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "customer": {
                          "id": "66f1c2a9e4b0a1b2c3d4e506",
                          "name": "Ada Obi"
                        },
                        "events": [
                          {
                            "type": "loyalty",
                            "at": "2026-10-02T14:05:00.000Z",
                            "id": "66f1c2a9e4b0a1b2c3d4e508",
                            "title": "Earned 139 points",
                            "detail": "Earned on order ORD1790904240356987",
                            "balanceAfter": 459
                          },
                          {
                            "type": "order",
                            "at": "2026-10-02T14:05:00.000Z",
                            "id": "66f1c2a9e4b0a1b2c3d4e505",
                            "title": "Order ORD1790904240356987",
                            "detail": "confirmed, paid by cash",
                            "amount": 13975,
                            "store": "Main Street"
                          }
                        ]
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "crm",
          "keys": [
            "customers",
            "support",
            "loyalty"
          ]
        },
        "x-scope": "crm:read"
      }
    },
    "/hr/employees": {
      "get": {
        "operationId": "hr.employees.list",
        "tags": [
          "hr"
        ],
        "summary": "List employees",
        "description": "Permission: `hr.employees`.\n\nScope: `hr:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "department",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "designation",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "active",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e511",
                          "employeeNumber": "E-014",
                          "name": "Emma Obi",
                          "email": "emma@example.com",
                          "mobile": "08055556666",
                          "department": "Sales",
                          "designation": "Cashier",
                          "role": "Staff",
                          "unit": "Front desk",
                          "location": "Main Street",
                          "employmentType": "Full time",
                          "gender": "Female",
                          "reportingTo": "Jane Doe",
                          "active": true,
                          "joinedOn": "2025-03-01",
                          "probationEndsOn": "2025-06-01",
                          "contractEndsOn": null,
                          "createdAt": "2026-10-01T09:30:00.000Z",
                          "updatedAt": "2026-10-02T14:05:00.000Z"
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "hr",
          "keys": "employees"
        },
        "x-scope": "hr:read"
      }
    },
    "/hr/employees/{id}": {
      "get": {
        "operationId": "hr.employees.get",
        "tags": [
          "hr"
        ],
        "summary": "Get an employee",
        "description": "Includes salary, bank and pension details only when you have hr.payroll.\n\nPermission: `hr.employees`.\n\nScope: `hr:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e511",
                        "employeeNumber": "E-014",
                        "name": "Emma Obi",
                        "email": "emma@example.com",
                        "mobile": "08055556666",
                        "department": "Sales",
                        "designation": "Cashier",
                        "role": "Staff",
                        "unit": "Front desk",
                        "location": "Main Street",
                        "employmentType": "Full time",
                        "gender": "Female",
                        "reportingTo": "Jane Doe",
                        "active": true,
                        "joinedOn": "2025-03-01",
                        "probationEndsOn": "2025-06-01",
                        "contractEndsOn": null,
                        "createdAt": "2026-10-01T09:30:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z",
                        "address": "7 Broad Street",
                        "country": "Nigeria",
                        "state": "Lagos",
                        "language": "English",
                        "salutation": "Ms",
                        "maritalStatus": "Single",
                        "skills": "Customer service",
                        "note": "",
                        "salary": {
                          "level": 3,
                          "gross": 250000,
                          "basic": 180000,
                          "allowance": 50000,
                          "other": 20000,
                          "cycle": "monthly"
                        },
                        "bank": {
                          "name": "First Bank",
                          "accountNumber": "0123456789"
                        },
                        "pension": {
                          "administrator": "Stanbic IBTC Pension",
                          "number": "PEN100200300"
                        },
                        "taxNumber": "12345678-0001",
                        "nhfNumber": "NHF-55001"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "hr",
          "keys": "employees"
        },
        "x-scope": "hr:read"
      }
    },
    "/hr/departments": {
      "get": {
        "operationId": "hr.departments",
        "tags": [
          "hr"
        ],
        "summary": "Departments and head count",
        "description": "Departments set up in HR settings plus any used on employee records, with the number of employees in each.\n\nPermission: `hr.employees`.\n\nScope: `hr:read`.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "name": "Operations",
                          "employees": 4
                        },
                        {
                          "name": "Sales",
                          "employees": 9
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "hr",
          "keys": "employees"
        },
        "x-scope": "hr:read"
      }
    },
    "/hr/attendance": {
      "get": {
        "operationId": "hr.attendance.list",
        "tags": [
          "hr"
        ],
        "summary": "Attendance records",
        "description": "Permission: `hr.attendance`.\n\nScope: `hr:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          },
          {
            "name": "employeeId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          },
          {
            "name": "late",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e512",
                          "employeeId": "66f1c2a9e4b0a1b2c3d4e511",
                          "employeeNumber": "E-014",
                          "name": "Emma Obi",
                          "role": "Cashier",
                          "clockIn": "2026-10-02T07:58:00.000Z",
                          "clockOut": "2026-10-02T17:02:00.000Z",
                          "late": false,
                          "location": "Main Street",
                          "workday": "2026-10-02",
                          "createdAt": "2026-10-02T14:05:00.000Z"
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "hr",
          "keys": "attendance"
        },
        "x-scope": "hr:read"
      }
    },
    "/hr/leaves": {
      "get": {
        "operationId": "hr.leaves.list",
        "tags": [
          "hr"
        ],
        "summary": "Leave requests",
        "description": "Permission: `hr.leaves`.\n\nScope: `hr:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          },
          {
            "name": "employeeId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e513",
                          "employeeId": "66f1c2a9e4b0a1b2c3d4e511",
                          "employeeNumber": "E-014",
                          "name": "Emma Obi",
                          "type": "Annual leave",
                          "status": "1",
                          "startDate": "2026-11-03",
                          "endDate": "2026-11-07",
                          "duration": 5,
                          "paid": true,
                          "note": "Family trip",
                          "createdAt": "2026-10-02T14:05:00.000Z"
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "hr",
          "keys": "leaves"
        },
        "x-scope": "hr:read"
      }
    },
    "/hr/payroll": {
      "get": {
        "operationId": "hr.payroll.list",
        "tags": [
          "hr"
        ],
        "summary": "Payroll records (payslips)",
        "description": "Permission: `hr.payroll`.\n\nScope: `hr:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "employeeId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          },
          {
            "name": "department",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e514",
                          "employeeId": "66f1c2a9e4b0a1b2c3d4e511",
                          "employeeNumber": "E-014",
                          "name": "Emma Obi",
                          "designation": "Cashier",
                          "department": "Sales",
                          "payDate": "2026-09-30T00:00:00.000Z",
                          "payType": "month",
                          "basic": 180000,
                          "allowance": 50000,
                          "other": 20000,
                          "gross": 250000,
                          "net": 221500,
                          "deductions": {
                            "tax": 18500,
                            "pension": 10000
                          },
                          "attendanceDays": 21,
                          "totalDays": 22,
                          "unpaidLeaveDays": 0,
                          "latenessCount": 1,
                          "createdAt": "2026-10-02T14:05:00.000Z"
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "hr",
          "keys": "payroll"
        },
        "x-scope": "hr:read"
      }
    },
    "/hr/payroll/{id}": {
      "get": {
        "operationId": "hr.payroll.get",
        "tags": [
          "hr"
        ],
        "summary": "Get a payroll record",
        "description": "Permission: `hr.payroll`.\n\nScope: `hr:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e514",
                        "employeeId": "66f1c2a9e4b0a1b2c3d4e511",
                        "employeeNumber": "E-014",
                        "name": "Emma Obi",
                        "designation": "Cashier",
                        "department": "Sales",
                        "payDate": "2026-09-30T00:00:00.000Z",
                        "payType": "month",
                        "basic": 180000,
                        "allowance": 50000,
                        "other": 20000,
                        "gross": 250000,
                        "net": 221500,
                        "deductions": {
                          "tax": 18500,
                          "pension": 10000
                        },
                        "attendanceDays": 21,
                        "totalDays": 22,
                        "unpaidLeaveDays": 0,
                        "latenessCount": 1,
                        "createdAt": "2026-10-02T14:05:00.000Z"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "hr",
          "keys": "payroll"
        },
        "x-scope": "hr:read"
      }
    },
    "/finance/income": {
      "get": {
        "operationId": "finance.income.list",
        "tags": [
          "finance"
        ],
        "summary": "List income entries",
        "description": "Permission: `financial.finincome`.\n\nScope: `finance:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "Received",
                "Pending",
                "Cancelled"
              ]
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e520",
                          "createdAt": "2026-10-02T14:05:00.000Z",
                          "updatedAt": "2026-10-02T14:05:00.000Z",
                          "number": "INC-0042",
                          "date": "2026-10-02T14:05:00.000Z",
                          "reference": "POS-SALES-0210",
                          "description": "Daily POS sales",
                          "category": "Sales",
                          "source": "POS",
                          "amount": 845000,
                          "paymentMethod": "Cash",
                          "status": "Received",
                          "notes": ""
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "financial",
          "keys": "finincome"
        },
        "x-scope": "finance:read"
      }
    },
    "/finance/income/{id}": {
      "get": {
        "operationId": "finance.income.get",
        "tags": [
          "finance"
        ],
        "summary": "Get one of the income entries",
        "description": "Permission: `financial.finincome`.\n\nScope: `finance:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e520",
                        "createdAt": "2026-10-02T14:05:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z",
                        "number": "INC-0042",
                        "date": "2026-10-02T14:05:00.000Z",
                        "reference": "POS-SALES-0210",
                        "description": "Daily POS sales",
                        "category": "Sales",
                        "source": "POS",
                        "amount": 845000,
                        "paymentMethod": "Cash",
                        "status": "Received",
                        "notes": ""
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "financial",
          "keys": "finincome"
        },
        "x-scope": "finance:read"
      }
    },
    "/finance/expenses": {
      "get": {
        "operationId": "finance.expenses.list",
        "tags": [
          "finance"
        ],
        "summary": "List expenses",
        "description": "Permission: `financial.finexpenses`.\n\nScope: `finance:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "Paid",
                "Unpaid",
                "Partially Paid",
                "Cancelled"
              ]
            }
          },
          {
            "name": "vendorId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e521",
                          "createdAt": "2026-10-02T14:05:00.000Z",
                          "updatedAt": "2026-10-02T14:05:00.000Z",
                          "number": "EXP-0108",
                          "date": "2026-10-02T14:05:00.000Z",
                          "dueDate": "2026-10-16T00:00:00.000Z",
                          "reference": "INV-7781",
                          "description": "Generator diesel",
                          "category": "Utilities",
                          "vendor": {
                            "id": "66f1c2a9e4b0a1b2c3d4e522",
                            "name": "Total Energies"
                          },
                          "amount": 120000,
                          "paymentMethod": "Bank transfer",
                          "status": "Paid",
                          "notes": ""
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "financial",
          "keys": "finexpenses"
        },
        "x-scope": "finance:read"
      }
    },
    "/finance/expenses/{id}": {
      "get": {
        "operationId": "finance.expenses.get",
        "tags": [
          "finance"
        ],
        "summary": "Get one of the expenses",
        "description": "Permission: `financial.finexpenses`.\n\nScope: `finance:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e521",
                        "createdAt": "2026-10-02T14:05:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z",
                        "number": "EXP-0108",
                        "date": "2026-10-02T14:05:00.000Z",
                        "dueDate": "2026-10-16T00:00:00.000Z",
                        "reference": "INV-7781",
                        "description": "Generator diesel",
                        "category": "Utilities",
                        "vendor": {
                          "id": "66f1c2a9e4b0a1b2c3d4e522",
                          "name": "Total Energies"
                        },
                        "amount": 120000,
                        "paymentMethod": "Bank transfer",
                        "status": "Paid",
                        "notes": ""
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "financial",
          "keys": "finexpenses"
        },
        "x-scope": "finance:read"
      }
    },
    "/finance/vendors": {
      "get": {
        "operationId": "finance.vendors.list",
        "tags": [
          "finance"
        ],
        "summary": "List vendors",
        "description": "Permission: `financial.finvendors`.\n\nScope: `finance:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "Active",
                "Inactive"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e522",
                          "createdAt": "2026-10-01T09:30:00.000Z",
                          "updatedAt": "2026-10-02T14:05:00.000Z",
                          "number": "VEN-0007",
                          "code": "TOTAL",
                          "name": "Total Energies",
                          "company": "Total Energies Marketing Nigeria",
                          "email": "sales@total.example",
                          "phone": "01-2700000",
                          "address": "4 Adeola Odeku",
                          "city": "Lagos",
                          "state": "Lagos",
                          "contactPerson": "Musa Bello",
                          "openingBalance": 0,
                          "creditLimit": 1000000,
                          "paymentTerms": "Net 30",
                          "status": "Active"
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "financial",
          "keys": "finvendors"
        },
        "x-scope": "finance:read"
      }
    },
    "/finance/vendors/{id}": {
      "get": {
        "operationId": "finance.vendors.get",
        "tags": [
          "finance"
        ],
        "summary": "Get one of the vendors",
        "description": "Permission: `financial.finvendors`.\n\nScope: `finance:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e522",
                        "createdAt": "2026-10-01T09:30:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z",
                        "number": "VEN-0007",
                        "code": "TOTAL",
                        "name": "Total Energies",
                        "company": "Total Energies Marketing Nigeria",
                        "email": "sales@total.example",
                        "phone": "01-2700000",
                        "address": "4 Adeola Odeku",
                        "city": "Lagos",
                        "state": "Lagos",
                        "contactPerson": "Musa Bello",
                        "openingBalance": 0,
                        "creditLimit": 1000000,
                        "paymentTerms": "Net 30",
                        "status": "Active"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "financial",
          "keys": "finvendors"
        },
        "x-scope": "finance:read"
      }
    },
    "/finance/payables": {
      "get": {
        "operationId": "finance.payables.list",
        "tags": [
          "finance"
        ],
        "summary": "List payables (bills to pay)",
        "description": "Permission: `financial.finpayables`.\n\nScope: `finance:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "Unpaid",
                "Partially Paid",
                "Paid",
                "Overdue"
              ]
            }
          },
          {
            "name": "vendorId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e523",
                          "createdAt": "2026-10-01T09:30:00.000Z",
                          "updatedAt": "2026-10-02T14:05:00.000Z",
                          "number": "PAY-0031",
                          "date": "2026-10-01T09:30:00.000Z",
                          "dueDate": "2026-10-31T00:00:00.000Z",
                          "reference": "INV-7790",
                          "description": "Rice supply (200 bags)",
                          "vendor": {
                            "id": "66f1c2a9e4b0a1b2c3d4e522",
                            "name": "Total Energies"
                          },
                          "amount": 1040000,
                          "paid": 500000,
                          "balance": 540000,
                          "status": "Partially Paid",
                          "notes": ""
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "financial",
          "keys": "finpayables"
        },
        "x-scope": "finance:read"
      }
    },
    "/finance/payables/{id}": {
      "get": {
        "operationId": "finance.payables.get",
        "tags": [
          "finance"
        ],
        "summary": "Get one of the payables (bills to pay)",
        "description": "Permission: `financial.finpayables`.\n\nScope: `finance:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e523",
                        "createdAt": "2026-10-01T09:30:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z",
                        "number": "PAY-0031",
                        "date": "2026-10-01T09:30:00.000Z",
                        "dueDate": "2026-10-31T00:00:00.000Z",
                        "reference": "INV-7790",
                        "description": "Rice supply (200 bags)",
                        "vendor": {
                          "id": "66f1c2a9e4b0a1b2c3d4e522",
                          "name": "Total Energies"
                        },
                        "amount": 1040000,
                        "paid": 500000,
                        "balance": 540000,
                        "status": "Partially Paid",
                        "notes": ""
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "financial",
          "keys": "finpayables"
        },
        "x-scope": "finance:read"
      }
    },
    "/finance/receivables": {
      "get": {
        "operationId": "finance.receivables.list",
        "tags": [
          "finance"
        ],
        "summary": "List receivables (money owed to you)",
        "description": "Permission: `financial.finreceivables`.\n\nScope: `finance:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "Outstanding",
                "Partially Received",
                "Received",
                "Overdue"
              ]
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e524",
                          "createdAt": "2026-10-01T09:30:00.000Z",
                          "updatedAt": "2026-10-02T14:05:00.000Z",
                          "number": "REC-0012",
                          "date": "2026-10-01T09:30:00.000Z",
                          "dueDate": "2026-10-20T00:00:00.000Z",
                          "reference": "WHL-0009",
                          "description": "Wholesale order for Ade Foods",
                          "source": "Wholesale",
                          "amount": 650000,
                          "received": 300000,
                          "balance": 350000,
                          "status": "Partially Received",
                          "notes": ""
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "financial",
          "keys": "finreceivables"
        },
        "x-scope": "finance:read"
      }
    },
    "/finance/receivables/{id}": {
      "get": {
        "operationId": "finance.receivables.get",
        "tags": [
          "finance"
        ],
        "summary": "Get one of the receivables (money owed to you)",
        "description": "Permission: `financial.finreceivables`.\n\nScope: `finance:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e524",
                        "createdAt": "2026-10-01T09:30:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z",
                        "number": "REC-0012",
                        "date": "2026-10-01T09:30:00.000Z",
                        "dueDate": "2026-10-20T00:00:00.000Z",
                        "reference": "WHL-0009",
                        "description": "Wholesale order for Ade Foods",
                        "source": "Wholesale",
                        "amount": 650000,
                        "received": 300000,
                        "balance": 350000,
                        "status": "Partially Received",
                        "notes": ""
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "financial",
          "keys": "finreceivables"
        },
        "x-scope": "finance:read"
      }
    },
    "/finance/vendor-payments": {
      "get": {
        "operationId": "finance.vendor-payments.list",
        "tags": [
          "finance"
        ],
        "summary": "List payments to vendors",
        "description": "Permission: `financial.finpayments`.\n\nScope: `finance:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          },
          {
            "name": "vendorId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e525",
                          "createdAt": "2026-10-02T14:05:00.000Z",
                          "updatedAt": "2026-10-02T14:05:00.000Z",
                          "number": "VP-0019",
                          "date": "2026-10-02T14:05:00.000Z",
                          "reference": "TRF-55120",
                          "vendor": {
                            "id": "66f1c2a9e4b0a1b2c3d4e522",
                            "name": "Total Energies"
                          },
                          "amount": 500000,
                          "paymentMethod": "Bank transfer",
                          "description": "Part payment for INV-7790",
                          "payableId": "66f1c2a9e4b0a1b2c3d4e523",
                          "notes": ""
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "financial",
          "keys": "finpayments"
        },
        "x-scope": "finance:read"
      }
    },
    "/finance/vendor-payments/{id}": {
      "get": {
        "operationId": "finance.vendor-payments.get",
        "tags": [
          "finance"
        ],
        "summary": "Get one of the payments to vendors",
        "description": "Permission: `financial.finpayments`.\n\nScope: `finance:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e525",
                        "createdAt": "2026-10-02T14:05:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z",
                        "number": "VP-0019",
                        "date": "2026-10-02T14:05:00.000Z",
                        "reference": "TRF-55120",
                        "vendor": {
                          "id": "66f1c2a9e4b0a1b2c3d4e522",
                          "name": "Total Energies"
                        },
                        "amount": 500000,
                        "paymentMethod": "Bank transfer",
                        "description": "Part payment for INV-7790",
                        "payableId": "66f1c2a9e4b0a1b2c3d4e523",
                        "notes": ""
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "financial",
          "keys": "finpayments"
        },
        "x-scope": "finance:read"
      }
    },
    "/finance/receivable-payments": {
      "get": {
        "operationId": "finance.receivable-payments.list",
        "tags": [
          "finance"
        ],
        "summary": "List payments received",
        "description": "Permission: `financial.finpayments`.\n\nScope: `finance:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e526",
                          "createdAt": "2026-10-02T14:05:00.000Z",
                          "updatedAt": "2026-10-02T14:05:00.000Z",
                          "number": "RP-0008",
                          "date": "2026-10-02T14:05:00.000Z",
                          "reference": "TRF-88101",
                          "receivableId": "66f1c2a9e4b0a1b2c3d4e524",
                          "amount": 300000,
                          "paymentMethod": "Bank transfer",
                          "description": "Ade Foods part payment",
                          "notes": ""
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "financial",
          "keys": "finpayments"
        },
        "x-scope": "finance:read"
      }
    },
    "/finance/receivable-payments/{id}": {
      "get": {
        "operationId": "finance.receivable-payments.get",
        "tags": [
          "finance"
        ],
        "summary": "Get one of the payments received",
        "description": "Permission: `financial.finpayments`.\n\nScope: `finance:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e526",
                        "createdAt": "2026-10-02T14:05:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z",
                        "number": "RP-0008",
                        "date": "2026-10-02T14:05:00.000Z",
                        "reference": "TRF-88101",
                        "receivableId": "66f1c2a9e4b0a1b2c3d4e524",
                        "amount": 300000,
                        "paymentMethod": "Bank transfer",
                        "description": "Ade Foods part payment",
                        "notes": ""
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "financial",
          "keys": "finpayments"
        },
        "x-scope": "finance:read"
      }
    },
    "/finance/transactions": {
      "get": {
        "operationId": "finance.transactions.list",
        "tags": [
          "finance"
        ],
        "summary": "List ledger transactions",
        "description": "Permission: `financial.fintransactions`.\n\nScope: `finance:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "Income",
                "Expense",
                "Vendor Payment",
                "Receivable",
                "Receivable Payment",
                "Payable",
                "Adjustment"
              ]
            }
          },
          {
            "name": "vendorId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e527",
                          "createdAt": "2026-10-02T14:05:00.000Z",
                          "updatedAt": "2026-10-02T14:05:00.000Z",
                          "number": "TXN-1201",
                          "date": "2026-10-02T14:05:00.000Z",
                          "reference": "EXP-0108",
                          "type": "Expense",
                          "description": "Generator diesel",
                          "category": "Utilities",
                          "vendor": {
                            "id": "66f1c2a9e4b0a1b2c3d4e522",
                            "name": "Total Energies"
                          },
                          "debit": 120000,
                          "credit": 0,
                          "amount": 120000,
                          "balance": 3240000,
                          "paymentMethod": "Bank transfer",
                          "status": "Posted",
                          "sourceId": "66f1c2a9e4b0a1b2c3d4e521"
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "financial",
          "keys": "fintransactions"
        },
        "x-scope": "finance:read"
      }
    },
    "/finance/transactions/{id}": {
      "get": {
        "operationId": "finance.transactions.get",
        "tags": [
          "finance"
        ],
        "summary": "Get one of the ledger transactions",
        "description": "Permission: `financial.fintransactions`.\n\nScope: `finance:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e527",
                        "createdAt": "2026-10-02T14:05:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z",
                        "number": "TXN-1201",
                        "date": "2026-10-02T14:05:00.000Z",
                        "reference": "EXP-0108",
                        "type": "Expense",
                        "description": "Generator diesel",
                        "category": "Utilities",
                        "vendor": {
                          "id": "66f1c2a9e4b0a1b2c3d4e522",
                          "name": "Total Energies"
                        },
                        "debit": 120000,
                        "credit": 0,
                        "amount": 120000,
                        "balance": 3240000,
                        "paymentMethod": "Bank transfer",
                        "status": "Posted",
                        "sourceId": "66f1c2a9e4b0a1b2c3d4e521"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "financial",
          "keys": "fintransactions"
        },
        "x-scope": "finance:read"
      }
    },
    "/finance/budgets": {
      "get": {
        "operationId": "finance.budgets.list",
        "tags": [
          "finance"
        ],
        "summary": "List budgets",
        "description": "Permission: `financial.finbudgets`.\n\nScope: `finance:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e528",
                          "createdAt": "2026-10-01T09:30:00.000Z",
                          "updatedAt": "2026-10-02T14:05:00.000Z",
                          "number": "BUD-2026-Q4",
                          "name": "Q4 utilities",
                          "category": "Utilities",
                          "period": "quarterly",
                          "startDate": "2026-10-01T00:00:00.000Z",
                          "endDate": "2026-12-31T00:00:00.000Z",
                          "amount": 600000,
                          "notes": ""
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "financial",
          "keys": "finbudgets"
        },
        "x-scope": "finance:read"
      }
    },
    "/finance/budgets/{id}": {
      "get": {
        "operationId": "finance.budgets.get",
        "tags": [
          "finance"
        ],
        "summary": "Get one of the budgets",
        "description": "Permission: `financial.finbudgets`.\n\nScope: `finance:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e528",
                        "createdAt": "2026-10-01T09:30:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z",
                        "number": "BUD-2026-Q4",
                        "name": "Q4 utilities",
                        "category": "Utilities",
                        "period": "quarterly",
                        "startDate": "2026-10-01T00:00:00.000Z",
                        "endDate": "2026-12-31T00:00:00.000Z",
                        "amount": 600000,
                        "notes": ""
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "financial",
          "keys": "finbudgets"
        },
        "x-scope": "finance:read"
      }
    },
    "/finance/categories": {
      "get": {
        "operationId": "finance.categories.list",
        "tags": [
          "finance"
        ],
        "summary": "List categories",
        "description": "Permission: `financial.fincategories`.\n\nScope: `finance:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "Active",
                "Inactive"
              ]
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "Income",
                "Expense"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e529",
                          "createdAt": "2026-10-01T09:30:00.000Z",
                          "updatedAt": "2026-10-02T14:05:00.000Z",
                          "number": "CAT-0004",
                          "name": "Utilities",
                          "type": "Expense",
                          "description": "Power, water, internet",
                          "status": "Active"
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "financial",
          "keys": "fincategories"
        },
        "x-scope": "finance:read"
      }
    },
    "/finance/categories/{id}": {
      "get": {
        "operationId": "finance.categories.get",
        "tags": [
          "finance"
        ],
        "summary": "Get one of the categories",
        "description": "Permission: `financial.fincategories`.\n\nScope: `finance:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e529",
                        "createdAt": "2026-10-01T09:30:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z",
                        "number": "CAT-0004",
                        "name": "Utilities",
                        "type": "Expense",
                        "description": "Power, water, internet",
                        "status": "Active"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "financial",
          "keys": "fincategories"
        },
        "x-scope": "finance:read"
      }
    },
    "/finance/summary": {
      "get": {
        "operationId": "finance.summary",
        "tags": [
          "finance"
        ],
        "summary": "Income, expenses and balances for a period",
        "description": "Totals of received income and non-cancelled expenses in the period (default: this month), plus what is still owed to and by you today.\n\nPermission: `financial.finreports` or `financial.findashboard`.\n\nScope: `finance:read`.",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "period": {
                          "from": "2026-10-01",
                          "to": "2026-10-31"
                        },
                        "income": {
                          "total": 1200000,
                          "count": 14
                        },
                        "expenses": {
                          "total": 830000,
                          "count": 22
                        },
                        "net": 370000,
                        "payablesOutstanding": {
                          "total": 150000,
                          "count": 3
                        },
                        "receivablesOutstanding": {
                          "total": 90000,
                          "count": 2
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "financial",
          "keys": [
            "finreports",
            "findashboard"
          ]
        },
        "x-scope": "finance:read"
      }
    },
    "/projects": {
      "get": {
        "operationId": "projects.list",
        "tags": [
          "projects"
        ],
        "summary": "List your projects",
        "description": "Permission: `project.project`.\n\nScope: `projects:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "new",
                "started",
                "ongoing",
                "in_review",
                "completed"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e515",
                          "title": "Open the Ikeja branch",
                          "status": "ongoing",
                          "startsAt": "2026-09-01T00:00:00.000Z",
                          "endsAt": "2026-12-01T00:00:00.000Z",
                          "owner": {
                            "id": "66f1c2a9e4b0a1b2c3d4e502",
                            "name": "Jane Doe"
                          },
                          "members": [
                            {
                              "id": "66f1c2a9e4b0a1b2c3d4e502",
                              "name": "Jane Doe",
                              "email": "jane@example.com"
                            }
                          ],
                          "tasks": {
                            "total": 12,
                            "completed": 5
                          },
                          "createdAt": "2026-10-01T09:30:00.000Z",
                          "updatedAt": "2026-10-02T14:05:00.000Z"
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "project",
          "keys": "project"
        },
        "x-scope": "projects:read"
      }
    },
    "/projects/{id}": {
      "get": {
        "operationId": "projects.get",
        "tags": [
          "projects"
        ],
        "summary": "Get a project",
        "description": "Permission: `project.project`.\n\nScope: `projects:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e515",
                        "title": "Open the Ikeja branch",
                        "status": "ongoing",
                        "startsAt": "2026-09-01T00:00:00.000Z",
                        "endsAt": "2026-12-01T00:00:00.000Z",
                        "owner": {
                          "id": "66f1c2a9e4b0a1b2c3d4e502",
                          "name": "Jane Doe"
                        },
                        "members": [
                          {
                            "id": "66f1c2a9e4b0a1b2c3d4e502",
                            "name": "Jane Doe",
                            "email": "jane@example.com"
                          }
                        ],
                        "tasks": {
                          "total": 12,
                          "completed": 5,
                          "byStatus": {
                            "new": 2,
                            "started": 1,
                            "ongoing": 3,
                            "in_review": 1,
                            "completed": 5
                          }
                        },
                        "createdAt": "2026-10-01T09:30:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "project",
          "keys": "project"
        },
        "x-scope": "projects:read"
      }
    },
    "/projects/{id}/tasks": {
      "get": {
        "operationId": "projects.tasks",
        "tags": [
          "projects"
        ],
        "summary": "List a project's tasks",
        "description": "Permission: `project.project` or `project.alltask`.\n\nScope: `projects:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "new",
                "started",
                "ongoing",
                "in_review",
                "completed"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e516",
                          "projectId": "66f1c2a9e4b0a1b2c3d4e515",
                          "title": "Order shelving",
                          "type": "task",
                          "status": "started",
                          "startDate": "2026-10-01T00:00:00.000Z",
                          "endDate": "2026-10-10T00:00:00.000Z",
                          "budget": 450000,
                          "owner": {
                            "id": "66f1c2a9e4b0a1b2c3d4e502",
                            "name": "Jane Doe"
                          },
                          "assignedTo": [
                            {
                              "id": "66f1c2a9e4b0a1b2c3d4e502",
                              "name": "Jane Doe",
                              "email": "jane@example.com"
                            }
                          ],
                          "members": [
                            {
                              "id": "66f1c2a9e4b0a1b2c3d4e502",
                              "name": "Jane Doe",
                              "email": "jane@example.com"
                            }
                          ],
                          "workflow": "Purchase approval",
                          "createdAt": "2026-10-01T09:30:00.000Z",
                          "updatedAt": "2026-10-02T14:05:00.000Z"
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": [
          {
            "plugin": "project",
            "keys": [
              "project",
              "alltask"
            ]
          }
        ],
        "x-scope": "projects:read"
      }
    },
    "/tasks": {
      "get": {
        "operationId": "tasks.list",
        "tags": [
          "projects"
        ],
        "summary": "List your tasks",
        "description": "Permission: `project.alltask`.\n\nScope: `projects:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
            },
            "description": "Comma-separated fields; prefix with - for descending. Example: -createdAt,name"
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 500,
              "description": "Comma-separated fields to return. Example: id,name,status"
            },
            "description": "Comma-separated fields to return. Example: id,name,status"
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "new",
                "started",
                "ongoing",
                "in_review",
                "completed"
              ]
            }
          },
          {
            "name": "projectId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e516",
                          "projectId": "66f1c2a9e4b0a1b2c3d4e515",
                          "title": "Order shelving",
                          "type": "task",
                          "status": "started",
                          "startDate": "2026-10-01T00:00:00.000Z",
                          "endDate": "2026-10-10T00:00:00.000Z",
                          "budget": 450000,
                          "owner": {
                            "id": "66f1c2a9e4b0a1b2c3d4e502",
                            "name": "Jane Doe"
                          },
                          "assignedTo": [
                            {
                              "id": "66f1c2a9e4b0a1b2c3d4e502",
                              "name": "Jane Doe",
                              "email": "jane@example.com"
                            }
                          ],
                          "members": [
                            {
                              "id": "66f1c2a9e4b0a1b2c3d4e502",
                              "name": "Jane Doe",
                              "email": "jane@example.com"
                            }
                          ],
                          "workflow": "Purchase approval",
                          "createdAt": "2026-10-01T09:30:00.000Z",
                          "updatedAt": "2026-10-02T14:05:00.000Z"
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "project",
          "keys": "alltask"
        },
        "x-scope": "projects:read"
      }
    },
    "/tasks/{id}": {
      "get": {
        "operationId": "tasks.get",
        "tags": [
          "projects"
        ],
        "summary": "Get a task",
        "description": "Permission: `project.alltask` or `project.project`.\n\nScope: `projects:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "id": "66f1c2a9e4b0a1b2c3d4e516",
                        "projectId": "66f1c2a9e4b0a1b2c3d4e515",
                        "title": "Order shelving",
                        "type": "task",
                        "status": "started",
                        "startDate": "2026-10-01T00:00:00.000Z",
                        "endDate": "2026-10-10T00:00:00.000Z",
                        "budget": 450000,
                        "owner": {
                          "id": "66f1c2a9e4b0a1b2c3d4e502",
                          "name": "Jane Doe"
                        },
                        "assignedTo": [
                          {
                            "id": "66f1c2a9e4b0a1b2c3d4e502",
                            "name": "Jane Doe",
                            "email": "jane@example.com"
                          }
                        ],
                        "members": [
                          {
                            "id": "66f1c2a9e4b0a1b2c3d4e502",
                            "name": "Jane Doe",
                            "email": "jane@example.com"
                          }
                        ],
                        "workflow": "Purchase approval",
                        "createdAt": "2026-10-01T09:30:00.000Z",
                        "updatedAt": "2026-10-02T14:05:00.000Z",
                        "description": "Get three quotes and order shelving for the new branch.",
                        "approvals": [
                          {
                            "title": "Manager approval",
                            "approved": true,
                            "by": "Jane Doe",
                            "at": "2026-10-02T14:05:00.000Z"
                          }
                        ]
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "project",
          "keys": [
            "alltask",
            "project"
          ]
        },
        "x-scope": "projects:read"
      }
    },
    "/reports/sales": {
      "get": {
        "operationId": "reports.sales",
        "tags": [
          "reports"
        ],
        "summary": "Sales summary",
        "description": "Totals for the period plus a breakdown by day, week or month and by payment method.\n\nPermission: `pos.report` or `pos.sales`.\n\nScope: `reports:read`.",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          },
          {
            "name": "store",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 30,
              "pattern": "^(all|current|[a-f0-9]{24})$",
              "description": "\"all\" or a store id (needs pos.stores). Default: your store."
            },
            "description": "\"all\" or a store id (needs pos.stores). Default: your store."
          },
          {
            "name": "groupBy",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "day",
                "week",
                "month"
              ],
              "default": "day"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "period": {
                          "from": "2026-09-01T00:00:00.000Z",
                          "to": "2026-09-30T23:59:59.999Z"
                        },
                        "totals": {
                          "orders": 412,
                          "revenue": 5384000,
                          "tax": 375600,
                          "discounts": 21000,
                          "averageOrder": 13067.96,
                          "itemsSold": 1530
                        },
                        "series": [
                          {
                            "period": "2026-09-01",
                            "orders": 14,
                            "revenue": 182500
                          },
                          {
                            "period": "2026-09-02",
                            "orders": 11,
                            "revenue": 151200
                          }
                        ],
                        "byPaymentMethod": [
                          {
                            "method": "cash",
                            "orders": 260,
                            "revenue": 3105000
                          },
                          {
                            "method": "transfer",
                            "orders": 152,
                            "revenue": 2279000
                          }
                        ],
                        "byStatus": [
                          {
                            "status": "completed",
                            "orders": 398
                          },
                          {
                            "status": "cancelled",
                            "orders": 14
                          }
                        ]
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": [
            "report",
            "sales"
          ]
        },
        "x-scope": "reports:read"
      }
    },
    "/reports/top-products": {
      "get": {
        "operationId": "reports.products",
        "tags": [
          "reports"
        ],
        "summary": "Best-selling products",
        "description": "Permission: `pos.report` or `pos.sales`.\n\nScope: `reports:read`.",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          },
          {
            "name": "store",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 30,
              "pattern": "^(all|current|[a-f0-9]{24})$",
              "description": "\"all\" or a store id (needs pos.stores). Default: your store."
            },
            "description": "\"all\" or a store id (needs pos.stores). Default: your store."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 10
            }
          },
          {
            "name": "by",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "revenue",
                "quantity"
              ],
              "default": "revenue"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "productId": "66f1c2a9e4b0a1b2c3d4e503",
                          "name": "Rice 5kg",
                          "sku": "RICE5",
                          "quantity": 186,
                          "revenue": 1209000,
                          "orders": 141
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": [
            "report",
            "sales"
          ]
        },
        "x-scope": "reports:read"
      }
    },
    "/reports/staff": {
      "get": {
        "operationId": "reports.staff",
        "tags": [
          "reports"
        ],
        "summary": "Sales by staff member",
        "description": "Permission: `pos.report` or `pos.sales`.\n\nScope: `reports:read`.",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          },
          {
            "name": "store",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 30,
              "pattern": "^(all|current|[a-f0-9]{24})$",
              "description": "\"all\" or a store id (needs pos.stores). Default: your store."
            },
            "description": "\"all\" or a store id (needs pos.stores). Default: your store."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "staffId": "66f1c2a9e4b0a1b2c3d4e502",
                          "name": "Jane Doe",
                          "orders": 210,
                          "revenue": 2744000,
                          "averageOrder": 13066.67
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": [
            "report",
            "sales"
          ]
        },
        "x-scope": "reports:read"
      }
    },
    "/admin/activity-logs": {
      "get": {
        "operationId": "admin.activity",
        "tags": [
          "admin"
        ],
        "summary": "Activity log",
        "description": "Who did what and when, across all modules (including API calls, marked with source \"api\"). Sensitive values in before/after snapshots are redacted.\n\nPermission: `admin.admin` or `logs/general.activity` or `logs/general.logs`.\n\nScope: `admin:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100,
              "description": "Search text."
            },
            "description": "Search text."
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          },
          {
            "name": "module",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          },
          {
            "name": "action",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          },
          {
            "name": "userId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{24}$"
            }
          },
          {
            "name": "resource",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 60
            }
          },
          {
            "name": "resourceId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 60
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "success",
                "failure"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e518",
                          "at": "2026-10-02T14:05:00.000Z",
                          "module": "pos",
                          "action": "update",
                          "resource": "pos_product",
                          "resourceId": "66f1c2a9e4b0a1b2c3d4e503",
                          "description": "Updated product Rice 5kg (API, token)",
                          "status": "success",
                          "user": {
                            "id": "66f1c2a9e4b0a1b2c3d4e502",
                            "name": "Jane Doe"
                          },
                          "source": "api",
                          "ip": "102.89.1.20",
                          "method": "PATCH",
                          "path": "/api/v1/products/66f1c2a9e4b0a1b2c3d4e503",
                          "requestId": "106213322361546",
                          "before": {
                            "name": "Rice 5 kg"
                          },
                          "after": {
                            "name": "Rice 5kg"
                          }
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": [
          {
            "plugin": "admin",
            "keys": "admin"
          },
          {
            "plugin": "logs/general",
            "keys": [
              "activity",
              "logs"
            ]
          }
        ],
        "x-scope": "admin:read"
      }
    },
    "/admin/permissions": {
      "get": {
        "operationId": "admin.permissions",
        "tags": [
          "admin"
        ],
        "summary": "Permission catalogue",
        "description": "Every menu and permission key the app knows, as used by PUT /users/{id}/permissions.\n\nPermission: `admin.permission` or `admin.admin`.\n\nScope: `admin:read`.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "menu": "pos",
                          "name": "POS",
                          "permissions": {
                            "pos": "View POS",
                            "products": "View Products"
                          }
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": [
          {
            "plugin": "admin",
            "keys": [
              "permission",
              "admin"
            ]
          }
        ],
        "x-scope": "admin:read"
      }
    },
    "/admin/settings": {
      "get": {
        "operationId": "admin.settings",
        "tags": [
          "admin"
        ],
        "summary": "Main settings (no secrets)",
        "description": "Permission: `pos.setting` or `pos.onlinestore`.\n\nScope: `admin:read`.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "vatRate": 7.5,
                        "currencySymbol": "NGN",
                        "lowStockAlert": true,
                        "enableOnlineOrder": true,
                        "minOrderAmount": 0,
                        "orderPrepTime": 20,
                        "notificationEmail": "owner@example.com",
                        "messaging": {
                          "emailConfigured": true,
                          "fromEmail": "shop@example.com",
                          "fromName": "Main Street",
                          "smsConfigured": false,
                          "smsProvider": "",
                          "sendOrderConfirmation": true,
                          "enableSmsNotifications": false,
                          "sendWelcomeEmails": false
                        },
                        "api": {
                          "keys": 2,
                          "activeKeys": 1
                        },
                        "webhooks": 1,
                        "maintenance": {
                          "enabled": false
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": [
          {
            "plugin": "pos",
            "keys": [
              "setting",
              "onlinestore"
            ]
          }
        ],
        "x-scope": "admin:read"
      }
    },
    "/notifications": {
      "get": {
        "operationId": "notifications.list",
        "tags": [
          "notifications"
        ],
        "summary": "List your notifications",
        "description": "Any signed-in user.\n\nScope: `notifications:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "unread",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "66f1c2a9e4b0a1b2c3d4e530",
                          "type": "stock",
                          "icon": "fa-box",
                          "title": "Low stock: Rice 5kg",
                          "message": "Only 4 left at Main Street.",
                          "link": "/inventory",
                          "category": "inventory",
                          "event": "inventory.low_stock",
                          "priority": "high",
                          "read": false,
                          "readAt": null,
                          "from": "System",
                          "createdAt": "2026-10-02T14:05:00.000Z"
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": null,
        "x-scope": "notifications:read"
      }
    },
    "/notifications/{id}/read": {
      "post": {
        "operationId": "notifications.read",
        "tags": [
          "notifications"
        ],
        "summary": "Mark a notification as read",
        "description": "Any signed-in user.\n\nScope: `notifications:write`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^([a-f0-9]{24}|all)$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "updated": 1
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": null,
        "x-scope": "notifications:write"
      }
    },
    "/event-types": {
      "get": {
        "operationId": "webhooks.eventTypes",
        "tags": [
          "webhooks"
        ],
        "summary": "Events you can subscribe to",
        "description": "Any signed-in user.\n\nScope: `admin:read`.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "name": "order.created",
                          "group": "Orders",
                          "description": "A sale or online order was placed."
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": null,
        "x-scope": "admin:read"
      }
    },
    "/webhooks": {
      "get": {
        "operationId": "webhooks.list",
        "tags": [
          "webhooks"
        ],
        "summary": "List webhooks",
        "description": "Permission: `pos.onlinestore`.\n\nScope: `admin:read`.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "webhookId": "wh_3f9c0a1b2c3d4e5f",
                          "name": "Accounting sync",
                          "url": "https://example.com/hooks/pos",
                          "events": [
                            "order.created",
                            "refund.created"
                          ],
                          "event": "order.created",
                          "status": "active",
                          "retryCount": 3,
                          "signed": true,
                          "secretHint": "whsec_…9f0e",
                          "lastDeliveryAt": "2026-10-02T14:05:00.000Z",
                          "lastStatus": "success",
                          "lastError": null,
                          "consecutiveFailures": 0,
                          "createdAt": "2026-10-01T09:30:00.000Z"
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": "onlinestore"
        },
        "x-scope": "admin:read"
      },
      "post": {
        "operationId": "webhooks.create",
        "tags": [
          "webhooks"
        ],
        "summary": "Create a webhook",
        "description": "The response includes `secret` once. Keep it to check signatures; afterwards only a hint is shown.\n\nPermission: `pos.onlinestore`.\n\nScope: `admin:write`.",
        "parameters": [],
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "webhookId": "wh_3f9c0a1b2c3d4e5f",
                        "name": "Accounting sync",
                        "url": "https://example.com/hooks/pos",
                        "events": [
                          "order.created",
                          "refund.created"
                        ],
                        "event": "order.created",
                        "status": "active",
                        "retryCount": 3,
                        "signed": true,
                        "secretHint": "whsec_…9f0e",
                        "lastDeliveryAt": "2026-10-02T14:05:00.000Z",
                        "lastStatus": "success",
                        "lastError": null,
                        "consecutiveFailures": 0,
                        "createdAt": "2026-10-01T09:30:00.000Z",
                        "secret": "whsec_<secret shown once>"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": "onlinestore"
        },
        "x-scope": "admin:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "url": {
                    "type": "string",
                    "maxLength": 500,
                    "example": "https://example.com/hooks/pos"
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 60
                    },
                    "minItems": 1,
                    "maxItems": 50,
                    "description": "Event names from GET /event-types, or [\"*\"] for all events.",
                    "example": [
                      "order.created",
                      "order.updated"
                    ]
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "active",
                      "inactive"
                    ],
                    "default": "active"
                  },
                  "retryCount": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 10,
                    "default": 3
                  }
                },
                "required": [
                  "name",
                  "url",
                  "events"
                ]
              }
            }
          }
        }
      }
    },
    "/webhooks/{id}": {
      "get": {
        "operationId": "webhooks.get",
        "tags": [
          "webhooks"
        ],
        "summary": "Get a webhook",
        "description": "Permission: `pos.onlinestore`.\n\nScope: `admin:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^wh_[a-f0-9]{8,32}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "webhookId": "wh_3f9c0a1b2c3d4e5f",
                        "name": "Accounting sync",
                        "url": "https://example.com/hooks/pos",
                        "events": [
                          "order.created",
                          "refund.created"
                        ],
                        "event": "order.created",
                        "status": "active",
                        "retryCount": 3,
                        "signed": true,
                        "secretHint": "whsec_…9f0e",
                        "lastDeliveryAt": "2026-10-02T14:05:00.000Z",
                        "lastStatus": "success",
                        "lastError": null,
                        "consecutiveFailures": 0,
                        "createdAt": "2026-10-01T09:30:00.000Z"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": "onlinestore"
        },
        "x-scope": "admin:read"
      },
      "patch": {
        "operationId": "webhooks.update",
        "tags": [
          "webhooks"
        ],
        "summary": "Change a webhook",
        "description": "Permission: `pos.onlinestore`.\n\nScope: `admin:write`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^wh_[a-f0-9]{8,32}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "webhookId": "wh_3f9c0a1b2c3d4e5f",
                        "name": "Accounting sync",
                        "url": "https://example.com/hooks/pos",
                        "events": [
                          "order.created",
                          "refund.created"
                        ],
                        "event": "order.created",
                        "status": "active",
                        "retryCount": 3,
                        "signed": true,
                        "secretHint": "whsec_…9f0e",
                        "lastDeliveryAt": "2026-10-02T14:05:00.000Z",
                        "lastStatus": "success",
                        "lastError": null,
                        "consecutiveFailures": 0,
                        "createdAt": "2026-10-01T09:30:00.000Z"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": "onlinestore"
        },
        "x-scope": "admin:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "url": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 60
                    },
                    "minItems": 1,
                    "maxItems": 50,
                    "description": "Event names from GET /event-types, or [\"*\"] for all events.",
                    "example": [
                      "order.created",
                      "order.updated"
                    ]
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "active",
                      "inactive"
                    ]
                  },
                  "retryCount": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 10
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "webhooks.delete",
        "tags": [
          "webhooks"
        ],
        "summary": "Delete a webhook",
        "description": "Permission: `pos.onlinestore`.\n\nScope: `admin:write`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^wh_[a-f0-9]{8,32}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "webhookId": "wh_3f9c0a1b2c3d4e5f"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": "onlinestore"
        },
        "x-scope": "admin:write"
      }
    },
    "/webhooks/{id}/test": {
      "post": {
        "operationId": "webhooks.test",
        "tags": [
          "webhooks"
        ],
        "summary": "Send a test event",
        "description": "Sends a `webhook.test` event to this webhook now (even if it is inactive) and returns the result.\n\nPermission: `pos.onlinestore`.\n\nScope: `admin:write`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^wh_[a-f0-9]{8,32}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "deliveryId": "whd_5b1e9a0c7d2f4e6a8b3c1d0e",
                        "webhookId": "wh_3f9c0a1b2c3d4e5f",
                        "webhookName": "Accounting sync",
                        "url": "https://example.com/hooks/pos",
                        "event": "webhook.test",
                        "eventId": "evt_9b2f1c0d4e5a6b7c8d9e0f1a",
                        "status": "success",
                        "test": true,
                        "signed": true,
                        "attempts": 1,
                        "maxAttempts": 4,
                        "nextAttemptAt": null,
                        "lastAttemptAt": "2026-10-02T14:05:00.000Z",
                        "deliveredAt": "2026-10-02T14:05:00.000Z",
                        "responseStatus": 200,
                        "durationMs": 182,
                        "error": "",
                        "createdAt": "2026-10-02T14:05:00.000Z",
                        "payload": {
                          "id": "evt_9b2f1c0d4e5a6b7c8d9e0f1a",
                          "event": "order.created",
                          "createdAt": "2026-10-02T14:05:00.000Z",
                          "source": "api",
                          "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                          "actor": {
                            "type": "user",
                            "id": "66f1c2a9e4b0a1b2c3d4e502",
                            "name": "Jane Doe"
                          },
                          "data": {
                            "order": {
                              "id": "66f1c2a9e4b0a1b2c3d4e505",
                              "orderNumber": "ORD1790904240356987",
                              "status": "confirmed",
                              "total": {
                                "amount": 13975,
                                "currency": "NGN"
                              }
                            }
                          }
                        },
                        "responseBody": "{\"received\":true}",
                        "history": [
                          {
                            "at": "2026-10-02T14:05:00.000Z",
                            "status": "success",
                            "responseStatus": 200,
                            "durationMs": 182,
                            "error": ""
                          }
                        ]
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": "onlinestore"
        },
        "x-scope": "admin:write"
      }
    },
    "/webhooks/{id}/secret": {
      "post": {
        "operationId": "webhooks.secret",
        "tags": [
          "webhooks"
        ],
        "summary": "Create a new signing secret",
        "description": "Replaces the signing secret; the new one is returned once. Deliveries from now on are signed with it.\n\nPermission: `pos.onlinestore`.\n\nScope: `admin:write`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^wh_[a-f0-9]{8,32}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "webhookId": "wh_3f9c0a1b2c3d4e5f",
                        "secret": "whsec_<secret shown once>"
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": "onlinestore"
        },
        "x-scope": "admin:write"
      }
    },
    "/webhook-deliveries": {
      "get": {
        "operationId": "webhooks.deliveries",
        "tags": [
          "webhooks"
        ],
        "summary": "Delivery log",
        "description": "Newest first. Each delivery is one event sent to one webhook, with its attempts.\n\nPermission: `pos.onlinestore`.\n\nScope: `admin:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "webhookId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          },
          {
            "name": "event",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 60
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "retrying",
                "success",
                "failed",
                "cancelled"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "deliveryId": "whd_5b1e9a0c7d2f4e6a8b3c1d0e",
                          "webhookId": "wh_3f9c0a1b2c3d4e5f",
                          "webhookName": "Accounting sync",
                          "url": "https://example.com/hooks/pos",
                          "event": "order.created",
                          "eventId": "evt_9b2f1c0d4e5a6b7c8d9e0f1a",
                          "status": "success",
                          "test": false,
                          "signed": true,
                          "attempts": 1,
                          "maxAttempts": 4,
                          "nextAttemptAt": null,
                          "lastAttemptAt": "2026-10-02T14:05:00.000Z",
                          "deliveredAt": "2026-10-02T14:05:00.000Z",
                          "responseStatus": 200,
                          "durationMs": 182,
                          "error": "",
                          "createdAt": "2026-10-02T14:05:00.000Z"
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": "onlinestore"
        },
        "x-scope": "admin:read"
      }
    },
    "/webhook-deliveries/{id}": {
      "get": {
        "operationId": "webhooks.delivery",
        "tags": [
          "webhooks"
        ],
        "summary": "Get a delivery",
        "description": "Includes the payload that was sent, the start of the response, and every attempt.\n\nPermission: `pos.onlinestore`.\n\nScope: `admin:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^whd_[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "deliveryId": "whd_5b1e9a0c7d2f4e6a8b3c1d0e",
                        "webhookId": "wh_3f9c0a1b2c3d4e5f",
                        "webhookName": "Accounting sync",
                        "url": "https://example.com/hooks/pos",
                        "event": "order.created",
                        "eventId": "evt_9b2f1c0d4e5a6b7c8d9e0f1a",
                        "status": "success",
                        "test": false,
                        "signed": true,
                        "attempts": 1,
                        "maxAttempts": 4,
                        "nextAttemptAt": null,
                        "lastAttemptAt": "2026-10-02T14:05:00.000Z",
                        "deliveredAt": "2026-10-02T14:05:00.000Z",
                        "responseStatus": 200,
                        "durationMs": 182,
                        "error": "",
                        "createdAt": "2026-10-02T14:05:00.000Z",
                        "payload": {
                          "id": "evt_9b2f1c0d4e5a6b7c8d9e0f1a",
                          "event": "order.created",
                          "createdAt": "2026-10-02T14:05:00.000Z",
                          "source": "api",
                          "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                          "actor": {
                            "type": "user",
                            "id": "66f1c2a9e4b0a1b2c3d4e502",
                            "name": "Jane Doe"
                          },
                          "data": {
                            "order": {
                              "id": "66f1c2a9e4b0a1b2c3d4e505",
                              "orderNumber": "ORD1790904240356987",
                              "status": "confirmed",
                              "total": {
                                "amount": 13975,
                                "currency": "NGN"
                              }
                            }
                          }
                        },
                        "responseBody": "{\"received\":true}",
                        "history": [
                          {
                            "at": "2026-10-02T14:05:00.000Z",
                            "status": "success",
                            "responseStatus": 200,
                            "durationMs": 182,
                            "error": ""
                          }
                        ]
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": "onlinestore"
        },
        "x-scope": "admin:read"
      }
    },
    "/webhook-deliveries/{id}/retry": {
      "post": {
        "operationId": "webhooks.retry",
        "tags": [
          "webhooks"
        ],
        "summary": "Send a delivery again",
        "description": "Permission: `pos.onlinestore`.\n\nScope: `admin:write`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^whd_[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "deliveryId": "whd_5b1e9a0c7d2f4e6a8b3c1d0e",
                        "webhookId": "wh_3f9c0a1b2c3d4e5f",
                        "webhookName": "Accounting sync",
                        "url": "https://example.com/hooks/pos",
                        "event": "order.created",
                        "eventId": "evt_9b2f1c0d4e5a6b7c8d9e0f1a",
                        "status": "success",
                        "test": false,
                        "signed": true,
                        "attempts": 1,
                        "maxAttempts": 4,
                        "nextAttemptAt": null,
                        "lastAttemptAt": "2026-10-02T14:05:00.000Z",
                        "deliveredAt": "2026-10-02T14:05:00.000Z",
                        "responseStatus": 200,
                        "durationMs": 182,
                        "error": "",
                        "createdAt": "2026-10-02T14:05:00.000Z",
                        "payload": {
                          "id": "evt_9b2f1c0d4e5a6b7c8d9e0f1a",
                          "event": "order.created",
                          "createdAt": "2026-10-02T14:05:00.000Z",
                          "source": "api",
                          "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                          "actor": {
                            "type": "user",
                            "id": "66f1c2a9e4b0a1b2c3d4e502",
                            "name": "Jane Doe"
                          },
                          "data": {
                            "order": {
                              "id": "66f1c2a9e4b0a1b2c3d4e505",
                              "orderNumber": "ORD1790904240356987",
                              "status": "confirmed",
                              "total": {
                                "amount": 13975,
                                "currency": "NGN"
                              }
                            }
                          }
                        },
                        "responseBody": "{\"received\":true}",
                        "history": [
                          {
                            "at": "2026-10-02T14:05:00.000Z",
                            "status": "success",
                            "responseStatus": 200,
                            "durationMs": 182,
                            "error": ""
                          }
                        ]
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": "onlinestore"
        },
        "x-scope": "admin:write"
      }
    },
    "/events": {
      "get": {
        "operationId": "events.list",
        "tags": [
          "webhooks"
        ],
        "summary": "Event history",
        "description": "Everything that happened (orders, payments, customers, stock, HR…), newest first, with the data sent to webhooks.\n\nPermission: `pos.onlinestore`.\n\nScope: `admin:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "Page number (starts at 1)."
            },
            "description": "Page number (starts at 1)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "description": "Items per page (max 100)."
            },
            "description": "Items per page (max 100)."
          },
          {
            "name": "event",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 60
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or after this date (YYYY-MM-DD)."
            },
            "description": "Only items on or after this date (YYYY-MM-DD)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
            },
            "description": "Only items on or before this date (YYYY-MM-DD, whole day included)."
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "id": "evt_9b2f1c0d4e5a6b7c8d9e0f1a",
                          "event": "order.created",
                          "source": "api",
                          "occurredAt": "2026-10-02T14:05:00.000Z",
                          "storeId": "66f1c2a9e4b0a1b2c3d4e501",
                          "actor": {
                            "type": "user",
                            "id": "66f1c2a9e4b0a1b2c3d4e502",
                            "name": "Jane Doe"
                          },
                          "webhooks": 1,
                          "data": {
                            "order": {
                              "id": "66f1c2a9e4b0a1b2c3d4e505",
                              "orderNumber": "ORD1790904240356987",
                              "status": "confirmed",
                              "total": {
                                "amount": 13975,
                                "currency": "NGN"
                              }
                            }
                          }
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": {
          "plugin": "pos",
          "keys": "onlinestore"
        },
        "x-scope": "admin:read"
      }
    },
    "/ai/ask": {
      "post": {
        "operationId": "ai.ask",
        "tags": [
          "ai"
        ],
        "summary": "Ask a question",
        "description": "`status` is `answered`, `no_match` (with `suggestions`) or `denied` (the user or key may not see that data). Answers can include `facts` (headline figures), a `table` and a `chart`; money values are plain numbers in the store currency (`currency`).\n\nAny signed-in user.\n\nScope: `ai:read`.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": {
                        "status": "answered",
                        "question": "How much did we sell this month?",
                        "intent": "sales.summary",
                        "area": "sales",
                        "areaLabel": "Sales",
                        "period": {
                          "label": "this month",
                          "from": "2026-10-01T00:00:00.000Z",
                          "to": "2026-10-02T23:59:59.999Z"
                        },
                        "store": null,
                        "currency": "NGN",
                        "corrections": [],
                        "link": {
                          "href": "/pos/report",
                          "label": "Sales report"
                        },
                        "answer": "You sold NGN845,000 this month at Main Street from 64 orders (average NGN13,203.13). That is +12.5% compared with the previous period.",
                        "facts": [
                          {
                            "label": "Revenue",
                            "value": 845000,
                            "type": "money"
                          },
                          {
                            "label": "Orders",
                            "value": 64,
                            "type": "number"
                          },
                          {
                            "label": "Average order",
                            "value": 13203.13,
                            "type": "money"
                          },
                          {
                            "label": "Items sold",
                            "value": 211,
                            "type": "number"
                          }
                        ],
                        "chart": {
                          "type": "line",
                          "labels": [
                            "2026-10-01",
                            "2026-10-02"
                          ],
                          "series": [
                            {
                              "label": "Revenue",
                              "data": [
                                402000,
                                443000
                              ]
                            }
                          ],
                          "format": "money"
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": null,
        "x-scope": "ai:read",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "question": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 300,
                    "example": "How much did we sell this month?"
                  }
                },
                "required": [
                  "question"
                ]
              }
            }
          }
        }
      }
    },
    "/ai/suggestions": {
      "get": {
        "operationId": "ai.suggestions",
        "tags": [
          "ai"
        ],
        "summary": "Questions you can ask",
        "description": "Example questions grouped by area, limited to the data this user (and key) may see.\n\nAny signed-in user.\n\nScope: `ai:read`.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "example": [
                        {
                          "area": "sales",
                          "label": "Sales",
                          "questions": [
                            "How much did we sell this month?"
                          ]
                        },
                        {
                          "area": "inventory",
                          "label": "Inventory",
                          "questions": [
                            "Which products are out of stock?"
                          ]
                        }
                      ]
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "x-permission": null,
        "x-scope": "ai:read"
      }
    }
  }
}
