{ "openapi": "3.0.3", "info": { "title": "blueQ API", "version": "v1", "description": "REST API for blueQ workspaces. Authenticate with your workspace API key as a Bearer token. Live keys (bq_live_...): Business plans have read-only access (60 req/min); Pro plans have full read/write access (300 req/min). Sandbox keys (bq_test_...) are available on every plan, work on a separate sandbox copy of the workspace with sample data, and have full read/write access (60 req/min). The X-API-Mode response header says which one answered.", "contact": { "name": "blueQ support", "url": "https://www.blueq.app/api/doc/v1" } }, "servers": [ { "url": "https://www.blueq.app/api/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Account", "description": "The workspace that owns the API key, its plan, API access level and rate limit." }, { "name": "Clients", "description": "Customers you invoice and sell to. Creating a client counts against the plan's client limit." }, { "name": "Suppliers", "description": "Vendors you buy stock and services from. Deleting a supplier archives it." }, { "name": "Products", "description": "Catalogue items: sellable products, services, menu items and stock (inventory) items, with optional variations (sizes). Stock quantity changes go through /stock/adjustments." }, { "name": "Product categories", "description": "Groups for catalogue items. Each category has a kind: product, service or menu." }, { "name": "Stock", "description": "Quantities on hand for product-kind items, the stock movement history, and adjustments. Adjustments made through the API are applied immediately and recorded in the stock history as approved, with \"API\" as the requester." }, { "name": "Invoices", "description": "Quotes (proformas), invoices and receipts. A new invoice starts as a proforma; confirming it turns it into an invoice, and payments turn it into a receipt. Totals (taxes, discount) are recalculated on every change. Creating an invoice counts against the plan's monthly invoice limit." }, { "name": "Payments", "description": "Every payment received against invoices, across the workspace. Read-only here — record, edit or delete payments through /invoices/{id}/payments so invoice balances stay in sync." }, { "name": "Sales", "description": "Counter and walk-in sales recorded outside of invoices (multi-item carts with optional payments, discount and taxes). Creating a sale counts against the plan's monthly sales limit." }, { "name": "Expenditure", "description": "Business expenses with line items, supplier, and payments. Lines whose expense type is set to add stock (or that reference a stock product) update inventory automatically, exactly as in the app. Creating an expense counts against the plan's monthly expenditure limit." }, { "name": "Orders (production)", "description": "Production orders created from invoices. Each invoice line becomes a job; each job holds one or more orders that move through pending → in_progress → completed (or cancelled). Orders can carry processes (e.g. \"Design\", \"Print\", \"Laminate\") that are ticked off as work progresses." }, { "name": "Taxes", "description": "Tax rates (levies and VAT). Levies are charged on the taxable amount; VAT is charged on the taxable amount plus levies. Group rates into tax groups to apply them to invoices and sales." }, { "name": "Tax groups", "description": "Named sets of taxes (called \"tax instances\" in the app), e.g. \"Standard VAT + levies\" or \"VAT exempt\". One group is the default for new invoices and sales." }, { "name": "Branches", "description": "Shop locations. Every workspace has at least one branch; one is the default. Creating a branch counts against the plan's branch limit." }, { "name": "Users (team)", "description": "Team members with access to the workspace. New users are always invited by email and set their own password; passwords are never accepted or returned by the API. The workspace owner cannot be changed or removed here." }, { "name": "Roles & privileges", "description": "Roles decide what each team member can do. Every module has four privileges: view, add, update, delete. Built-in roles can be narrowed (except super_admin); custom roles can be created and deleted." }, { "name": "Recipes", "description": "Recipes (bill of materials) for food and production businesses: ingredients drawn from Cost-of-Sale stock items, optional base recipes, yield, and live cost. Available when the Recipes feature is enabled for the business type. Sizes/variations and cost add-ons are managed in the app and returned read-only." }, { "name": "Online stores", "description": "Public online stores (storefronts) and which catalogue products each one sells. Payment gateway secrets are never returned. Deleting a store takes it offline; orders are kept." }, { "name": "Store & walk-in orders", "description": "Orders placed on online stores (channel \"online\") and at the POS till (channel \"walkin\"). Orders are created by customers at checkout or by cashiers at the till; the API reads them and marks paid orders as picked up / delivered." }, { "name": "Delivery zones", "description": "Delivery fees for online stores. Each zone has a price and the towns it covers; at checkout the cheapest zone covering the customer's town is used." }, { "name": "Store customer accounts", "description": "Shopper accounts created on your online stores. Customers register themselves at checkout; the API can list, correct and remove accounts. Passwords are never exposed." }, { "name": "POS (point of sale)", "description": "The walk-in till: register settings, cashier sessions (\"accounts\") that are opened, closed and reviewed, and walk-in sales. Sales are recorded against the cashier's open session, deduct stock, and share order numbers with the linked online store. Paystack payments need the customer present at the till and are not available through the API." }, { "name": "Reports", "description": "The same datasets as the Reports area and scheduled report e-mails: run any built-in report with filters, read its summary and chart series, and manage saved custom reports (several datasets with chosen columns). Rows come back both as raw arrays (matching `columns`) and as keyed objects; money columns are numbers." } ], "paths": { "/me": { "get": { "tags": [ "Account" ], "summary": "Get the current workspace", "operationId": "meGet", "description": "Use this to test a key. Returns the workspace, plan, access level and rate limit.", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Me" } } }, "example": { "ok": true, "data": { "mode": "live", "workspace_id": 1042, "live_workspace_id": 1042, "business_name": "Kente Prints Ltd", "business_type": "printing", "owner": { "name": "Ama Mensah", "email": "ama@kenteprints.com", "phone": "0244000000" }, "plan": "Pro", "api_access": "full", "rate_limit_per_minute": 300, "key_prefix": "bq_live_3f9a1c2e", "limits": { "clients": null, "invoices": null, "sales": null, "branches": 5 }, "usage": { "clients": 182, "invoices": 940, "sales": 2210, "branches": 2 } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/clients": { "get": { "tags": [ "Clients" ], "summary": "List clients", "operationId": "clientsGet", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "q", "in": "query", "description": "Search name, phone or email.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Created on/after (YYYY-MM-DD).", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Created on/before.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "name, -created_at (default).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Clients" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "ok": true, "data": [ { "id": 2381, "name": "Akosua Boateng", "contact_person": "Kwame Boateng", "phone": "0244123456", "email": "akosua@example.com", "gender": "female", "date_of_birth": "1992-04-18", "balance": 0, "created_at": "2026-09-14 10:22:05" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Clients" ], "summary": "Create a client", "operationId": "clientsPost", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Client or company name.", "example": "Akosua Boateng" }, "contact_person": { "type": "string", "description": "Contact person (for companies).", "example": "Kwame Boateng" }, "phone": { "type": "string", "description": "Phone number. Must be unique in the workspace.", "example": "0244123456" }, "email": { "type": "string", "description": "Email address. Must be unique in the workspace.", "example": "akosua@example.com" }, "gender": { "type": "string", "description": "\"male\" or \"female\".", "example": "female" }, "date_of_birth": { "type": "string", "format": "date", "description": "Date of birth (YYYY-MM-DD).", "example": "1992-04-18" } }, "required": [ "name", "phone" ] }, "example": { "name": "Akosua Boateng", "contact_person": "Kwame Boateng", "phone": "0244123456", "email": "akosua@example.com", "gender": "female", "date_of_birth": "1992-04-18" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Clients" } } }, "example": { "ok": true, "data": { "id": 2381, "name": "Akosua Boateng", "contact_person": "Kwame Boateng", "phone": "0244123456", "email": "akosua@example.com", "gender": "female", "date_of_birth": "1992-04-18", "balance": 0, "created_at": "2026-09-14 10:22:05" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/clients/{id}": { "get": { "tags": [ "Clients" ], "summary": "Get a client", "operationId": "clientsGetId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Clients ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Clients" } } }, "example": { "ok": true, "data": { "id": 2381, "name": "Akosua Boateng", "contact_person": "Kwame Boateng", "phone": "0244123456", "email": "akosua@example.com", "gender": "female", "date_of_birth": "1992-04-18", "balance": 0, "created_at": "2026-09-14 10:22:05" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "tags": [ "Clients" ], "summary": "Update a client", "operationId": "clientsPatchId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Clients ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Client or company name.", "example": "Akosua Boateng" }, "contact_person": { "type": "string", "description": "Contact person (for companies).", "example": "Kwame Boateng" }, "phone": { "type": "string", "description": "Phone number. Must be unique in the workspace.", "example": "0244123456" }, "email": { "type": "string", "description": "Email address. Must be unique in the workspace.", "example": "akosua@example.com" }, "gender": { "type": "string", "description": "\"male\" or \"female\".", "example": "female" }, "date_of_birth": { "type": "string", "format": "date", "description": "Date of birth (YYYY-MM-DD).", "example": "1992-04-18" } } }, "example": { "name": "Akosua Boateng", "contact_person": "Kwame Boateng", "phone": "0244123456", "email": "akosua@example.com", "gender": "female", "date_of_birth": "1992-04-18" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Clients" } } }, "example": { "ok": true, "data": { "id": 2381, "name": "Akosua Boateng", "contact_person": "Kwame Boateng", "phone": "0244123456", "email": "akosua@example.com", "gender": "female", "date_of_birth": "1992-04-18", "balance": 0, "created_at": "2026-09-14 10:22:05" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Clients" ], "summary": "Delete a client", "operationId": "clientsDeleteId", "description": "Refused with 409 if the client has invoices.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Clients ID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/clients/{id}/invoices": { "get": { "tags": [ "Clients" ], "summary": "List a client's invoices", "operationId": "clientsGetIdInvoices", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Clients ID.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Clients" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "ok": true, "data": [ { "id": 2381, "name": "Akosua Boateng", "contact_person": "Kwame Boateng", "phone": "0244123456", "email": "akosua@example.com", "gender": "female", "date_of_birth": "1992-04-18", "balance": 0, "created_at": "2026-09-14 10:22:05" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/clients/{id}/payments": { "get": { "tags": [ "Clients" ], "summary": "List a client's payments", "operationId": "clientsGetIdPayments", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Clients ID.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Clients" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "ok": true, "data": [ { "id": 2381, "name": "Akosua Boateng", "contact_person": "Kwame Boateng", "phone": "0244123456", "email": "akosua@example.com", "gender": "female", "date_of_birth": "1992-04-18", "balance": 0, "created_at": "2026-09-14 10:22:05" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/suppliers": { "get": { "tags": [ "Suppliers" ], "summary": "List suppliers", "operationId": "suppliersGet", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "q", "in": "query", "description": "Search name, phone or email.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "name, -created_at (default).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Suppliers" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "ok": true, "data": [ { "id": 57, "name": "Accra Paper Mills", "phone": "0302123456", "email": "sales@accrapaper.com", "notes": "Delivers on Tuesdays.", "created_at": "2026-08-02 09:12:44" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Suppliers" ], "summary": "Create a supplier", "operationId": "suppliersPost", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Supplier name.", "example": "Accra Paper Mills" }, "phone": { "type": "string", "description": "Phone number.", "example": "0302123456" }, "email": { "type": "string", "description": "Email address.", "example": "sales@accrapaper.com" }, "notes": { "type": "string", "description": "Internal notes.", "example": "Delivers on Tuesdays." } }, "required": [ "name" ] }, "example": { "name": "Accra Paper Mills", "phone": "0302123456", "email": "sales@accrapaper.com", "notes": "Delivers on Tuesdays." } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Suppliers" } } }, "example": { "ok": true, "data": { "id": 57, "name": "Accra Paper Mills", "phone": "0302123456", "email": "sales@accrapaper.com", "notes": "Delivers on Tuesdays.", "created_at": "2026-08-02 09:12:44" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/suppliers/{id}": { "get": { "tags": [ "Suppliers" ], "summary": "Get a supplier", "operationId": "suppliersGetId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Suppliers ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Suppliers" } } }, "example": { "ok": true, "data": { "id": 57, "name": "Accra Paper Mills", "phone": "0302123456", "email": "sales@accrapaper.com", "notes": "Delivers on Tuesdays.", "created_at": "2026-08-02 09:12:44" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "tags": [ "Suppliers" ], "summary": "Update a supplier", "operationId": "suppliersPatchId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Suppliers ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Supplier name.", "example": "Accra Paper Mills" }, "phone": { "type": "string", "description": "Phone number.", "example": "0302123456" }, "email": { "type": "string", "description": "Email address.", "example": "sales@accrapaper.com" }, "notes": { "type": "string", "description": "Internal notes.", "example": "Delivers on Tuesdays." } } }, "example": { "name": "Accra Paper Mills", "phone": "0302123456", "email": "sales@accrapaper.com", "notes": "Delivers on Tuesdays." } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Suppliers" } } }, "example": { "ok": true, "data": { "id": 57, "name": "Accra Paper Mills", "phone": "0302123456", "email": "sales@accrapaper.com", "notes": "Delivers on Tuesdays.", "created_at": "2026-08-02 09:12:44" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Suppliers" ], "summary": "Archive a supplier", "operationId": "suppliersDeleteId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Suppliers ID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/products": { "get": { "tags": [ "Products" ], "summary": "List products", "operationId": "productsGet", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "q", "in": "query", "description": "Search name or description.", "schema": { "type": "string" } }, { "name": "category_id", "in": "query", "description": "Filter by category.", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "description": "product, service or menu.", "schema": { "type": "string" } }, { "name": "sellable", "in": "query", "description": "true for catalogue items, false for stock items.", "schema": { "type": "string" } }, { "name": "low_stock", "in": "query", "description": "true to list items at or below reorder level.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "name, price, -created_at (default).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Products" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "ok": true, "data": [ { "id": 812, "name": "A2 Flyer (glossy)", "description": "Full-colour, 150gsm", "price": 2.5, "category_id": 14, "kind": "product", "sellable": true, "active": true, "unit": "pcs", "stock_qty": 500, "reorder_level": 50, "expiry_date": null, "supplier_id": 57, "supplier_cost": 1.1, "variations": [ { "id": 813, "label": "Pack of 100", "price": 220, "stock_qty": 20 } ], "created_at": "2026-07-20 15:40:11" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Products" ], "summary": "Create a product", "operationId": "productsPost", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Item name.", "example": "A2 Flyer (glossy)" }, "description": { "type": "string", "description": "Description shown on invoices and the store.", "example": "Full-colour, 150gsm" }, "price": { "type": "number", "description": "Selling price.", "example": 2.5 }, "category_id": { "type": "integer", "description": "Product category ID.", "example": 14 }, "sellable": { "type": "boolean", "description": "true = catalogue item you sell; false = stock/inventory item.", "example": true }, "active": { "type": "boolean", "description": "Whether the item is active.", "example": true }, "unit": { "type": "string", "description": "Stock unit, e.g. pcs, kg, l, m.", "example": "pcs" }, "stock_qty": { "type": "number", "description": "Quantity on hand. Set on create only; use /stock/adjustments afterwards.", "example": 500 }, "reorder_level": { "type": "number", "description": "Low-stock warning level (inventory items).", "example": 50 }, "expiry_date": { "type": "string", "format": "date", "description": "Expiry date (inventory items)." }, "supplier_id": { "type": "integer", "description": "Default supplier ID.", "example": 57 }, "supplier_cost": { "type": "number", "description": "Cost price from the supplier.", "example": 1.1 }, "variations": { "type": "array", "items": { "type": "object" }, "description": "Sizes/options: [{id, label, price, stock_qty}]. Send on create to add variations.", "example": [ { "id": 813, "label": "Pack of 100", "price": 220, "stock_qty": 20 } ] } }, "required": [ "name", "price", "category_id" ] }, "example": { "name": "A2 Flyer (glossy)", "description": "Full-colour, 150gsm", "price": 2.5, "category_id": 14, "sellable": true, "active": true, "unit": "pcs", "stock_qty": 500, "reorder_level": 50, "expiry_date": null, "supplier_id": 57, "supplier_cost": 1.1, "variations": [ { "id": 813, "label": "Pack of 100", "price": 220, "stock_qty": 20 } ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Products" } } }, "example": { "ok": true, "data": { "id": 812, "name": "A2 Flyer (glossy)", "description": "Full-colour, 150gsm", "price": 2.5, "category_id": 14, "kind": "product", "sellable": true, "active": true, "unit": "pcs", "stock_qty": 500, "reorder_level": 50, "expiry_date": null, "supplier_id": 57, "supplier_cost": 1.1, "variations": [ { "id": 813, "label": "Pack of 100", "price": 220, "stock_qty": 20 } ], "created_at": "2026-07-20 15:40:11" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/products/{id}": { "get": { "tags": [ "Products" ], "summary": "Get a product", "operationId": "productsGetId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Products ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Products" } } }, "example": { "ok": true, "data": { "id": 812, "name": "A2 Flyer (glossy)", "description": "Full-colour, 150gsm", "price": 2.5, "category_id": 14, "kind": "product", "sellable": true, "active": true, "unit": "pcs", "stock_qty": 500, "reorder_level": 50, "expiry_date": null, "supplier_id": 57, "supplier_cost": 1.1, "variations": [ { "id": 813, "label": "Pack of 100", "price": 220, "stock_qty": 20 } ], "created_at": "2026-07-20 15:40:11" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "tags": [ "Products" ], "summary": "Update a product", "operationId": "productsPatchId", "description": "stock_qty and variations are ignored here. Use /stock/adjustments to change quantities.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Products ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Item name.", "example": "A2 Flyer (glossy)" }, "description": { "type": "string", "description": "Description shown on invoices and the store.", "example": "Full-colour, 150gsm" }, "price": { "type": "number", "description": "Selling price.", "example": 2.5 }, "category_id": { "type": "integer", "description": "Product category ID.", "example": 14 }, "sellable": { "type": "boolean", "description": "true = catalogue item you sell; false = stock/inventory item.", "example": true }, "active": { "type": "boolean", "description": "Whether the item is active.", "example": true }, "unit": { "type": "string", "description": "Stock unit, e.g. pcs, kg, l, m.", "example": "pcs" }, "stock_qty": { "type": "number", "description": "Quantity on hand. Set on create only; use /stock/adjustments afterwards.", "example": 500 }, "reorder_level": { "type": "number", "description": "Low-stock warning level (inventory items).", "example": 50 }, "expiry_date": { "type": "string", "format": "date", "description": "Expiry date (inventory items)." }, "supplier_id": { "type": "integer", "description": "Default supplier ID.", "example": 57 }, "supplier_cost": { "type": "number", "description": "Cost price from the supplier.", "example": 1.1 }, "variations": { "type": "array", "items": { "type": "object" }, "description": "Sizes/options: [{id, label, price, stock_qty}]. Send on create to add variations.", "example": [ { "id": 813, "label": "Pack of 100", "price": 220, "stock_qty": 20 } ] } } }, "example": { "name": "A2 Flyer (glossy)", "description": "Full-colour, 150gsm", "price": 2.5, "category_id": 14, "sellable": true, "active": true, "unit": "pcs", "stock_qty": 500, "reorder_level": 50, "expiry_date": null, "supplier_id": 57, "supplier_cost": 1.1, "variations": [ { "id": 813, "label": "Pack of 100", "price": 220, "stock_qty": 20 } ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Products" } } }, "example": { "ok": true, "data": { "id": 812, "name": "A2 Flyer (glossy)", "description": "Full-colour, 150gsm", "price": 2.5, "category_id": 14, "kind": "product", "sellable": true, "active": true, "unit": "pcs", "stock_qty": 500, "reorder_level": 50, "expiry_date": null, "supplier_id": 57, "supplier_cost": 1.1, "variations": [ { "id": 813, "label": "Pack of 100", "price": 220, "stock_qty": 20 } ], "created_at": "2026-07-20 15:40:11" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Products" ], "summary": "Delete a product", "operationId": "productsDeleteId", "description": "Deletes the item, its variations and its store links.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Products ID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/product-categories": { "get": { "tags": [ "Product categories" ], "summary": "List categories", "operationId": "productCategoriesGet", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "q", "in": "query", "description": "Search by name.", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "description": "product, service or menu.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCategories" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "ok": true, "data": [ { "id": 14, "name": "Banners", "kind": "product", "store_visible": true, "product_count": 12 } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Product categories" ], "summary": "Create a category", "operationId": "productCategoriesPost", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Category name.", "example": "Banners" }, "kind": { "type": "string", "description": "\"product\", \"service\" or \"menu\".", "example": "product" }, "store_visible": { "type": "boolean", "description": "Shown on the online store.", "example": true } }, "required": [ "name" ] }, "example": { "name": "Banners", "kind": "product", "store_visible": true } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ProductCategories" } } }, "example": { "ok": true, "data": { "id": 14, "name": "Banners", "kind": "product", "store_visible": true, "product_count": 12 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/product-categories/{id}": { "get": { "tags": [ "Product categories" ], "summary": "Get a category", "operationId": "productCategoriesGetId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Product categories ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ProductCategories" } } }, "example": { "ok": true, "data": { "id": 14, "name": "Banners", "kind": "product", "store_visible": true, "product_count": 12 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "tags": [ "Product categories" ], "summary": "Update a category", "operationId": "productCategoriesPatchId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Product categories ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Category name.", "example": "Banners" }, "kind": { "type": "string", "description": "\"product\", \"service\" or \"menu\".", "example": "product" }, "store_visible": { "type": "boolean", "description": "Shown on the online store.", "example": true } } }, "example": { "name": "Banners", "kind": "product", "store_visible": true } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ProductCategories" } } }, "example": { "ok": true, "data": { "id": 14, "name": "Banners", "kind": "product", "store_visible": true, "product_count": 12 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Product categories" ], "summary": "Delete a category", "operationId": "productCategoriesDeleteId", "description": "Refused with 409 while products are still in the category.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Product categories ID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/stock": { "get": { "tags": [ "Stock" ], "summary": "List stock levels", "operationId": "stockGet", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "q", "in": "query", "description": "Search item name.", "schema": { "type": "string" } }, { "name": "low_stock", "in": "query", "description": "true to list only items at or below reorder level.", "schema": { "type": "string" } }, { "name": "sellable", "in": "query", "description": "true/false.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Stock" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "ok": true, "data": [ { "product_id": 812, "name": "A2 Flyer paper", "unit": "pcs", "stock_qty": 480, "reorder_level": 50, "low_stock": false, "sellable": false, "unit_cost": 1.1, "stock_value": 528 } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/stock/movements": { "get": { "tags": [ "Stock" ], "summary": "List stock movements", "operationId": "stockGetMovements", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "product_id", "in": "query", "description": "Filter by product.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "pending, approved or rejected.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "On/after date.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "On/before date.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/StockMovement" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "ok": true, "data": [ { "id": 3301, "product_id": 812, "name": "A2 Flyer paper", "type": "add", "reason": null, "qty": 100, "qty_before": 380, "qty_after": 480, "status": "approved", "note": "Delivery from Accra Paper Mills", "requested_by": "API", "requested_at": "2026-10-02 08:15:00" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/stock/adjustments": { "post": { "tags": [ "Stock" ], "summary": "Adjust stock", "operationId": "stockPostAdjustments", "description": "Subtracting more than is on hand returns 422.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "integer", "description": "Product to adjust (must be a product-kind item).", "example": 812 }, "direction": { "type": "string", "description": "\"add\" or \"subtract\".", "example": "add" }, "qty": { "type": "number", "description": "Quantity to add or remove (greater than 0).", "example": 100 }, "reason": { "type": "string", "description": "For subtract: expired, broken or obsolete." }, "note": { "type": "string", "description": "Note for the stock history.", "example": "Delivery from Accra Paper Mills" } }, "required": [ "product_id", "direction", "qty" ] }, "example": { "product_id": 812, "direction": "add", "qty": 100, "reason": null, "note": "Delivery from Accra Paper Mills" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/StockMovement" } } }, "example": { "ok": true, "data": { "id": 3301, "product_id": 812, "name": "A2 Flyer paper", "type": "add", "reason": null, "qty": 100, "qty_before": 380, "qty_after": 480, "status": "approved", "note": "Delivery from Accra Paper Mills", "requested_by": "API", "requested_at": "2026-10-02 08:15:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/stock/{id}": { "get": { "tags": [ "Stock" ], "summary": "Get stock for a product", "operationId": "stockGetId", "description": "Includes the 20 most recent movements as \"movements\".", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Stock ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Stock" } } }, "example": { "ok": true, "data": { "product_id": 812, "name": "A2 Flyer paper", "unit": "pcs", "stock_qty": 480, "reorder_level": 50, "low_stock": false, "sellable": false, "unit_cost": 1.1, "stock_value": 528 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/invoices": { "get": { "tags": [ "Invoices" ], "summary": "List invoices", "operationId": "invoicesGet", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "q", "in": "query", "description": "Search number or title.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "open, completed, discarded, or all (default excludes discarded).", "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "proforma, invoice or receipt.", "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "description": "Only this client.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Invoice date on/after.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Invoice date on/before.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "date, total, number, -created_at (default).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoices" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "ok": true, "data": [ { "id": "66f1c2a9e4b1d", "number": "0042-37-1026", "title": "Branded T-shirts — October order", "client_id": 2381, "type": "invoice", "status": "open", "confirmed": true, "date": "2026-10-08", "due_date": "2026-10-22", "tax_group_id": 1, "discount_type": "percent", "discount_value": 5, "subtotal": 1200, "discount": 60, "tax_total": 199.5, "total": 1339.5, "paid": 500, "balance_due": 839.5, "orders_created": false, "public_url": "https://blueq.app/link/invoice/66f1c2a9e4b1d", "created_at": "2026-10-08 09:14:00", "items": [ { "id": 9811, "product_id": 57, "name": "Round-neck T-shirt (L)", "description": "Navy, 2-colour print front", "qty": 40, "unit_price": 30, "amount": 1200 } ] } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Invoices" ], "summary": "Create an invoice", "operationId": "invoicesPost", "description": "Pass items[] to add lines in the same call. Set \"confirm\": true to confirm it straight away.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Invoice title / subject.", "example": "Branded T-shirts — October order" }, "client_id": { "type": "integer", "description": "Client the invoice is billed to.", "example": 2381 }, "date": { "type": "string", "format": "date", "description": "Invoice date (YYYY-MM-DD).", "example": "2026-10-08" }, "due_date": { "type": "string", "format": "date", "description": "Payment due / quote expiry date.", "example": "2026-10-22" }, "tax_group_id": { "type": "integer", "description": "Tax group applied (see /tax-groups). Omit for the default group.", "example": 1 }, "discount_type": { "type": "string", "description": "\"amount\" or \"percent\".", "example": "percent" }, "discount_value": { "type": "number", "description": "Discount amount or percentage.", "example": 5 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceItem" }, "description": "Line items (detail view and create).", "example": [] } } }, "example": { "title": "Branded T-shirts — October order", "client_id": 2381, "date": "2026-10-08", "due_date": "2026-10-22", "tax_group_id": 1, "discount_type": "percent", "discount_value": 5, "items": [ { "product_id": 57, "name": "Round-neck T-shirt (L)", "description": "Navy, 2-colour print front", "qty": 40, "unit_price": 30 } ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Invoices" } } }, "example": { "ok": true, "data": { "id": "66f1c2a9e4b1d", "number": "0042-37-1026", "title": "Branded T-shirts — October order", "client_id": 2381, "type": "invoice", "status": "open", "confirmed": true, "date": "2026-10-08", "due_date": "2026-10-22", "tax_group_id": 1, "discount_type": "percent", "discount_value": 5, "subtotal": 1200, "discount": 60, "tax_total": 199.5, "total": 1339.5, "paid": 500, "balance_due": 839.5, "orders_created": false, "public_url": "https://blueq.app/link/invoice/66f1c2a9e4b1d", "created_at": "2026-10-08 09:14:00", "items": [ { "id": 9811, "product_id": 57, "name": "Round-neck T-shirt (L)", "description": "Navy, 2-colour print front", "qty": 40, "unit_price": 30, "amount": 1200 } ] } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{id}": { "get": { "tags": [ "Invoices" ], "summary": "Get an invoice with items and payments", "operationId": "invoicesGetId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoices ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Invoices" } } }, "example": { "ok": true, "data": { "id": "66f1c2a9e4b1d", "number": "0042-37-1026", "title": "Branded T-shirts — October order", "client_id": 2381, "type": "invoice", "status": "open", "confirmed": true, "date": "2026-10-08", "due_date": "2026-10-22", "tax_group_id": 1, "discount_type": "percent", "discount_value": 5, "subtotal": 1200, "discount": 60, "tax_total": 199.5, "total": 1339.5, "paid": 500, "balance_due": 839.5, "orders_created": false, "public_url": "https://blueq.app/link/invoice/66f1c2a9e4b1d", "created_at": "2026-10-08 09:14:00", "items": [ { "id": 9811, "product_id": 57, "name": "Round-neck T-shirt (L)", "description": "Navy, 2-colour print front", "qty": 40, "unit_price": 30, "amount": 1200 } ] } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "tags": [ "Invoices" ], "summary": "Update an invoice", "operationId": "invoicesPatchId", "description": "Client, title, dates, tax group and discount. Line items are locked once a payment is recorded.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoices ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Invoice title / subject.", "example": "Branded T-shirts — October order" }, "client_id": { "type": "integer", "description": "Client the invoice is billed to.", "example": 2381 }, "date": { "type": "string", "format": "date", "description": "Invoice date (YYYY-MM-DD).", "example": "2026-10-08" }, "due_date": { "type": "string", "format": "date", "description": "Payment due / quote expiry date.", "example": "2026-10-22" }, "tax_group_id": { "type": "integer", "description": "Tax group applied (see /tax-groups). Omit for the default group.", "example": 1 }, "discount_type": { "type": "string", "description": "\"amount\" or \"percent\".", "example": "percent" }, "discount_value": { "type": "number", "description": "Discount amount or percentage.", "example": 5 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceItem" }, "description": "Line items (detail view and create).", "example": [] } } }, "example": { "title": "Branded T-shirts — October order", "client_id": 2381, "date": "2026-10-08", "due_date": "2026-10-22", "tax_group_id": 1, "discount_type": "percent", "discount_value": 5, "items": [ { "product_id": 57, "name": "Round-neck T-shirt (L)", "description": "Navy, 2-colour print front", "qty": 40, "unit_price": 30 } ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Invoices" } } }, "example": { "ok": true, "data": { "id": "66f1c2a9e4b1d", "number": "0042-37-1026", "title": "Branded T-shirts — October order", "client_id": 2381, "type": "invoice", "status": "open", "confirmed": true, "date": "2026-10-08", "due_date": "2026-10-22", "tax_group_id": 1, "discount_type": "percent", "discount_value": 5, "subtotal": 1200, "discount": 60, "tax_total": 199.5, "total": 1339.5, "paid": 500, "balance_due": 839.5, "orders_created": false, "public_url": "https://blueq.app/link/invoice/66f1c2a9e4b1d", "created_at": "2026-10-08 09:14:00", "items": [ { "id": 9811, "product_id": 57, "name": "Round-neck T-shirt (L)", "description": "Navy, 2-colour print front", "qty": 40, "unit_price": 30, "amount": 1200 } ] } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Invoices" ], "summary": "Discard an invoice", "operationId": "invoicesDeleteId", "description": "Invoices are never hard-deleted. Any invoice can be discarded with a note, and restored later.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoices ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "description": "Reason (required).", "example": "Client cancelled" } }, "required": [ "note" ] }, "example": { "note": "Client cancelled" } } } }, "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{id}/restore": { "post": { "tags": [ "Invoices" ], "summary": "Restore a discarded invoice", "operationId": "invoicesPostIdRestore", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoices ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Invoices" } } }, "example": { "ok": true, "data": { "id": "66f1c2a9e4b1d", "number": "0042-37-1026", "title": "Branded T-shirts — October order", "client_id": 2381, "type": "invoice", "status": "open", "confirmed": true, "date": "2026-10-08", "due_date": "2026-10-22", "tax_group_id": 1, "discount_type": "percent", "discount_value": 5, "subtotal": 1200, "discount": 60, "tax_total": 199.5, "total": 1339.5, "paid": 500, "balance_due": 839.5, "orders_created": false, "public_url": "https://blueq.app/link/invoice/66f1c2a9e4b1d", "created_at": "2026-10-08 09:14:00", "items": [ { "id": 9811, "product_id": 57, "name": "Round-neck T-shirt (L)", "description": "Navy, 2-colour print front", "qty": 40, "unit_price": 30, "amount": 1200 } ] } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{id}/confirm": { "post": { "tags": [ "Invoices" ], "summary": "Confirm a proforma into an invoice", "operationId": "invoicesPostIdConfirm", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoices ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Invoices" } } }, "example": { "ok": true, "data": { "id": "66f1c2a9e4b1d", "number": "0042-37-1026", "title": "Branded T-shirts — October order", "client_id": 2381, "type": "invoice", "status": "open", "confirmed": true, "date": "2026-10-08", "due_date": "2026-10-22", "tax_group_id": 1, "discount_type": "percent", "discount_value": 5, "subtotal": 1200, "discount": 60, "tax_total": 199.5, "total": 1339.5, "paid": 500, "balance_due": 839.5, "orders_created": false, "public_url": "https://blueq.app/link/invoice/66f1c2a9e4b1d", "created_at": "2026-10-08 09:14:00", "items": [ { "id": 9811, "product_id": 57, "name": "Round-neck T-shirt (L)", "description": "Navy, 2-colour print front", "qty": 40, "unit_price": 30, "amount": 1200 } ] } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{id}/items": { "get": { "tags": [ "Invoices" ], "summary": "List line items", "operationId": "invoicesGetIdItems", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoices ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceItem" } } } }, "example": { "ok": true, "data": [ { "id": 9811, "product_id": 57, "name": "Round-neck T-shirt (L)", "description": "Navy, 2-colour print front", "qty": 40, "unit_price": 30, "amount": 1200 } ] } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Invoices" ], "summary": "Add a line item", "operationId": "invoicesPostIdItems", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoices ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "integer", "description": "Catalogue product/service, or null for a custom line.", "example": 57 }, "name": { "type": "string", "description": "Line name. Defaults to the product name.", "example": "Round-neck T-shirt (L)" }, "description": { "type": "string", "description": "Extra detail shown under the name.", "example": "Navy, 2-colour print front" }, "qty": { "type": "number", "description": "Quantity (default 1).", "example": 40 }, "unit_price": { "type": "number", "description": "Unit price. Defaults to the product price.", "example": 30 } } }, "example": { "product_id": 57, "name": "Round-neck T-shirt (L)", "description": "Navy, 2-colour print front", "qty": 40, "unit_price": 30 } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/InvoiceItem" } } }, "example": { "ok": true, "data": { "id": 9811, "product_id": 57, "name": "Round-neck T-shirt (L)", "description": "Navy, 2-colour print front", "qty": 40, "unit_price": 30, "amount": 1200 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{id}/items/{item_id}": { "patch": { "tags": [ "Invoices" ], "summary": "Update a line item", "operationId": "invoicesPatchIdItemsItemId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoices ID.", "schema": { "type": "string" } }, { "name": "item_id", "in": "path", "required": true, "description": "Item id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "integer", "description": "Catalogue product/service, or null for a custom line.", "example": 57 }, "name": { "type": "string", "description": "Line name. Defaults to the product name.", "example": "Round-neck T-shirt (L)" }, "description": { "type": "string", "description": "Extra detail shown under the name.", "example": "Navy, 2-colour print front" }, "qty": { "type": "number", "description": "Quantity (default 1).", "example": 40 }, "unit_price": { "type": "number", "description": "Unit price. Defaults to the product price.", "example": 30 } } }, "example": { "product_id": 57, "name": "Round-neck T-shirt (L)", "description": "Navy, 2-colour print front", "qty": 40, "unit_price": 30 } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/InvoiceItem" } } }, "example": { "ok": true, "data": { "id": 9811, "product_id": 57, "name": "Round-neck T-shirt (L)", "description": "Navy, 2-colour print front", "qty": 40, "unit_price": 30, "amount": 1200 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Invoices" ], "summary": "Remove a line item", "operationId": "invoicesDeleteIdItemsItemId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoices ID.", "schema": { "type": "string" } }, { "name": "item_id", "in": "path", "required": true, "description": "Item id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{id}/payments": { "get": { "tags": [ "Invoices" ], "summary": "List payments on the invoice", "operationId": "invoicesGetIdPayments", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoices ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoicePayment" } } } }, "example": { "ok": true, "data": [ { "id": 4410, "amount": 500, "mode": "momo", "date": "2026-10-08", "remarks": "MoMo ref 77812" } ] } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Invoices" ], "summary": "Record a payment", "operationId": "invoicesPostIdPayments", "description": "Duplicate payments (same client, amount, date and mode) are refused with 409. Send an Idempotency-Key to retry safely.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoices ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount received.", "example": 500 }, "mode": { "type": "string", "description": "cash, momo, cheque, bank, card, credit (from account balance) or a custom mode.", "example": "momo" }, "date": { "type": "string", "format": "date", "description": "Payment date (default today).", "example": "2026-10-08" }, "remarks": { "type": "string", "description": "Reference or note.", "example": "MoMo ref 77812" } }, "required": [ "amount" ] }, "example": { "amount": 500, "mode": "momo", "date": "2026-10-08", "remarks": "MoMo ref 77812" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/InvoicePayment" } } }, "example": { "ok": true, "data": { "id": 4410, "amount": 500, "mode": "momo", "date": "2026-10-08", "remarks": "MoMo ref 77812" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{id}/payments/{payment_id}": { "patch": { "tags": [ "Invoices" ], "summary": "Edit a payment", "operationId": "invoicesPatchIdPaymentsPaymentId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoices ID.", "schema": { "type": "string" } }, { "name": "payment_id", "in": "path", "required": true, "description": "Payment id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount received.", "example": 500 }, "mode": { "type": "string", "description": "cash, momo, cheque, bank, card, credit (from account balance) or a custom mode.", "example": "momo" }, "date": { "type": "string", "format": "date", "description": "Payment date (default today).", "example": "2026-10-08" }, "remarks": { "type": "string", "description": "Reference or note.", "example": "MoMo ref 77812" } }, "required": [ "amount" ] }, "example": { "amount": 500, "mode": "momo", "date": "2026-10-08", "remarks": "MoMo ref 77812" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/InvoicePayment" } } }, "example": { "ok": true, "data": { "id": 4410, "amount": 500, "mode": "momo", "date": "2026-10-08", "remarks": "MoMo ref 77812" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Invoices" ], "summary": "Delete a payment", "operationId": "invoicesDeleteIdPaymentsPaymentId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoices ID.", "schema": { "type": "string" } }, { "name": "payment_id", "in": "path", "required": true, "description": "Payment id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{id}/send": { "post": { "tags": [ "Invoices" ], "summary": "Send the invoice to the client", "operationId": "invoicesPostIdSend", "description": "Sending enables the public share link. SMS and WhatsApp use the workspace's messaging credits.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoices ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channels": { "type": "array", "items": { "type": "string" }, "description": "Any of email, sms, whatsapp (default email).", "example": [ "email", "whatsapp" ] }, "email_to": { "type": "array", "items": { "type": "string" }, "description": "Recipients (defaults to the client).", "example": [ "akosua@example.com" ] }, "cc": { "type": "string", "description": "Copy to this email.", "example": "accounts@kenteprints.com" }, "sms_to": { "type": "array", "items": { "type": "string" }, "description": "SMS numbers (defaults to the client).", "example": [] }, "whatsapp_to": { "type": "array", "items": { "type": "string" }, "description": "WhatsApp numbers (defaults to the client).", "example": [] }, "message": { "type": "string", "description": "Message shown with the link.", "example": "Please find your invoice below." }, "attach_pdf": { "type": "boolean", "description": "Include the PDF link.", "example": true } } }, "example": { "channels": [ "email", "whatsapp" ], "email_to": [ "akosua@example.com" ], "cc": "accounts@kenteprints.com", "sms_to": [], "whatsapp_to": [], "message": "Please find your invoice below.", "attach_pdf": true } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Invoices" } } }, "example": { "ok": true, "data": { "id": "66f1c2a9e4b1d", "number": "0042-37-1026", "title": "Branded T-shirts — October order", "client_id": 2381, "type": "invoice", "status": "open", "confirmed": true, "date": "2026-10-08", "due_date": "2026-10-22", "tax_group_id": 1, "discount_type": "percent", "discount_value": 5, "subtotal": 1200, "discount": 60, "tax_total": 199.5, "total": 1339.5, "paid": 500, "balance_due": 839.5, "orders_created": false, "public_url": "https://blueq.app/link/invoice/66f1c2a9e4b1d", "created_at": "2026-10-08 09:14:00", "items": [ { "id": 9811, "product_id": 57, "name": "Round-neck T-shirt (L)", "description": "Navy, 2-colour print front", "qty": 40, "unit_price": 30, "amount": 1200 } ] } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{id}/links": { "get": { "tags": [ "Invoices" ], "summary": "Public view, PDF and receipt links", "operationId": "invoicesGetIdLinks", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoices ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Invoices" } } }, "example": { "ok": true, "data": { "id": "66f1c2a9e4b1d", "number": "0042-37-1026", "title": "Branded T-shirts — October order", "client_id": 2381, "type": "invoice", "status": "open", "confirmed": true, "date": "2026-10-08", "due_date": "2026-10-22", "tax_group_id": 1, "discount_type": "percent", "discount_value": 5, "subtotal": 1200, "discount": 60, "tax_total": 199.5, "total": 1339.5, "paid": 500, "balance_due": 839.5, "orders_created": false, "public_url": "https://blueq.app/link/invoice/66f1c2a9e4b1d", "created_at": "2026-10-08 09:14:00", "items": [ { "id": 9811, "product_id": 57, "name": "Round-neck T-shirt (L)", "description": "Navy, 2-colour print front", "qty": 40, "unit_price": 30, "amount": 1200 } ] } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{id}/pdf": { "get": { "tags": [ "Invoices" ], "summary": "Get the PDF link", "operationId": "invoicesGetIdPdf", "description": "Same as /links. The PDF is rendered by the public print page, so turn sharing on first if the client should open it.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoices ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Invoices" } } }, "example": { "ok": true, "data": { "id": "66f1c2a9e4b1d", "number": "0042-37-1026", "title": "Branded T-shirts — October order", "client_id": 2381, "type": "invoice", "status": "open", "confirmed": true, "date": "2026-10-08", "due_date": "2026-10-22", "tax_group_id": 1, "discount_type": "percent", "discount_value": 5, "subtotal": 1200, "discount": 60, "tax_total": 199.5, "total": 1339.5, "paid": 500, "balance_due": 839.5, "orders_created": false, "public_url": "https://blueq.app/link/invoice/66f1c2a9e4b1d", "created_at": "2026-10-08 09:14:00", "items": [ { "id": 9811, "product_id": 57, "name": "Round-neck T-shirt (L)", "description": "Navy, 2-colour print front", "qty": 40, "unit_price": 30, "amount": 1200 } ] } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{id}/share": { "post": { "tags": [ "Invoices" ], "summary": "Turn the public link on or off", "operationId": "invoicesPostIdShare", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoices ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Share on/off.", "example": true } }, "required": [ "enabled" ] }, "example": { "enabled": true } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Invoices" } } }, "example": { "ok": true, "data": { "id": "66f1c2a9e4b1d", "number": "0042-37-1026", "title": "Branded T-shirts — October order", "client_id": 2381, "type": "invoice", "status": "open", "confirmed": true, "date": "2026-10-08", "due_date": "2026-10-22", "tax_group_id": 1, "discount_type": "percent", "discount_value": 5, "subtotal": 1200, "discount": 60, "tax_total": 199.5, "total": 1339.5, "paid": 500, "balance_due": 839.5, "orders_created": false, "public_url": "https://blueq.app/link/invoice/66f1c2a9e4b1d", "created_at": "2026-10-08 09:14:00", "items": [ { "id": 9811, "product_id": 57, "name": "Round-neck T-shirt (L)", "description": "Navy, 2-colour print front", "qty": 40, "unit_price": 30, "amount": 1200 } ] } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{id}/reminders": { "get": { "tags": [ "Invoices" ], "summary": "List scheduled reminders", "operationId": "invoicesGetIdReminders", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoices ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceReminder" } } } }, "example": { "ok": true, "data": [ { "id": 18, "remind_at": "2026-10-20 09:00", "channels": [ "email", "sms" ], "message": "Friendly reminder — balance due Friday.", "email_to": [], "sms_to": [], "whatsapp_to": [], "whatsapp_pdf": false, "recur": "monthly", "recur_until": "2026-12-31", "status": "pending" } ] } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Invoices" ], "summary": "Schedule a reminder", "operationId": "invoicesPostIdReminders", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoices ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "remind_at": { "type": "string", "format": "date-time", "description": "When to send (YYYY-MM-DD HH:MM, workspace time).", "example": "2026-10-20 09:00" }, "channels": { "type": "array", "items": { "type": "string" }, "description": "Any of email, sms, whatsapp.", "example": [ "email", "sms" ] }, "message": { "type": "string", "description": "Optional custom message (max 1000).", "example": "Friendly reminder — balance due Friday." }, "email_to": { "type": "array", "items": { "type": "string" }, "description": "Override recipients (defaults to the client).", "example": [] }, "sms_to": { "type": "array", "items": { "type": "string" }, "description": "Override SMS numbers.", "example": [] }, "whatsapp_to": { "type": "array", "items": { "type": "string" }, "description": "Override WhatsApp numbers.", "example": [] }, "whatsapp_pdf": { "type": "boolean", "description": "Attach the PDF on WhatsApp.", "example": false }, "recur": { "type": "string", "description": "\"\", \"daily\" or \"monthly\".", "example": "monthly" }, "recur_until": { "type": "string", "format": "date", "description": "Last date for repeating reminders.", "example": "2026-12-31" } }, "required": [ "remind_at", "channels" ] }, "example": { "remind_at": "2026-10-20 09:00", "channels": [ "email", "sms" ], "message": "Friendly reminder — balance due Friday.", "email_to": [], "sms_to": [], "whatsapp_to": [], "whatsapp_pdf": false, "recur": "monthly", "recur_until": "2026-12-31" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/InvoiceReminder" } } }, "example": { "ok": true, "data": { "id": 18, "remind_at": "2026-10-20 09:00", "channels": [ "email", "sms" ], "message": "Friendly reminder — balance due Friday.", "email_to": [], "sms_to": [], "whatsapp_to": [], "whatsapp_pdf": false, "recur": "monthly", "recur_until": "2026-12-31", "status": "pending" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{id}/reminders/{reminder_id}": { "patch": { "tags": [ "Invoices" ], "summary": "Change a pending reminder", "operationId": "invoicesPatchIdRemindersReminderId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoices ID.", "schema": { "type": "string" } }, { "name": "reminder_id", "in": "path", "required": true, "description": "Reminder id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "remind_at": { "type": "string", "format": "date-time", "description": "When to send (YYYY-MM-DD HH:MM, workspace time).", "example": "2026-10-20 09:00" }, "channels": { "type": "array", "items": { "type": "string" }, "description": "Any of email, sms, whatsapp.", "example": [ "email", "sms" ] }, "message": { "type": "string", "description": "Optional custom message (max 1000).", "example": "Friendly reminder — balance due Friday." }, "email_to": { "type": "array", "items": { "type": "string" }, "description": "Override recipients (defaults to the client).", "example": [] }, "sms_to": { "type": "array", "items": { "type": "string" }, "description": "Override SMS numbers.", "example": [] }, "whatsapp_to": { "type": "array", "items": { "type": "string" }, "description": "Override WhatsApp numbers.", "example": [] }, "whatsapp_pdf": { "type": "boolean", "description": "Attach the PDF on WhatsApp.", "example": false }, "recur": { "type": "string", "description": "\"\", \"daily\" or \"monthly\".", "example": "monthly" }, "recur_until": { "type": "string", "format": "date", "description": "Last date for repeating reminders.", "example": "2026-12-31" } }, "required": [ "remind_at", "channels" ] }, "example": { "remind_at": "2026-10-20 09:00", "channels": [ "email", "sms" ], "message": "Friendly reminder — balance due Friday.", "email_to": [], "sms_to": [], "whatsapp_to": [], "whatsapp_pdf": false, "recur": "monthly", "recur_until": "2026-12-31" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/InvoiceReminder" } } }, "example": { "ok": true, "data": { "id": 18, "remind_at": "2026-10-20 09:00", "channels": [ "email", "sms" ], "message": "Friendly reminder — balance due Friday.", "email_to": [], "sms_to": [], "whatsapp_to": [], "whatsapp_pdf": false, "recur": "monthly", "recur_until": "2026-12-31", "status": "pending" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Invoices" ], "summary": "Cancel a reminder", "operationId": "invoicesDeleteIdRemindersReminderId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invoices ID.", "schema": { "type": "string" } }, { "name": "reminder_id", "in": "path", "required": true, "description": "Reminder id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/payments": { "get": { "tags": [ "Payments" ], "summary": "List payments", "operationId": "paymentsGet", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "q", "in": "query", "description": "Search remarks or mode.", "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "description": "Only this client.", "schema": { "type": "string" } }, { "name": "invoice_id", "in": "query", "description": "Only this invoice.", "schema": { "type": "string" } }, { "name": "mode", "in": "query", "description": "Only this payment mode.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Payment date on/after.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Payment date on/before.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "date, amount, -created_at (default).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payments" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "ok": true, "data": [ { "id": 4410, "client_id": 2381, "invoice_id": "66f1c2a9e4b1d", "amount": 500, "mode": "momo", "date": "2026-10-08", "remarks": "MoMo ref 77812", "created_at": "2026-10-08 11:02:40" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/payments/{id}": { "get": { "tags": [ "Payments" ], "summary": "Get a payment", "operationId": "paymentsGetId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payments ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Payments" } } }, "example": { "ok": true, "data": { "id": 4410, "client_id": 2381, "invoice_id": "66f1c2a9e4b1d", "amount": 500, "mode": "momo", "date": "2026-10-08", "remarks": "MoMo ref 77812", "created_at": "2026-10-08 11:02:40" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/sales": { "get": { "tags": [ "Sales" ], "summary": "List sales", "operationId": "salesGet", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "q", "in": "query", "description": "Search customer, product summary or remarks.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "paid, partial or unpaid.", "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "description": "Only this client.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Sale date on/after.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Sale date on/before.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "date, total, -created_at (default).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Sales" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "ok": true, "data": [ { "id": 812, "date": "2026-10-08", "client_id": 2381, "customer": "Walk-in", "branch_id": 1, "items": [ { "product_id": 57, "name": "Lamination A3", "category": "Counter / walk-in sales", "qty": 2, "unit_price": 125, "amount": 250 } ], "payments": [ { "amount": 250, "mode": "cash", "date": "2026-10-08", "reference": "" } ], "discount_type": "amount", "discount_value": 0, "tax_group_id": null, "remarks": "Paid at the counter", "subtotal": 250, "discount": 0, "tax_total": 0, "total": 250, "paid": 250, "balance_due": 0, "payment_status": "paid", "invoice_id": null, "created_at": "2026-10-08 13:40:11" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Sales" ], "summary": "Record a sale", "operationId": "salesPost", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Sale date (default today).", "example": "2026-10-08" }, "client_id": { "type": "integer", "description": "Client, or null for a walk-in.", "example": 2381 }, "customer": { "type": "string", "description": "Customer name for walk-ins (defaults to \"Walk-in\").", "example": "Walk-in" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SaleItem" }, "description": "Cart lines (at least one).", "example": [] }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/SalePayment" }, "description": "Payments taken. Omit for an unpaid sale.", "example": [] }, "discount_type": { "type": "string", "description": "\"amount\" or \"percent\".", "example": "amount" }, "discount_value": { "type": "number", "description": "Discount amount or percentage.", "example": 0 }, "tax_group_id": { "type": "integer", "description": "Tax group to apply, \"default\", or null for no tax." }, "remarks": { "type": "string", "description": "Internal note.", "example": "Paid at the counter" } }, "required": [ "items" ] }, "example": { "date": "2026-10-08", "client_id": 2381, "customer": "Walk-in", "items": [ { "product_id": 57, "name": "Lamination A3", "category": "Counter / walk-in sales", "qty": 2, "unit_price": 125 } ], "payments": [ { "amount": 250, "mode": "cash", "date": "2026-10-08", "reference": "" } ], "discount_type": "amount", "discount_value": 0, "tax_group_id": null, "remarks": "Paid at the counter" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Sales" } } }, "example": { "ok": true, "data": { "id": 812, "date": "2026-10-08", "client_id": 2381, "customer": "Walk-in", "branch_id": 1, "items": [ { "product_id": 57, "name": "Lamination A3", "category": "Counter / walk-in sales", "qty": 2, "unit_price": 125, "amount": 250 } ], "payments": [ { "amount": 250, "mode": "cash", "date": "2026-10-08", "reference": "" } ], "discount_type": "amount", "discount_value": 0, "tax_group_id": null, "remarks": "Paid at the counter", "subtotal": 250, "discount": 0, "tax_total": 0, "total": 250, "paid": 250, "balance_due": 0, "payment_status": "paid", "invoice_id": null, "created_at": "2026-10-08 13:40:11" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/sales/{id}": { "get": { "tags": [ "Sales" ], "summary": "Get a sale with items and payments", "operationId": "salesGetId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Sales ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Sales" } } }, "example": { "ok": true, "data": { "id": 812, "date": "2026-10-08", "client_id": 2381, "customer": "Walk-in", "branch_id": 1, "items": [ { "product_id": 57, "name": "Lamination A3", "category": "Counter / walk-in sales", "qty": 2, "unit_price": 125, "amount": 250 } ], "payments": [ { "amount": 250, "mode": "cash", "date": "2026-10-08", "reference": "" } ], "discount_type": "amount", "discount_value": 0, "tax_group_id": null, "remarks": "Paid at the counter", "subtotal": 250, "discount": 0, "tax_total": 0, "total": 250, "paid": 250, "balance_due": 0, "payment_status": "paid", "invoice_id": null, "created_at": "2026-10-08 13:40:11" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "tags": [ "Sales" ], "summary": "Update a sale", "operationId": "salesPatchId", "description": "Fields you omit are kept. Passing items or payments replaces the whole list.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Sales ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Sale date (default today).", "example": "2026-10-08" }, "client_id": { "type": "integer", "description": "Client, or null for a walk-in.", "example": 2381 }, "customer": { "type": "string", "description": "Customer name for walk-ins (defaults to \"Walk-in\").", "example": "Walk-in" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SaleItem" }, "description": "Cart lines (at least one).", "example": [] }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/SalePayment" }, "description": "Payments taken. Omit for an unpaid sale.", "example": [] }, "discount_type": { "type": "string", "description": "\"amount\" or \"percent\".", "example": "amount" }, "discount_value": { "type": "number", "description": "Discount amount or percentage.", "example": 0 }, "tax_group_id": { "type": "integer", "description": "Tax group to apply, \"default\", or null for no tax." }, "remarks": { "type": "string", "description": "Internal note.", "example": "Paid at the counter" } } }, "example": { "date": "2026-10-08", "client_id": 2381, "customer": "Walk-in", "items": [ { "product_id": 57, "name": "Lamination A3", "category": "Counter / walk-in sales", "qty": 2, "unit_price": 125 } ], "payments": [ { "amount": 250, "mode": "cash", "date": "2026-10-08", "reference": "" } ], "discount_type": "amount", "discount_value": 0, "tax_group_id": null, "remarks": "Paid at the counter" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Sales" } } }, "example": { "ok": true, "data": { "id": 812, "date": "2026-10-08", "client_id": 2381, "customer": "Walk-in", "branch_id": 1, "items": [ { "product_id": 57, "name": "Lamination A3", "category": "Counter / walk-in sales", "qty": 2, "unit_price": 125, "amount": 250 } ], "payments": [ { "amount": 250, "mode": "cash", "date": "2026-10-08", "reference": "" } ], "discount_type": "amount", "discount_value": 0, "tax_group_id": null, "remarks": "Paid at the counter", "subtotal": 250, "discount": 0, "tax_total": 0, "total": 250, "paid": 250, "balance_due": 0, "payment_status": "paid", "invoice_id": null, "created_at": "2026-10-08 13:40:11" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Sales" ], "summary": "Delete a sale", "operationId": "salesDeleteId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Sales ID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/sales/{id}/payments": { "post": { "tags": [ "Sales" ], "summary": "Add a payment to a sale", "operationId": "salesPostIdPayments", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Sales ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount.", "example": 250 }, "mode": { "type": "string", "description": "cash, momo, card, bank, cheque…", "example": "cash" }, "date": { "type": "string", "format": "date", "description": "Payment date (default sale date).", "example": "2026-10-08" }, "reference": { "type": "string", "description": "Reference number.", "example": "" } }, "required": [ "amount" ] }, "example": { "amount": 250, "mode": "cash", "date": "2026-10-08", "reference": "" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Sales" } } }, "example": { "ok": true, "data": { "id": 812, "date": "2026-10-08", "client_id": 2381, "customer": "Walk-in", "branch_id": 1, "items": [ { "product_id": 57, "name": "Lamination A3", "category": "Counter / walk-in sales", "qty": 2, "unit_price": 125, "amount": 250 } ], "payments": [ { "amount": 250, "mode": "cash", "date": "2026-10-08", "reference": "" } ], "discount_type": "amount", "discount_value": 0, "tax_group_id": null, "remarks": "Paid at the counter", "subtotal": 250, "discount": 0, "tax_total": 0, "total": 250, "paid": 250, "balance_due": 0, "payment_status": "paid", "invoice_id": null, "created_at": "2026-10-08 13:40:11" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/sales/{id}/invoice": { "post": { "tags": [ "Sales" ], "summary": "Generate an invoice from the sale", "operationId": "salesPostIdInvoice", "description": "Returns the existing invoice if one was already generated.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Sales ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Sales" } } }, "example": { "ok": true, "data": { "id": 812, "date": "2026-10-08", "client_id": 2381, "customer": "Walk-in", "branch_id": 1, "items": [ { "product_id": 57, "name": "Lamination A3", "category": "Counter / walk-in sales", "qty": 2, "unit_price": 125, "amount": 250 } ], "payments": [ { "amount": 250, "mode": "cash", "date": "2026-10-08", "reference": "" } ], "discount_type": "amount", "discount_value": 0, "tax_group_id": null, "remarks": "Paid at the counter", "subtotal": 250, "discount": 0, "tax_total": 0, "total": 250, "paid": 250, "balance_due": 0, "payment_status": "paid", "invoice_id": null, "created_at": "2026-10-08 13:40:11" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/expenditure": { "get": { "tags": [ "Expenditure" ], "summary": "List expenses", "operationId": "expenditureGet", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "q", "in": "query", "description": "Search payee, category or remarks.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "paid, partial or unpaid.", "schema": { "type": "string" } }, { "name": "supplier_id", "in": "query", "description": "Only this supplier.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Expense date on/after.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Expense date on/before.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "date, total, -created_at (default).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Expenditure" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "ok": true, "data": [ { "id": 305, "date": "2026-10-07", "payee": "Accra Paper Mills", "supplier_id": 14, "supplier_invoice": "APM-55120", "linked_invoice_id": null, "category": "Raw materials", "items": [ { "product_id": 61, "name": "A4 paper 80gsm (box)", "category": "Raw materials", "qty": 10, "unit": "box", "unit_price": 145, "amount": 1450, "remarks": "", "expiry_date": null } ], "payments": [ { "amount": 1450, "mode": "momo", "date": "2026-10-07", "reference": "MOMO-99812", "remarks": "" } ], "total": 1450, "paid": 1450, "balance_due": 0, "payment_status": "paid", "branch_id": 1, "created_at": "2026-10-07 16:20:00" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Expenditure" ], "summary": "Record an expense", "operationId": "expenditurePost", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Expense date (default today).", "example": "2026-10-07" }, "payee": { "type": "string", "description": "Who was paid (defaults to the supplier name).", "example": "Accra Paper Mills" }, "supplier_id": { "type": "integer", "description": "Supplier (see /suppliers).", "example": 14 }, "supplier_invoice": { "type": "string", "description": "Supplier's invoice / bill number.", "example": "APM-55120" }, "linked_invoice_id": { "type": "string", "description": "Customer invoice this cost belongs to (job costing)." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ExpenseItem" }, "description": "Lines (at least one).", "example": [] }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/ExpensePayment" }, "description": "Payments made. Omit for an unpaid bill.", "example": [] } }, "required": [ "items" ] }, "example": { "date": "2026-10-07", "payee": "Accra Paper Mills", "supplier_id": 14, "supplier_invoice": "APM-55120", "linked_invoice_id": null, "items": [ { "product_id": 61, "name": "A4 paper 80gsm (box)", "category": "Raw materials", "qty": 10, "unit": "box", "unit_price": 145, "remarks": "", "expiry_date": null } ], "payments": [ { "amount": 1450, "mode": "momo", "date": "2026-10-07", "reference": "MOMO-99812", "remarks": "" } ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Expenditure" } } }, "example": { "ok": true, "data": { "id": 305, "date": "2026-10-07", "payee": "Accra Paper Mills", "supplier_id": 14, "supplier_invoice": "APM-55120", "linked_invoice_id": null, "category": "Raw materials", "items": [ { "product_id": 61, "name": "A4 paper 80gsm (box)", "category": "Raw materials", "qty": 10, "unit": "box", "unit_price": 145, "amount": 1450, "remarks": "", "expiry_date": null } ], "payments": [ { "amount": 1450, "mode": "momo", "date": "2026-10-07", "reference": "MOMO-99812", "remarks": "" } ], "total": 1450, "paid": 1450, "balance_due": 0, "payment_status": "paid", "branch_id": 1, "created_at": "2026-10-07 16:20:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/expenditure/{id}": { "get": { "tags": [ "Expenditure" ], "summary": "Get an expense with lines and payments", "operationId": "expenditureGetId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Expenditure ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Expenditure" } } }, "example": { "ok": true, "data": { "id": 305, "date": "2026-10-07", "payee": "Accra Paper Mills", "supplier_id": 14, "supplier_invoice": "APM-55120", "linked_invoice_id": null, "category": "Raw materials", "items": [ { "product_id": 61, "name": "A4 paper 80gsm (box)", "category": "Raw materials", "qty": 10, "unit": "box", "unit_price": 145, "amount": 1450, "remarks": "", "expiry_date": null } ], "payments": [ { "amount": 1450, "mode": "momo", "date": "2026-10-07", "reference": "MOMO-99812", "remarks": "" } ], "total": 1450, "paid": 1450, "balance_due": 0, "payment_status": "paid", "branch_id": 1, "created_at": "2026-10-07 16:20:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "tags": [ "Expenditure" ], "summary": "Update an expense", "operationId": "expenditurePatchId", "description": "Omitted fields are kept. Passing items or payments replaces the whole list; stock is re-balanced.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Expenditure ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Expense date (default today).", "example": "2026-10-07" }, "payee": { "type": "string", "description": "Who was paid (defaults to the supplier name).", "example": "Accra Paper Mills" }, "supplier_id": { "type": "integer", "description": "Supplier (see /suppliers).", "example": 14 }, "supplier_invoice": { "type": "string", "description": "Supplier's invoice / bill number.", "example": "APM-55120" }, "linked_invoice_id": { "type": "string", "description": "Customer invoice this cost belongs to (job costing)." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ExpenseItem" }, "description": "Lines (at least one).", "example": [] }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/ExpensePayment" }, "description": "Payments made. Omit for an unpaid bill.", "example": [] } } }, "example": { "date": "2026-10-07", "payee": "Accra Paper Mills", "supplier_id": 14, "supplier_invoice": "APM-55120", "linked_invoice_id": null, "items": [ { "product_id": 61, "name": "A4 paper 80gsm (box)", "category": "Raw materials", "qty": 10, "unit": "box", "unit_price": 145, "remarks": "", "expiry_date": null } ], "payments": [ { "amount": 1450, "mode": "momo", "date": "2026-10-07", "reference": "MOMO-99812", "remarks": "" } ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Expenditure" } } }, "example": { "ok": true, "data": { "id": 305, "date": "2026-10-07", "payee": "Accra Paper Mills", "supplier_id": 14, "supplier_invoice": "APM-55120", "linked_invoice_id": null, "category": "Raw materials", "items": [ { "product_id": 61, "name": "A4 paper 80gsm (box)", "category": "Raw materials", "qty": 10, "unit": "box", "unit_price": 145, "amount": 1450, "remarks": "", "expiry_date": null } ], "payments": [ { "amount": 1450, "mode": "momo", "date": "2026-10-07", "reference": "MOMO-99812", "remarks": "" } ], "total": 1450, "paid": 1450, "balance_due": 0, "payment_status": "paid", "branch_id": 1, "created_at": "2026-10-07 16:20:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Expenditure" ], "summary": "Delete an expense", "operationId": "expenditureDeleteId", "description": "Stock added by the expense is reversed.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Expenditure ID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/expenditure/{id}/payments": { "post": { "tags": [ "Expenditure" ], "summary": "Add a payment to an expense", "operationId": "expenditurePostIdPayments", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Expenditure ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount paid.", "example": 1450 }, "mode": { "type": "string", "description": "cash, momo, bank, cheque…", "example": "momo" }, "date": { "type": "string", "format": "date", "description": "Payment date (default expense date).", "example": "2026-10-07" }, "reference": { "type": "string", "description": "Reference.", "example": "MOMO-99812" }, "remarks": { "type": "string", "description": "Note.", "example": "" } }, "required": [ "amount" ] }, "example": { "amount": 1450, "mode": "momo", "date": "2026-10-07", "reference": "MOMO-99812", "remarks": "" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Expenditure" } } }, "example": { "ok": true, "data": { "id": 305, "date": "2026-10-07", "payee": "Accra Paper Mills", "supplier_id": 14, "supplier_invoice": "APM-55120", "linked_invoice_id": null, "category": "Raw materials", "items": [ { "product_id": 61, "name": "A4 paper 80gsm (box)", "category": "Raw materials", "qty": 10, "unit": "box", "unit_price": 145, "amount": 1450, "remarks": "", "expiry_date": null } ], "payments": [ { "amount": 1450, "mode": "momo", "date": "2026-10-07", "reference": "MOMO-99812", "remarks": "" } ], "total": 1450, "paid": 1450, "balance_due": 0, "payment_status": "paid", "branch_id": 1, "created_at": "2026-10-07 16:20:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/orders": { "get": { "tags": [ "Orders (production)" ], "summary": "List orders", "operationId": "ordersGet", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "status", "in": "query", "description": "pending, in_progress, completed or cancelled.", "schema": { "type": "string" } }, { "name": "invoice_id", "in": "query", "description": "Only orders from this invoice.", "schema": { "type": "string" } }, { "name": "job_id", "in": "query", "description": "Only orders in this job.", "schema": { "type": "string" } }, { "name": "assigned_to", "in": "query", "description": "Only orders assigned to this user.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Search title or remarks.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Created on/after.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Created on/before.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "start_at, end_at, -created_at (default).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Orders" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "ok": true, "data": [ { "id": 1204, "job_id": 388, "invoice_id": "66f1c2a9e4b1d", "title": "Round-neck T-shirt (L) — navy", "product_id": 57, "qty": 40, "status": "in_progress", "assigned_to": 77, "start_at": "2026-10-09 08:00", "end_at": "2026-10-10 17:00", "remarks": "Use Pantone 2945C", "started_at": "2026-10-09 08:12:00", "completed_at": null, "cancelled_at": null, "processes": [ { "id": 5521, "name": "Screen print", "done": false, "completed_at": null } ], "created_at": "2026-10-08 15:00:00" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Orders (production)" ], "summary": "Create an order inside a job", "operationId": "ordersPost", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "integer", "description": "Job (invoice line group) this order belongs to.", "example": 388 }, "title": { "type": "string", "description": "What is being produced.", "example": "Round-neck T-shirt (L) — navy" }, "product_id": { "type": "integer", "description": "Catalogue product/service, if any.", "example": 57 }, "qty": { "type": "number", "description": "Quantity.", "example": 40 }, "assigned_to": { "type": "integer", "description": "Team member (see /users).", "example": 77 }, "start_at": { "type": "string", "format": "date-time", "description": "Planned start (YYYY-MM-DD HH:MM).", "example": "2026-10-09 08:00" }, "end_at": { "type": "string", "format": "date-time", "description": "Planned finish.", "example": "2026-10-10 17:00" }, "remarks": { "type": "string", "description": "Production notes.", "example": "Use Pantone 2945C" }, "processes": { "type": "array", "items": { "$ref": "#/components/schemas/OrderProcess" }, "description": "Processes (detail view). On create, pass an array of names.", "example": [] } }, "required": [ "job_id", "title" ] }, "example": { "job_id": 388, "title": "Round-neck T-shirt (L) — navy", "product_id": 57, "qty": 40, "assigned_to": 77, "start_at": "2026-10-09 08:00", "end_at": "2026-10-10 17:00", "remarks": "Use Pantone 2945C", "processes": [ [] ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Orders" } } }, "example": { "ok": true, "data": { "id": 1204, "job_id": 388, "invoice_id": "66f1c2a9e4b1d", "title": "Round-neck T-shirt (L) — navy", "product_id": 57, "qty": 40, "status": "in_progress", "assigned_to": 77, "start_at": "2026-10-09 08:00", "end_at": "2026-10-10 17:00", "remarks": "Use Pantone 2945C", "started_at": "2026-10-09 08:12:00", "completed_at": null, "cancelled_at": null, "processes": [ { "id": 5521, "name": "Screen print", "done": false, "completed_at": null } ], "created_at": "2026-10-08 15:00:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/orders/jobs": { "get": { "tags": [ "Orders (production)" ], "summary": "List jobs (invoice line groups)", "operationId": "ordersGetJobs", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "invoice_id", "in": "query", "description": "Only jobs from this invoice.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "ok": true, "data": [ { "id": 388, "invoice_id": "66f1c2a9e4b1d", "invoice_item_id": 9811, "title": "Round-neck T-shirt (L)", "qty": 40, "order_count": 1, "created_at": "2026-10-08 15:00:00" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/orders/from-invoice": { "post": { "tags": [ "Orders (production)" ], "summary": "Create jobs and orders from an invoice", "operationId": "ordersPostFromInvoice", "description": "One job is created per line item. Requires the invoice to be eligible for production (confirmed / paid per your settings).", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice_id": { "type": "string", "description": "Invoice to produce.", "example": "66f1c2a9e4b1d" } }, "required": [ "invoice_id" ] }, "example": { "invoice_id": "66f1c2a9e4b1d" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Job" } } }, "example": { "ok": true, "data": { "id": 388, "invoice_id": "66f1c2a9e4b1d", "invoice_item_id": 9811, "title": "Round-neck T-shirt (L)", "qty": 40, "order_count": 1, "created_at": "2026-10-08 15:00:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}": { "get": { "tags": [ "Orders (production)" ], "summary": "Get an order with its processes", "operationId": "ordersGetId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Orders (production) ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Orders" } } }, "example": { "ok": true, "data": { "id": 1204, "job_id": 388, "invoice_id": "66f1c2a9e4b1d", "title": "Round-neck T-shirt (L) — navy", "product_id": 57, "qty": 40, "status": "in_progress", "assigned_to": 77, "start_at": "2026-10-09 08:00", "end_at": "2026-10-10 17:00", "remarks": "Use Pantone 2945C", "started_at": "2026-10-09 08:12:00", "completed_at": null, "cancelled_at": null, "processes": [ { "id": 5521, "name": "Screen print", "done": false, "completed_at": null } ], "created_at": "2026-10-08 15:00:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "tags": [ "Orders (production)" ], "summary": "Update a pending order", "operationId": "ordersPatchId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Orders (production) ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "integer", "description": "Job (invoice line group) this order belongs to.", "example": 388 }, "title": { "type": "string", "description": "What is being produced.", "example": "Round-neck T-shirt (L) — navy" }, "product_id": { "type": "integer", "description": "Catalogue product/service, if any.", "example": 57 }, "qty": { "type": "number", "description": "Quantity.", "example": 40 }, "assigned_to": { "type": "integer", "description": "Team member (see /users).", "example": 77 }, "start_at": { "type": "string", "format": "date-time", "description": "Planned start (YYYY-MM-DD HH:MM).", "example": "2026-10-09 08:00" }, "end_at": { "type": "string", "format": "date-time", "description": "Planned finish.", "example": "2026-10-10 17:00" }, "remarks": { "type": "string", "description": "Production notes.", "example": "Use Pantone 2945C" }, "processes": { "type": "array", "items": { "$ref": "#/components/schemas/OrderProcess" }, "description": "Processes (detail view). On create, pass an array of names.", "example": [] } } }, "example": { "job_id": 388, "title": "Round-neck T-shirt (L) — navy", "product_id": 57, "qty": 40, "assigned_to": 77, "start_at": "2026-10-09 08:00", "end_at": "2026-10-10 17:00", "remarks": "Use Pantone 2945C", "processes": [ [] ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Orders" } } }, "example": { "ok": true, "data": { "id": 1204, "job_id": 388, "invoice_id": "66f1c2a9e4b1d", "title": "Round-neck T-shirt (L) — navy", "product_id": 57, "qty": 40, "status": "in_progress", "assigned_to": 77, "start_at": "2026-10-09 08:00", "end_at": "2026-10-10 17:00", "remarks": "Use Pantone 2945C", "started_at": "2026-10-09 08:12:00", "completed_at": null, "cancelled_at": null, "processes": [ { "id": 5521, "name": "Screen print", "done": false, "completed_at": null } ], "created_at": "2026-10-08 15:00:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Orders (production)" ], "summary": "Delete a pending order", "operationId": "ordersDeleteId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Orders (production) ID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}/commence": { "post": { "tags": [ "Orders (production)" ], "summary": "Start work on an order", "operationId": "ordersPostIdCommence", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Orders (production) ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Orders" } } }, "example": { "ok": true, "data": { "id": 1204, "job_id": 388, "invoice_id": "66f1c2a9e4b1d", "title": "Round-neck T-shirt (L) — navy", "product_id": 57, "qty": 40, "status": "in_progress", "assigned_to": 77, "start_at": "2026-10-09 08:00", "end_at": "2026-10-10 17:00", "remarks": "Use Pantone 2945C", "started_at": "2026-10-09 08:12:00", "completed_at": null, "cancelled_at": null, "processes": [ { "id": 5521, "name": "Screen print", "done": false, "completed_at": null } ], "created_at": "2026-10-08 15:00:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}/complete": { "post": { "tags": [ "Orders (production)" ], "summary": "Complete an order", "operationId": "ordersPostIdComplete", "description": "Refused with 409 while processes are open unless \"force\": true.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Orders (production) ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "force": { "type": "boolean", "description": "Also tick off any open processes.", "example": false } } }, "example": { "force": false } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Orders" } } }, "example": { "ok": true, "data": { "id": 1204, "job_id": 388, "invoice_id": "66f1c2a9e4b1d", "title": "Round-neck T-shirt (L) — navy", "product_id": 57, "qty": 40, "status": "in_progress", "assigned_to": 77, "start_at": "2026-10-09 08:00", "end_at": "2026-10-10 17:00", "remarks": "Use Pantone 2945C", "started_at": "2026-10-09 08:12:00", "completed_at": null, "cancelled_at": null, "processes": [ { "id": 5521, "name": "Screen print", "done": false, "completed_at": null } ], "created_at": "2026-10-08 15:00:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}/cancel": { "post": { "tags": [ "Orders (production)" ], "summary": "Cancel an order", "operationId": "ordersPostIdCancel", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Orders (production) ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Orders" } } }, "example": { "ok": true, "data": { "id": 1204, "job_id": 388, "invoice_id": "66f1c2a9e4b1d", "title": "Round-neck T-shirt (L) — navy", "product_id": 57, "qty": 40, "status": "in_progress", "assigned_to": 77, "start_at": "2026-10-09 08:00", "end_at": "2026-10-10 17:00", "remarks": "Use Pantone 2945C", "started_at": "2026-10-09 08:12:00", "completed_at": null, "cancelled_at": null, "processes": [ { "id": 5521, "name": "Screen print", "done": false, "completed_at": null } ], "created_at": "2026-10-08 15:00:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}/processes": { "post": { "tags": [ "Orders (production)" ], "summary": "Add processes", "operationId": "ordersPostIdProcesses", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Orders (production) ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "names": { "type": "array", "items": { "type": "string" }, "description": "Process names. Duplicates are skipped.", "example": [ "Design", "Print" ] } }, "required": [ "names" ] }, "example": { "names": [ "Design", "Print" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/OrderProcess" } } }, "example": { "ok": true, "data": { "id": 5521, "name": "Screen print", "done": false, "completed_at": null } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}/processes/{process_id}/complete": { "post": { "tags": [ "Orders (production)" ], "summary": "Tick off a process", "operationId": "ordersPostIdProcessesProcessIdComplete", "description": "The order must be in progress.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Orders (production) ID.", "schema": { "type": "string" } }, { "name": "process_id", "in": "path", "required": true, "description": "Process id.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/OrderProcess" } } }, "example": { "ok": true, "data": { "id": 5521, "name": "Screen print", "done": false, "completed_at": null } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}/processes/{process_id}": { "delete": { "tags": [ "Orders (production)" ], "summary": "Remove an open process", "operationId": "ordersDeleteIdProcessesProcessId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Orders (production) ID.", "schema": { "type": "string" } }, { "name": "process_id", "in": "path", "required": true, "description": "Process id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/taxes": { "get": { "tags": [ "Taxes" ], "summary": "List taxes", "operationId": "taxesGet", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Taxes" } } } }, "example": { "ok": true, "data": [ { "id": 31, "name": "VAT", "rate": 15, "type": "vat", "sort": 40, "active": true } ] } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Taxes" ], "summary": "Create a tax", "operationId": "taxesPost", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Tax name.", "example": "VAT" }, "rate": { "type": "number", "description": "Percentage, 0 to 100.", "example": 15 }, "type": { "type": "string", "description": "\"levy\" or \"vat\".", "example": "vat" }, "sort": { "type": "integer", "description": "Display and calculation order.", "example": 40 }, "active": { "type": "boolean", "description": "Active taxes are added to the default tax group on create.", "example": true } }, "required": [ "name", "rate", "type" ] }, "example": { "name": "VAT", "rate": 15, "type": "vat", "sort": 40, "active": true } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Taxes" } } }, "example": { "ok": true, "data": { "id": 31, "name": "VAT", "rate": 15, "type": "vat", "sort": 40, "active": true } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/taxes/{id}": { "get": { "tags": [ "Taxes" ], "summary": "Get a tax", "operationId": "taxesGetId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Taxes ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Taxes" } } }, "example": { "ok": true, "data": { "id": 31, "name": "VAT", "rate": 15, "type": "vat", "sort": 40, "active": true } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "tags": [ "Taxes" ], "summary": "Update a tax", "operationId": "taxesPatchId", "description": "Invoices already confirmed keep the rates they were issued with.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Taxes ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Tax name.", "example": "VAT" }, "rate": { "type": "number", "description": "Percentage, 0 to 100.", "example": 15 }, "type": { "type": "string", "description": "\"levy\" or \"vat\".", "example": "vat" }, "sort": { "type": "integer", "description": "Display and calculation order.", "example": 40 }, "active": { "type": "boolean", "description": "Active taxes are added to the default tax group on create.", "example": true } } }, "example": { "name": "VAT", "rate": 15, "type": "vat", "sort": 40, "active": true } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Taxes" } } }, "example": { "ok": true, "data": { "id": 31, "name": "VAT", "rate": 15, "type": "vat", "sort": 40, "active": true } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Taxes" ], "summary": "Delete a tax", "operationId": "taxesDeleteId", "description": "Also removes the tax from every tax group.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Taxes ID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/tax-groups": { "get": { "tags": [ "Tax groups" ], "summary": "List tax groups", "operationId": "taxGroupsGet", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TaxGroups" } } } }, "example": { "ok": true, "data": [ { "id": 4, "name": "Standard (VAT + levies)", "is_default": true, "active": true, "sort": 0, "tax_ids": [ 28, 29, 30, 31 ], "taxes": [ { "id": 31, "name": "VAT", "rate": 15, "type": "vat" } ] } ] } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Tax groups" ], "summary": "Create a tax group", "operationId": "taxGroupsPost", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Group name.", "example": "Standard (VAT + levies)" }, "is_default": { "type": "boolean", "description": "Default group for new invoices and sales.", "example": true }, "active": { "type": "boolean", "description": "Whether the group can be selected.", "example": true }, "sort": { "type": "integer", "description": "Display order.", "example": 0 }, "tax_ids": { "type": "array", "items": { "type": "object" }, "description": "IDs of the taxes in this group.", "example": [ 28, 29, 30, 31 ] } }, "required": [ "name" ] }, "example": { "name": "Standard (VAT + levies)", "is_default": true, "active": true, "sort": 0, "tax_ids": [ 28, 29, 30, 31 ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/TaxGroups" } } }, "example": { "ok": true, "data": { "id": 4, "name": "Standard (VAT + levies)", "is_default": true, "active": true, "sort": 0, "tax_ids": [ 28, 29, 30, 31 ], "taxes": [ { "id": 31, "name": "VAT", "rate": 15, "type": "vat" } ] } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/tax-groups/{id}": { "get": { "tags": [ "Tax groups" ], "summary": "Get a tax group", "operationId": "taxGroupsGetId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tax groups ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/TaxGroups" } } }, "example": { "ok": true, "data": { "id": 4, "name": "Standard (VAT + levies)", "is_default": true, "active": true, "sort": 0, "tax_ids": [ 28, 29, 30, 31 ], "taxes": [ { "id": 31, "name": "VAT", "rate": 15, "type": "vat" } ] } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "tags": [ "Tax groups" ], "summary": "Update a tax group", "operationId": "taxGroupsPatchId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tax groups ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Group name.", "example": "Standard (VAT + levies)" }, "is_default": { "type": "boolean", "description": "Default group for new invoices and sales.", "example": true }, "active": { "type": "boolean", "description": "Whether the group can be selected.", "example": true }, "sort": { "type": "integer", "description": "Display order.", "example": 0 }, "tax_ids": { "type": "array", "items": { "type": "object" }, "description": "IDs of the taxes in this group.", "example": [ 28, 29, 30, 31 ] } } }, "example": { "name": "Standard (VAT + levies)", "is_default": true, "active": true, "sort": 0, "tax_ids": [ 28, 29, 30, 31 ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/TaxGroups" } } }, "example": { "ok": true, "data": { "id": 4, "name": "Standard (VAT + levies)", "is_default": true, "active": true, "sort": 0, "tax_ids": [ 28, 29, 30, 31 ], "taxes": [ { "id": 31, "name": "VAT", "rate": 15, "type": "vat" } ] } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Tax groups" ], "summary": "Delete a tax group", "operationId": "taxGroupsDeleteId", "description": "The default group cannot be deleted (409).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tax groups ID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/branches": { "get": { "tags": [ "Branches" ], "summary": "List branches", "operationId": "branchesGet", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Branches" } } } }, "example": { "ok": true, "data": [ { "id": 3, "name": "Kumasi Mall", "code": "KSI", "phone": "0322000111", "email": "kumasi@kenteprints.com", "address": "Shop 14, Kumasi City Mall", "town": "Kumasi", "is_default": false, "active": true, "created_at": "2026-05-11 12:00:00" } ] } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Branches" ], "summary": "Create a branch", "operationId": "branchesPost", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Branch name.", "example": "Kumasi Mall" }, "code": { "type": "string", "description": "Short code (stored uppercase).", "example": "KSI" }, "phone": { "type": "string", "description": "Phone (digits only).", "example": "0322000111" }, "email": { "type": "string", "description": "Email.", "example": "kumasi@kenteprints.com" }, "address": { "type": "string", "description": "Street address.", "example": "Shop 14, Kumasi City Mall" }, "town": { "type": "string", "description": "Town or city.", "example": "Kumasi" }, "is_default": { "type": "boolean", "description": "Default branch for new records.", "example": false }, "active": { "type": "boolean", "description": "Whether the branch is in use.", "example": true } }, "required": [ "name" ] }, "example": { "name": "Kumasi Mall", "code": "KSI", "phone": "0322000111", "email": "kumasi@kenteprints.com", "address": "Shop 14, Kumasi City Mall", "town": "Kumasi", "is_default": false, "active": true } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Branches" } } }, "example": { "ok": true, "data": { "id": 3, "name": "Kumasi Mall", "code": "KSI", "phone": "0322000111", "email": "kumasi@kenteprints.com", "address": "Shop 14, Kumasi City Mall", "town": "Kumasi", "is_default": false, "active": true, "created_at": "2026-05-11 12:00:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/branches/{id}": { "get": { "tags": [ "Branches" ], "summary": "Get a branch", "operationId": "branchesGetId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Branches ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Branches" } } }, "example": { "ok": true, "data": { "id": 3, "name": "Kumasi Mall", "code": "KSI", "phone": "0322000111", "email": "kumasi@kenteprints.com", "address": "Shop 14, Kumasi City Mall", "town": "Kumasi", "is_default": false, "active": true, "created_at": "2026-05-11 12:00:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "tags": [ "Branches" ], "summary": "Update a branch", "operationId": "branchesPatchId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Branches ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Branch name.", "example": "Kumasi Mall" }, "code": { "type": "string", "description": "Short code (stored uppercase).", "example": "KSI" }, "phone": { "type": "string", "description": "Phone (digits only).", "example": "0322000111" }, "email": { "type": "string", "description": "Email.", "example": "kumasi@kenteprints.com" }, "address": { "type": "string", "description": "Street address.", "example": "Shop 14, Kumasi City Mall" }, "town": { "type": "string", "description": "Town or city.", "example": "Kumasi" }, "is_default": { "type": "boolean", "description": "Default branch for new records.", "example": false }, "active": { "type": "boolean", "description": "Whether the branch is in use.", "example": true } } }, "example": { "name": "Kumasi Mall", "code": "KSI", "phone": "0322000111", "email": "kumasi@kenteprints.com", "address": "Shop 14, Kumasi City Mall", "town": "Kumasi", "is_default": false, "active": true } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Branches" } } }, "example": { "ok": true, "data": { "id": 3, "name": "Kumasi Mall", "code": "KSI", "phone": "0322000111", "email": "kumasi@kenteprints.com", "address": "Shop 14, Kumasi City Mall", "town": "Kumasi", "is_default": false, "active": true, "created_at": "2026-05-11 12:00:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Branches" ], "summary": "Delete a branch", "operationId": "branchesDeleteId", "description": "If the default branch is deleted another becomes the default. The last branch is recreated automatically.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Branches ID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/users": { "get": { "tags": [ "Users (team)" ], "summary": "List team members", "operationId": "usersGet", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "q", "in": "query", "description": "Search name, email or phone.", "schema": { "type": "string" } }, { "name": "role", "in": "query", "description": "Only this role.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Users" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "ok": true, "data": [ { "id": 77, "first_name": "Esi", "last_name": "Mensah", "email": "esi@kenteprints.com", "phone": "0201234567", "role": "manager", "role_label": "Manager", "branch_id": 1, "active": true, "invite_pending": false } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Users (team)" ], "summary": "Invite a team member", "operationId": "usersPost", "description": "Sends an invitation email. \"invite_sent\" in the response is false if the email could not be delivered (the user is still created).", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "description": "First name.", "example": "Esi" }, "last_name": { "type": "string", "description": "Last name.", "example": "Mensah" }, "email": { "type": "string", "description": "Email (the invite is sent here). Unique per workspace.", "example": "esi@kenteprints.com" }, "phone": { "type": "string", "description": "Phone. Unique per workspace.", "example": "0201234567" }, "role": { "type": "string", "description": "Role key (see /roles), e.g. admin, manager, accountant, sales, production, viewer.", "example": "manager" }, "branch_id": { "type": "integer", "description": "Home branch (see /branches).", "example": 1 }, "active": { "type": "boolean", "description": "Can sign in. Invited users become active after accepting.", "example": true } }, "required": [ "first_name", "last_name", "email" ] }, "example": { "first_name": "Esi", "last_name": "Mensah", "email": "esi@kenteprints.com", "phone": "0201234567", "role": "manager", "branch_id": 1, "active": true } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Users" } } }, "example": { "ok": true, "data": { "id": 77, "first_name": "Esi", "last_name": "Mensah", "email": "esi@kenteprints.com", "phone": "0201234567", "role": "manager", "role_label": "Manager", "branch_id": 1, "active": true, "invite_pending": false } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/users/{id}": { "get": { "tags": [ "Users (team)" ], "summary": "Get a team member", "operationId": "usersGetId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Users (team) ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Users" } } }, "example": { "ok": true, "data": { "id": 77, "first_name": "Esi", "last_name": "Mensah", "email": "esi@kenteprints.com", "phone": "0201234567", "role": "manager", "role_label": "Manager", "branch_id": 1, "active": true, "invite_pending": false } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "tags": [ "Users (team)" ], "summary": "Update a team member", "operationId": "usersPatchId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Users (team) ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "description": "First name.", "example": "Esi" }, "last_name": { "type": "string", "description": "Last name.", "example": "Mensah" }, "email": { "type": "string", "description": "Email (the invite is sent here). Unique per workspace.", "example": "esi@kenteprints.com" }, "phone": { "type": "string", "description": "Phone. Unique per workspace.", "example": "0201234567" }, "role": { "type": "string", "description": "Role key (see /roles), e.g. admin, manager, accountant, sales, production, viewer.", "example": "manager" }, "branch_id": { "type": "integer", "description": "Home branch (see /branches).", "example": 1 }, "active": { "type": "boolean", "description": "Can sign in. Invited users become active after accepting.", "example": true } } }, "example": { "first_name": "Esi", "last_name": "Mensah", "email": "esi@kenteprints.com", "phone": "0201234567", "role": "manager", "branch_id": 1, "active": true } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Users" } } }, "example": { "ok": true, "data": { "id": 77, "first_name": "Esi", "last_name": "Mensah", "email": "esi@kenteprints.com", "phone": "0201234567", "role": "manager", "role_label": "Manager", "branch_id": 1, "active": true, "invite_pending": false } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Users (team)" ], "summary": "Remove a team member", "operationId": "usersDeleteId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Users (team) ID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/roles": { "get": { "tags": [ "Roles & privileges" ], "summary": "List roles with privileges", "operationId": "rolesGet", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Roles" } } } }, "example": { "ok": true, "data": [ { "key": "manager", "label": "Front desk", "summary": "Clients, invoices and POS only.", "custom": false, "locked": false, "user_count": 3, "privileges": { "invoices": { "view": true, "add": true, "update": true, "delete": false } } } ] } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Roles & privileges" ], "summary": "Create a custom role", "operationId": "rolesPost", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "Role name.", "example": "Front desk" }, "summary": { "type": "string", "description": "Short description.", "example": "Clients, invoices and POS only." }, "privileges": { "type": "object", "description": "module key => {view, add, update, delete}. On create/update, only modules you pass are changed.", "example": { "invoices": { "view": true, "add": true, "update": true, "delete": false } } } }, "required": [ "label" ] }, "example": { "label": "Front desk", "summary": "Clients, invoices and POS only.", "privileges": { "invoices": { "view": true, "add": true, "update": true, "delete": false } } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Roles" } } }, "example": { "ok": true, "data": { "key": "manager", "label": "Front desk", "summary": "Clients, invoices and POS only.", "custom": false, "locked": false, "user_count": 3, "privileges": { "invoices": { "view": true, "add": true, "update": true, "delete": false } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/roles/modules": { "get": { "tags": [ "Roles & privileges" ], "summary": "List modules that privileges apply to", "operationId": "rolesGetModules", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RoleModule" } } } }, "example": { "ok": true, "data": [ { "key": "invoices", "label": "Invoices", "industry": false } ] } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/roles/{key}": { "get": { "tags": [ "Roles & privileges" ], "summary": "Get a role", "operationId": "rolesGetKey", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Key.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Roles" } } }, "example": { "ok": true, "data": { "key": "manager", "label": "Front desk", "summary": "Clients, invoices and POS only.", "custom": false, "locked": false, "user_count": 3, "privileges": { "invoices": { "view": true, "add": true, "update": true, "delete": false } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "tags": [ "Roles & privileges" ], "summary": "Change a role's privileges", "operationId": "rolesPatchKey", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Key.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "privileges": { "type": "object", "description": "module key => {view, add, update, delete}.", "example": { "reports": { "view": true } } } }, "required": [ "privileges" ] }, "example": { "privileges": { "reports": { "view": true } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Roles" } } }, "example": { "ok": true, "data": { "key": "manager", "label": "Front desk", "summary": "Clients, invoices and POS only.", "custom": false, "locked": false, "user_count": 3, "privileges": { "invoices": { "view": true, "add": true, "update": true, "delete": false } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Roles & privileges" ], "summary": "Delete a custom role", "operationId": "rolesDeleteKey", "description": "Refused with 409 while users still have the role.", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Key.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/recipes": { "get": { "tags": [ "Recipes" ], "summary": "List recipes", "operationId": "recipesGet", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "q", "in": "query", "description": "Search name.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "name (default), -created_at.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Recipes" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "ok": true, "data": [ { "id": 41, "name": "Jollof rice (party pack)", "notes": "Parboil rice 10 min before adding stew.", "yield_qty": 10, "yield_unit": "portion", "menu_product_id": 120, "ingredients": [ { "product_id": 61, "name": "Water", "qty": 2.5, "unit": "kg" } ], "bases": [ { "recipe_id": 12, "variation_id": 0, "qty": 1, "unit": "portion" } ], "variations": [], "cost": 182.5, "cost_per_unit": 18.25, "publish_to_menu": false, "menu_price": 35, "menu_category_id": 3, "created_at": "2026-09-30 12:00:00" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Recipes" ], "summary": "Create a recipe", "operationId": "recipesPost", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Recipe name.", "example": "Jollof rice (party pack)" }, "notes": { "type": "string", "description": "Method / notes.", "example": "Parboil rice 10 min before adding stew." }, "yield_qty": { "type": "number", "description": "How much one batch makes.", "example": 10 }, "yield_unit": { "type": "string", "description": "Yield unit (portion, kg, l, pcs…).", "example": "portion" }, "ingredients": { "type": "array", "items": { "$ref": "#/components/schemas/RecipeIngredient" }, "description": "Ingredients (at least one ingredient or base).", "example": [] }, "bases": { "type": "array", "items": { "$ref": "#/components/schemas/RecipeBase" }, "description": "Base recipes used inside this recipe.", "example": [] }, "publish_to_menu": { "type": "boolean", "description": "Create/refresh a sellable menu item (create only).", "example": false }, "menu_price": { "type": "number", "description": "Selling price for the menu item (with publish_to_menu).", "example": 35 }, "menu_category_id": { "type": "integer", "description": "Catalogue category for the menu item.", "example": 3 } }, "required": [ "name", "ingredients" ] }, "example": { "name": "Jollof rice (party pack)", "notes": "Parboil rice 10 min before adding stew.", "yield_qty": 10, "yield_unit": "portion", "ingredients": [ { "product_id": 61, "name": "Water", "qty": 2.5, "unit": "kg" } ], "bases": [ { "recipe_id": 12, "variation_id": 0, "qty": 1, "unit": "portion" } ], "publish_to_menu": false, "menu_price": 35, "menu_category_id": 3 } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Recipes" } } }, "example": { "ok": true, "data": { "id": 41, "name": "Jollof rice (party pack)", "notes": "Parboil rice 10 min before adding stew.", "yield_qty": 10, "yield_unit": "portion", "menu_product_id": 120, "ingredients": [ { "product_id": 61, "name": "Water", "qty": 2.5, "unit": "kg" } ], "bases": [ { "recipe_id": 12, "variation_id": 0, "qty": 1, "unit": "portion" } ], "variations": [], "cost": 182.5, "cost_per_unit": 18.25, "publish_to_menu": false, "menu_price": 35, "menu_category_id": 3, "created_at": "2026-09-30 12:00:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/recipes/{id}": { "get": { "tags": [ "Recipes" ], "summary": "Get a recipe with ingredients and cost", "operationId": "recipesGetId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Recipes ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Recipes" } } }, "example": { "ok": true, "data": { "id": 41, "name": "Jollof rice (party pack)", "notes": "Parboil rice 10 min before adding stew.", "yield_qty": 10, "yield_unit": "portion", "menu_product_id": 120, "ingredients": [ { "product_id": 61, "name": "Water", "qty": 2.5, "unit": "kg" } ], "bases": [ { "recipe_id": 12, "variation_id": 0, "qty": 1, "unit": "portion" } ], "variations": [], "cost": 182.5, "cost_per_unit": 18.25, "publish_to_menu": false, "menu_price": 35, "menu_category_id": 3, "created_at": "2026-09-30 12:00:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "tags": [ "Recipes" ], "summary": "Update a recipe", "operationId": "recipesPatchId", "description": "Passing ingredients or bases replaces that list. Sizes and cost add-ons are not changed.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Recipes ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Recipe name.", "example": "Jollof rice (party pack)" }, "notes": { "type": "string", "description": "Method / notes.", "example": "Parboil rice 10 min before adding stew." }, "yield_qty": { "type": "number", "description": "How much one batch makes.", "example": 10 }, "yield_unit": { "type": "string", "description": "Yield unit (portion, kg, l, pcs…).", "example": "portion" }, "ingredients": { "type": "array", "items": { "$ref": "#/components/schemas/RecipeIngredient" }, "description": "Ingredients (at least one ingredient or base).", "example": [] }, "bases": { "type": "array", "items": { "$ref": "#/components/schemas/RecipeBase" }, "description": "Base recipes used inside this recipe.", "example": [] }, "publish_to_menu": { "type": "boolean", "description": "Create/refresh a sellable menu item (create only).", "example": false }, "menu_price": { "type": "number", "description": "Selling price for the menu item (with publish_to_menu).", "example": 35 }, "menu_category_id": { "type": "integer", "description": "Catalogue category for the menu item.", "example": 3 } } }, "example": { "name": "Jollof rice (party pack)", "notes": "Parboil rice 10 min before adding stew.", "yield_qty": 10, "yield_unit": "portion", "ingredients": [ { "product_id": 61, "name": "Water", "qty": 2.5, "unit": "kg" } ], "bases": [ { "recipe_id": 12, "variation_id": 0, "qty": 1, "unit": "portion" } ], "publish_to_menu": false, "menu_price": 35, "menu_category_id": 3 } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Recipes" } } }, "example": { "ok": true, "data": { "id": 41, "name": "Jollof rice (party pack)", "notes": "Parboil rice 10 min before adding stew.", "yield_qty": 10, "yield_unit": "portion", "menu_product_id": 120, "ingredients": [ { "product_id": 61, "name": "Water", "qty": 2.5, "unit": "kg" } ], "bases": [ { "recipe_id": 12, "variation_id": 0, "qty": 1, "unit": "portion" } ], "variations": [], "cost": 182.5, "cost_per_unit": 18.25, "publish_to_menu": false, "menu_price": 35, "menu_category_id": 3, "created_at": "2026-09-30 12:00:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Recipes" ], "summary": "Delete a recipe", "operationId": "recipesDeleteId", "description": "Also removes its sizes and any menu-item variations linked to it.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Recipes ID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/recipes/{id}/cost": { "get": { "tags": [ "Recipes" ], "summary": "Get the current cost of a recipe", "operationId": "recipesGetIdCost", "description": "Batch cost, cost per unit and the cost of each size, priced from current stock costs.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Recipes ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Recipes" } } }, "example": { "ok": true, "data": { "id": 41, "name": "Jollof rice (party pack)", "notes": "Parboil rice 10 min before adding stew.", "yield_qty": 10, "yield_unit": "portion", "menu_product_id": 120, "ingredients": [ { "product_id": 61, "name": "Water", "qty": 2.5, "unit": "kg" } ], "bases": [ { "recipe_id": 12, "variation_id": 0, "qty": 1, "unit": "portion" } ], "variations": [], "cost": 182.5, "cost_per_unit": 18.25, "publish_to_menu": false, "menu_price": 35, "menu_category_id": 3, "created_at": "2026-09-30 12:00:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/stores": { "get": { "tags": [ "Online stores" ], "summary": "List stores", "operationId": "storesGet", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Stores" } } } }, "example": { "ok": true, "data": [ { "id": 2, "name": "Kente Prints Shop", "description": "Custom T-shirts, banners and souvenirs.", "phone": "0244000111", "email": "shop@kenteprints.com", "slug": "kente-prints", "public_url": "https://blueq.app/link/store/kente-prints", "template": "classic", "active": true, "paystack_connected": true, "product_count": 48, "settings": { "checkout_payment": "paystack", "pickup_enabled": true, "delivery_enabled": true, "send_receipt": true, "tax_group_id": null }, "created_at": "2026-08-02 10:00:00" } ] } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Online stores" ], "summary": "Create a store", "operationId": "storesPost", "description": "The first store automatically lists every sellable product.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Store name (at least 5 characters).", "example": "Kente Prints Shop" }, "description": { "type": "string", "description": "Shown on the storefront.", "example": "Custom T-shirts, banners and souvenirs." }, "phone": { "type": "string", "description": "Contact phone.", "example": "0244000111" }, "email": { "type": "string", "description": "Contact email.", "example": "shop@kenteprints.com" }, "slug": { "type": "string", "description": "Link name in the public URL (unique, at least 5 characters).", "example": "kente-prints" }, "template": { "type": "string", "description": "classic, market or list.", "example": "classic" }, "active": { "type": "boolean", "description": "Store is online.", "example": true }, "settings": { "type": "object", "description": "Checkout settings: checkout_payment (\"paystack\" or \"place\"), pickup_enabled, delivery_enabled, create_orders, pos_create_orders, send_receipt, reset_order_daily, tax_group_id, payment_note.", "example": { "checkout_payment": "paystack", "pickup_enabled": true, "delivery_enabled": true, "send_receipt": true, "tax_group_id": null } } }, "required": [ "name" ] }, "example": { "name": "Kente Prints Shop", "description": "Custom T-shirts, banners and souvenirs.", "phone": "0244000111", "email": "shop@kenteprints.com", "slug": "kente-prints", "template": "classic", "active": true, "settings": { "checkout_payment": "paystack", "pickup_enabled": true, "delivery_enabled": true, "send_receipt": true, "tax_group_id": null } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Stores" } } }, "example": { "ok": true, "data": { "id": 2, "name": "Kente Prints Shop", "description": "Custom T-shirts, banners and souvenirs.", "phone": "0244000111", "email": "shop@kenteprints.com", "slug": "kente-prints", "public_url": "https://blueq.app/link/store/kente-prints", "template": "classic", "active": true, "paystack_connected": true, "product_count": 48, "settings": { "checkout_payment": "paystack", "pickup_enabled": true, "delivery_enabled": true, "send_receipt": true, "tax_group_id": null }, "created_at": "2026-08-02 10:00:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/stores/{id}": { "get": { "tags": [ "Online stores" ], "summary": "Get a store", "operationId": "storesGetId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Online stores ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Stores" } } }, "example": { "ok": true, "data": { "id": 2, "name": "Kente Prints Shop", "description": "Custom T-shirts, banners and souvenirs.", "phone": "0244000111", "email": "shop@kenteprints.com", "slug": "kente-prints", "public_url": "https://blueq.app/link/store/kente-prints", "template": "classic", "active": true, "paystack_connected": true, "product_count": 48, "settings": { "checkout_payment": "paystack", "pickup_enabled": true, "delivery_enabled": true, "send_receipt": true, "tax_group_id": null }, "created_at": "2026-08-02 10:00:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "tags": [ "Online stores" ], "summary": "Update a store", "operationId": "storesPatchId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Online stores ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Store name (at least 5 characters).", "example": "Kente Prints Shop" }, "description": { "type": "string", "description": "Shown on the storefront.", "example": "Custom T-shirts, banners and souvenirs." }, "phone": { "type": "string", "description": "Contact phone.", "example": "0244000111" }, "email": { "type": "string", "description": "Contact email.", "example": "shop@kenteprints.com" }, "slug": { "type": "string", "description": "Link name in the public URL (unique, at least 5 characters).", "example": "kente-prints" }, "template": { "type": "string", "description": "classic, market or list.", "example": "classic" }, "active": { "type": "boolean", "description": "Store is online.", "example": true }, "settings": { "type": "object", "description": "Checkout settings: checkout_payment (\"paystack\" or \"place\"), pickup_enabled, delivery_enabled, create_orders, pos_create_orders, send_receipt, reset_order_daily, tax_group_id, payment_note.", "example": { "checkout_payment": "paystack", "pickup_enabled": true, "delivery_enabled": true, "send_receipt": true, "tax_group_id": null } } } }, "example": { "name": "Kente Prints Shop", "description": "Custom T-shirts, banners and souvenirs.", "phone": "0244000111", "email": "shop@kenteprints.com", "slug": "kente-prints", "template": "classic", "active": true, "settings": { "checkout_payment": "paystack", "pickup_enabled": true, "delivery_enabled": true, "send_receipt": true, "tax_group_id": null } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Stores" } } }, "example": { "ok": true, "data": { "id": 2, "name": "Kente Prints Shop", "description": "Custom T-shirts, banners and souvenirs.", "phone": "0244000111", "email": "shop@kenteprints.com", "slug": "kente-prints", "public_url": "https://blueq.app/link/store/kente-prints", "template": "classic", "active": true, "paystack_connected": true, "product_count": 48, "settings": { "checkout_payment": "paystack", "pickup_enabled": true, "delivery_enabled": true, "send_receipt": true, "tax_group_id": null }, "created_at": "2026-08-02 10:00:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Online stores" ], "summary": "Take a store offline", "operationId": "storesDeleteId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Online stores ID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/stores/{id}/products": { "get": { "tags": [ "Online stores" ], "summary": "List products in a store", "operationId": "storesGetIdProducts", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Online stores ID.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Stores" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "ok": true, "data": [ { "id": 2, "name": "Kente Prints Shop", "description": "Custom T-shirts, banners and souvenirs.", "phone": "0244000111", "email": "shop@kenteprints.com", "slug": "kente-prints", "public_url": "https://blueq.app/link/store/kente-prints", "template": "classic", "active": true, "paystack_connected": true, "product_count": 48, "settings": { "checkout_payment": "paystack", "pickup_enabled": true, "delivery_enabled": true, "send_receipt": true, "tax_group_id": null }, "created_at": "2026-08-02 10:00:00" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Online stores" ], "summary": "Add products to a store", "operationId": "storesPostIdProducts", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Online stores ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_ids": { "type": "array", "items": { "type": "integer" }, "description": "Sellable catalogue products.", "example": [ 57, 58 ] } }, "required": [ "product_ids" ] }, "example": { "product_ids": [ 57, 58 ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Stores" } } }, "example": { "ok": true, "data": { "id": 2, "name": "Kente Prints Shop", "description": "Custom T-shirts, banners and souvenirs.", "phone": "0244000111", "email": "shop@kenteprints.com", "slug": "kente-prints", "public_url": "https://blueq.app/link/store/kente-prints", "template": "classic", "active": true, "paystack_connected": true, "product_count": 48, "settings": { "checkout_payment": "paystack", "pickup_enabled": true, "delivery_enabled": true, "send_receipt": true, "tax_group_id": null }, "created_at": "2026-08-02 10:00:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/stores/{id}/products/{product_id}": { "delete": { "tags": [ "Online stores" ], "summary": "Remove a product from a store", "operationId": "storesDeleteIdProductsProductId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Online stores ID.", "schema": { "type": "string" } }, { "name": "product_id", "in": "path", "required": true, "description": "Product id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/store-orders": { "get": { "tags": [ "Store & walk-in orders" ], "summary": "List orders", "operationId": "storeOrdersGet", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "store_id", "in": "query", "description": "Only this store.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "pending, paid, failed or open (paid, not picked up).", "schema": { "type": "string" } }, { "name": "channel", "in": "query", "description": "online or walkin.", "schema": { "type": "string" } }, { "name": "payment_mode", "in": "query", "description": "Paystack, Cash, Mobile Money, Card, Place order.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Search number, receipt, customer or reference.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Order date on/after.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Order date on/before.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/StoreOrders" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "ok": true, "data": [ { "id": 9031, "store_id": 2, "number": "014", "receipt_number": "R-00412", "channel": "online", "status": "paid", "payment_mode": "Paystack", "customer": { "name": "Yaw Asante", "phone": "0244111222", "email": null, "client_id": 2399 }, "fulfillment": "delivery", "delivery": { "town": "East Legon", "address": "Lagos Ave 14", "zone": "Accra East", "fee": 25 }, "subtotal": 240, "tax_total": 0, "total": 265, "picked_up": false, "sale_id": 812, "invoice_id": null, "pos_session_id": null, "items": [], "date": "2026-10-08", "created_at": "2026-10-08 09:40:00", "paid_at": "2026-10-08 09:41:12" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/store-orders/{id}": { "get": { "tags": [ "Store & walk-in orders" ], "summary": "Get an order with items", "operationId": "storeOrdersGetId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Store & walk-in orders ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/StoreOrders" } } }, "example": { "ok": true, "data": { "id": 9031, "store_id": 2, "number": "014", "receipt_number": "R-00412", "channel": "online", "status": "paid", "payment_mode": "Paystack", "customer": { "name": "Yaw Asante", "phone": "0244111222", "email": null, "client_id": 2399 }, "fulfillment": "delivery", "delivery": { "town": "East Legon", "address": "Lagos Ave 14", "zone": "Accra East", "fee": 25 }, "subtotal": 240, "tax_total": 0, "total": 265, "picked_up": false, "sale_id": 812, "invoice_id": null, "pos_session_id": null, "items": [], "date": "2026-10-08", "created_at": "2026-10-08 09:40:00", "paid_at": "2026-10-08 09:41:12" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/store-orders/{id}/picked-up": { "post": { "tags": [ "Store & walk-in orders" ], "summary": "Mark picked up / delivered", "operationId": "storeOrdersPostIdPickedUp", "description": "Only paid orders can be marked.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Store & walk-in orders ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "picked_up": { "type": "boolean", "description": "true to mark collected, false to undo.", "example": true } } }, "example": { "picked_up": true } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/StoreOrders" } } }, "example": { "ok": true, "data": { "id": 9031, "store_id": 2, "number": "014", "receipt_number": "R-00412", "channel": "online", "status": "paid", "payment_mode": "Paystack", "customer": { "name": "Yaw Asante", "phone": "0244111222", "email": null, "client_id": 2399 }, "fulfillment": "delivery", "delivery": { "town": "East Legon", "address": "Lagos Ave 14", "zone": "Accra East", "fee": 25 }, "subtotal": 240, "tax_total": 0, "total": 265, "picked_up": false, "sale_id": 812, "invoice_id": null, "pos_session_id": null, "items": [], "date": "2026-10-08", "created_at": "2026-10-08 09:40:00", "paid_at": "2026-10-08 09:41:12" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/delivery-zones": { "get": { "tags": [ "Delivery zones" ], "summary": "List delivery zones", "operationId": "deliveryZonesGet", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "store_id", "in": "query", "description": "Only this store.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryZones" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "ok": true, "data": [ { "id": 7, "store_id": 2, "name": "Accra East", "price": 25, "towns": [ "East Legon", "Madina", "Adenta" ], "created_at": "2026-08-02 10:20:00" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Delivery zones" ], "summary": "Create a zone", "operationId": "deliveryZonesPost", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "store_id": { "type": "integer", "description": "Store the zone belongs to.", "example": 2 }, "name": { "type": "string", "description": "Zone name.", "example": "Accra East" }, "price": { "type": "number", "description": "Delivery fee.", "example": 25 }, "towns": { "type": "array", "items": { "type": "string" }, "description": "Towns covered (at least one).", "example": [ "East Legon", "Madina", "Adenta" ] } }, "required": [ "store_id", "name", "price", "towns" ] }, "example": { "store_id": 2, "name": "Accra East", "price": 25, "towns": [ "East Legon", "Madina", "Adenta" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/DeliveryZones" } } }, "example": { "ok": true, "data": { "id": 7, "store_id": 2, "name": "Accra East", "price": 25, "towns": [ "East Legon", "Madina", "Adenta" ], "created_at": "2026-08-02 10:20:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/delivery-zones/{id}": { "get": { "tags": [ "Delivery zones" ], "summary": "Get a zone", "operationId": "deliveryZonesGetId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Delivery zones ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/DeliveryZones" } } }, "example": { "ok": true, "data": { "id": 7, "store_id": 2, "name": "Accra East", "price": 25, "towns": [ "East Legon", "Madina", "Adenta" ], "created_at": "2026-08-02 10:20:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "tags": [ "Delivery zones" ], "summary": "Update a zone", "operationId": "deliveryZonesPatchId", "description": "Passing towns replaces the list.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Delivery zones ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "store_id": { "type": "integer", "description": "Store the zone belongs to.", "example": 2 }, "name": { "type": "string", "description": "Zone name.", "example": "Accra East" }, "price": { "type": "number", "description": "Delivery fee.", "example": 25 }, "towns": { "type": "array", "items": { "type": "string" }, "description": "Towns covered (at least one).", "example": [ "East Legon", "Madina", "Adenta" ] } } }, "example": { "store_id": 2, "name": "Accra East", "price": 25, "towns": [ "East Legon", "Madina", "Adenta" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/DeliveryZones" } } }, "example": { "ok": true, "data": { "id": 7, "store_id": 2, "name": "Accra East", "price": 25, "towns": [ "East Legon", "Madina", "Adenta" ], "created_at": "2026-08-02 10:20:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Delivery zones" ], "summary": "Delete a zone", "operationId": "deliveryZonesDeleteId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Delivery zones ID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/store-accounts": { "get": { "tags": [ "Store customer accounts" ], "summary": "List customer accounts", "operationId": "storeAccountsGet", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "q", "in": "query", "description": "Search email, name or phone.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Registered on/after.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Registered on/before.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/StoreAccounts" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "ok": true, "data": [ { "id": 311, "email": "yaw.asante@example.com", "name": "Yaw Asante", "phone": "0244111222", "order_count": 4, "created_at": "2026-09-01 18:30:00" } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/store-accounts/{id}": { "get": { "tags": [ "Store customer accounts" ], "summary": "Get a customer account", "operationId": "storeAccountsGetId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Store customer accounts ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/StoreAccounts" } } }, "example": { "ok": true, "data": { "id": 311, "email": "yaw.asante@example.com", "name": "Yaw Asante", "phone": "0244111222", "order_count": 4, "created_at": "2026-09-01 18:30:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "tags": [ "Store customer accounts" ], "summary": "Update name or phone", "operationId": "storeAccountsPatchId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Store customer accounts ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Full name.", "example": "Yaw Asante" }, "phone": { "type": "string", "description": "Phone.", "example": "0244111222" } } }, "example": { "name": "Yaw Asante", "phone": "0244111222" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/StoreAccounts" } } }, "example": { "ok": true, "data": { "id": 311, "email": "yaw.asante@example.com", "name": "Yaw Asante", "phone": "0244111222", "order_count": 4, "created_at": "2026-09-01 18:30:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Store customer accounts" ], "summary": "Delete a customer account", "operationId": "storeAccountsDeleteId", "description": "Past orders are kept.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Store customer accounts ID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/pos/register": { "get": { "tags": [ "POS (point of sale)" ], "summary": "Get the till register", "operationId": "posGetRegister", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/PosRegister" } } }, "example": { "ok": true, "data": { "name": "Front counter", "phone": "0302000111", "email": "counter@kenteprints.com", "address": "Osu, Oxford St.", "active": true, "store_id": 2, "tax_group_id": 0 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "put": { "tags": [ "POS (point of sale)" ], "summary": "Create or update the till register", "operationId": "posPutRegister", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Till name shown on receipts.", "example": "Front counter" }, "phone": { "type": "string", "description": "Receipt phone.", "example": "0302000111" }, "email": { "type": "string", "description": "Receipt email.", "example": "counter@kenteprints.com" }, "address": { "type": "string", "description": "Receipt address.", "example": "Osu, Oxford St." }, "active": { "type": "boolean", "description": "Till can take sales.", "example": true }, "store_id": { "type": "integer", "description": "Store whose products and order numbers the till uses.", "example": 2 }, "tax_group_id": { "type": "integer", "description": "Tax group applied to sales (0 = none).", "example": 0 } }, "required": [ "name" ] }, "example": { "name": "Front counter", "phone": "0302000111", "email": "counter@kenteprints.com", "address": "Osu, Oxford St.", "active": true, "store_id": 2, "tax_group_id": 0 } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/PosRegister" } } }, "example": { "ok": true, "data": { "name": "Front counter", "phone": "0302000111", "email": "counter@kenteprints.com", "address": "Osu, Oxford St.", "active": true, "store_id": 2, "tax_group_id": 0 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/pos/sessions": { "get": { "tags": [ "POS (point of sale)" ], "summary": "List cashier sessions", "operationId": "posGetSessions", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "status", "in": "query", "description": "open, pending, approved or rejected.", "schema": { "type": "string" } }, { "name": "cashier_id", "in": "query", "description": "Only this cashier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Pos" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "ok": true, "data": [ { "id": 140, "cashier_id": 77, "cashier_name": "Esi Mensah", "status": "open", "sale_count": 23, "total": 1840.5, "opened_at": "2026-10-08 07:58:00", "closed_at": null, "review_note": null, "reviewed_at": null } ], "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "POS (point of sale)" ], "summary": "Open a cashier session", "operationId": "posPostSessions", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cashier_id": { "type": "integer", "description": "Cashier (default: owner). Returns the existing open session if there is one.", "example": 77 } } }, "example": { "cashier_id": 77 } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Pos" } } }, "example": { "ok": true, "data": { "id": 140, "cashier_id": 77, "cashier_name": "Esi Mensah", "status": "open", "sale_count": 23, "total": 1840.5, "opened_at": "2026-10-08 07:58:00", "closed_at": null, "review_note": null, "reviewed_at": null } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/pos/sessions/{id}": { "get": { "tags": [ "POS (point of sale)" ], "summary": "Get a session with its sales", "operationId": "posGetSessionsId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "POS (point of sale) ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Pos" } } }, "example": { "ok": true, "data": { "id": 140, "cashier_id": 77, "cashier_name": "Esi Mensah", "status": "open", "sale_count": 23, "total": 1840.5, "opened_at": "2026-10-08 07:58:00", "closed_at": null, "review_note": null, "reviewed_at": null } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/pos/sessions/{id}/close": { "post": { "tags": [ "POS (point of sale)" ], "summary": "Close a session for review", "operationId": "posPostSessionsIdClose", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "POS (point of sale) ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Pos" } } }, "example": { "ok": true, "data": { "id": 140, "cashier_id": 77, "cashier_name": "Esi Mensah", "status": "open", "sale_count": 23, "total": 1840.5, "opened_at": "2026-10-08 07:58:00", "closed_at": null, "review_note": null, "reviewed_at": null } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/pos/sessions/{id}/review": { "post": { "tags": [ "POS (point of sale)" ], "summary": "Approve or reject a closed session", "operationId": "posPostSessionsIdReview", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "POS (point of sale) ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "description": "approved or rejected.", "example": "approved" }, "note": { "type": "string", "description": "Required when rejecting.", "example": "" } }, "required": [ "decision" ] }, "example": { "decision": "approved", "note": "" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Pos" } } }, "example": { "ok": true, "data": { "id": 140, "cashier_id": 77, "cashier_name": "Esi Mensah", "status": "open", "sale_count": 23, "total": 1840.5, "opened_at": "2026-10-08 07:58:00", "closed_at": null, "review_note": null, "reviewed_at": null } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/pos/sales": { "post": { "tags": [ "POS (point of sale)" ], "summary": "Record a walk-in sale", "operationId": "posPostSales", "description": "Fails with 422 if the cashier has no open session, the register is inactive, or stock is insufficient. Send an Idempotency-Key so a retried request never charges twice.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cashier_id": { "type": "integer", "description": "Cashier with an open session (default: owner).", "example": 77 }, "items": { "type": "array", "items": { "type": "object" }, "description": "Lines: {\"product_id\": 57, \"qty\": 2}. Prices come from the catalogue.", "example": [ { "product_id": 57, "qty": 2 } ] }, "payment_mode": { "type": "string", "description": "Cash, Mobile Money or Card.", "example": "Cash" }, "customer_name": { "type": "string", "description": "Default \"Walk-in\".", "example": "Walk-in" }, "customer_phone": { "type": "string", "description": "Receipt SMS number.", "example": "" } }, "required": [ "items", "payment_mode" ] }, "example": { "cashier_id": 77, "items": [ { "product_id": 57, "qty": 2 } ], "payment_mode": "Cash", "customer_name": "Walk-in", "customer_phone": "" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Pos" } } }, "example": { "ok": true, "data": { "id": 140, "cashier_id": 77, "cashier_name": "Esi Mensah", "status": "open", "sale_count": 23, "total": 1840.5, "opened_at": "2026-10-08 07:58:00", "closed_at": null, "review_note": null, "reviewed_at": null } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/reports": { "get": { "tags": [ "Reports" ], "summary": "List available reports and their filters", "operationId": "reportsGet", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReportSource" } } } }, "example": { "ok": true, "data": [ { "source": "payments", "title": "Payments", "columns": [ "Date", "Client", "Invoice", "Mode", "Type", "Amount (GHS)", "Remarks" ], "charts": [ "Payments by day", "Payments by mode" ], "filters": { "from": "Start date.", "to": "End date.", "client": "Client ID.", "payment_type": "credit or debit." } } ] } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/reports/custom": { "get": { "tags": [ "Reports" ], "summary": "List saved custom reports", "operationId": "reportsGetCustom", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomReport" } } } }, "example": { "ok": true, "data": [ { "id": 6, "name": "Monthly cash view", "sections": [ { "source": "payments", "columns": [ "Date", "Client", "Amount (GHS)" ], "filters": { "payment_type": "credit" }, "chart": "" } ], "updated_at": "2026-10-01 10:12:00" } ] } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Reports" ], "summary": "Save a custom report", "operationId": "reportsPostCustom", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Report name.", "example": "Monthly cash view" }, "sections": { "type": "array", "items": { "type": "object" }, "description": "Datasets: {\"source\":\"payments\",\"columns\":[\"Date\",\"Amount (GHS)\"],\"filters\":{\"payment_type\":\"credit\"},\"chart\":\"all\"}. Dates are supplied when the report is run.", "example": [ { "source": "payments", "columns": [ "Date", "Client", "Amount (GHS)" ], "filters": { "payment_type": "credit" }, "chart": "" } ] } }, "required": [ "name", "sections" ] }, "example": { "name": "Monthly cash view", "sections": [ { "source": "payments", "columns": [ "Date", "Client", "Amount (GHS)" ], "filters": { "payment_type": "credit" }, "chart": "" } ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CustomReport" } } }, "example": { "ok": true, "data": { "id": 6, "name": "Monthly cash view", "sections": [ { "source": "payments", "columns": [ "Date", "Client", "Amount (GHS)" ], "filters": { "payment_type": "credit" }, "chart": "" } ], "updated_at": "2026-10-01 10:12:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/reports/custom/{id}": { "get": { "tags": [ "Reports" ], "summary": "Get a custom report definition", "operationId": "reportsGetCustomId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Reports ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CustomReport" } } }, "example": { "ok": true, "data": { "id": 6, "name": "Monthly cash view", "sections": [ { "source": "payments", "columns": [ "Date", "Client", "Amount (GHS)" ], "filters": { "payment_type": "credit" }, "chart": "" } ], "updated_at": "2026-10-01 10:12:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "tags": [ "Reports" ], "summary": "Update a custom report", "operationId": "reportsPatchCustomId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Reports ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Report name.", "example": "Monthly cash view" }, "sections": { "type": "array", "items": { "type": "object" }, "description": "Datasets: {\"source\":\"payments\",\"columns\":[\"Date\",\"Amount (GHS)\"],\"filters\":{\"payment_type\":\"credit\"},\"chart\":\"all\"}. Dates are supplied when the report is run.", "example": [ { "source": "payments", "columns": [ "Date", "Client", "Amount (GHS)" ], "filters": { "payment_type": "credit" }, "chart": "" } ] } }, "required": [ "name", "sections" ] }, "example": { "name": "Monthly cash view", "sections": [ { "source": "payments", "columns": [ "Date", "Client", "Amount (GHS)" ], "filters": { "payment_type": "credit" }, "chart": "" } ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CustomReport" } } }, "example": { "ok": true, "data": { "id": 6, "name": "Monthly cash view", "sections": [ { "source": "payments", "columns": [ "Date", "Client", "Amount (GHS)" ], "filters": { "payment_type": "credit" }, "chart": "" } ], "updated_at": "2026-10-01 10:12:00" } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Reports" ], "summary": "Delete a custom report", "operationId": "reportsDeleteCustomId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Reports ID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/reports/custom/{id}/run": { "get": { "tags": [ "Reports" ], "summary": "Run a custom report", "operationId": "reportsGetCustomIdRun", "description": "Returns one result block (same shape as a built-in report) per section.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Reports ID.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Start date (YYYY-MM-DD).", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "End date (YYYY-MM-DD).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max rows, 1-5000 (default 1500).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Reports" } } }, "example": { "ok": true, "data": { "source": "sales", "title": "Sales", "columns": [ "Date", "Category", "Product", "Customer", "Status", "Reference", "Amount (GHS)" ], "rows": [ [ "2026-10-08", "Products", "Kente stole", "Walk-in", "Paid", "S-0812", 240 ] ], "items": [ { "date": "2026-10-08", "category": "Products", "product": "Kente stole", "customer": "Walk-in", "status": "Paid", "reference": "S-0812", "amount_ghs": 240 } ], "summary": [ { "label": "Rows", "value": "58" }, { "label": "Amount", "value": "GHS 9,420.00" } ], "total": 58, "truncated": false, "filters": { "start": "2026-10-01", "end": "2026-10-31" } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Reports" ], "summary": "Run a custom report (POST)", "operationId": "reportsPostCustomIdRun", "description": "Same as the GET form, for clients that prefer POST. Allowed on read-only keys.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Reports ID.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Start date (YYYY-MM-DD).", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "End date (YYYY-MM-DD).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max rows, 1-5000 (default 1500).", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Reports" } } }, "example": { "ok": true, "data": { "source": "sales", "title": "Sales", "columns": [ "Date", "Category", "Product", "Customer", "Status", "Reference", "Amount (GHS)" ], "rows": [ [ "2026-10-08", "Products", "Kente stole", "Walk-in", "Paid", "S-0812", 240 ] ], "items": [ { "date": "2026-10-08", "category": "Products", "product": "Kente stole", "customer": "Walk-in", "status": "Paid", "reference": "S-0812", "amount_ghs": 240 } ], "summary": [ { "label": "Rows", "value": "58" }, { "label": "Amount", "value": "GHS 9,420.00" } ], "total": 58, "truncated": false, "filters": { "start": "2026-10-01", "end": "2026-10-31" } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/reports/{source}": { "get": { "tags": [ "Reports" ], "summary": "Run a built-in report", "operationId": "reportsGetSource", "parameters": [ { "name": "source", "in": "path", "required": true, "description": "Source.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Start date (YYYY-MM-DD).", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "End date (YYYY-MM-DD).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max rows, 1-5000 (default 1500).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Reports" } } }, "example": { "ok": true, "data": { "source": "sales", "title": "Sales", "columns": [ "Date", "Category", "Product", "Customer", "Status", "Reference", "Amount (GHS)" ], "rows": [ [ "2026-10-08", "Products", "Kente stole", "Walk-in", "Paid", "S-0812", 240 ] ], "items": [ { "date": "2026-10-08", "category": "Products", "product": "Kente stole", "customer": "Walk-in", "status": "Paid", "reference": "S-0812", "amount_ghs": 240 } ], "summary": [ { "label": "Rows", "value": "58" }, { "label": "Amount", "value": "GHS 9,420.00" } ], "total": 58, "truncated": false, "filters": { "start": "2026-10-01", "end": "2026-10-31" } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/reports/{source}/charts": { "get": { "tags": [ "Reports" ], "summary": "Chart series for a report", "operationId": "reportsGetSourceCharts", "description": "Each chart has a title, type (bar, line, pie, doughnut) and labels/series ready for any chart library.", "parameters": [ { "name": "source", "in": "path", "required": true, "description": "Source.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Start date.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "End date.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Reports" } } }, "example": { "ok": true, "data": { "source": "sales", "title": "Sales", "columns": [ "Date", "Category", "Product", "Customer", "Status", "Reference", "Amount (GHS)" ], "rows": [ [ "2026-10-08", "Products", "Kente stole", "Walk-in", "Paid", "S-0812", 240 ] ], "items": [ { "date": "2026-10-08", "category": "Products", "product": "Kente stole", "customer": "Walk-in", "status": "Paid", "reference": "S-0812", "amount_ghs": 240 } ], "summary": [ { "label": "Rows", "value": "58" }, { "label": "Amount", "value": "GHS 9,420.00" } ], "total": 58, "truncated": false, "filters": { "start": "2026-10-01", "end": "2026-10-31" } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "bq_live_... or bq_test_..." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique value (e.g. a UUID). Repeating a POST with the same key within 24 hours returns the first response instead of creating a duplicate.", "schema": { "type": "string", "maxLength": 100 } } }, "responses": { "Error": { "description": "Error envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Me": { "type": "object", "properties": { "mode": { "type": "string", "description": "\"live\" for bq_live_ keys, \"sandbox\" for bq_test_ keys.", "example": "live", "readOnly": true }, "workspace_id": { "type": "integer", "description": "Workspace (tenant) ID. For sandbox keys this is the sandbox workspace.", "example": 1042, "readOnly": true }, "live_workspace_id": { "type": "integer", "description": "The real workspace. Same as workspace_id for live keys.", "example": 1042, "readOnly": true }, "business_name": { "type": "string", "description": "Business name.", "example": "Kente Prints Ltd", "readOnly": true }, "business_type": { "type": "string", "description": "Industry slug.", "example": "printing", "readOnly": true }, "owner": { "type": "object", "description": "Owner name, email and phone.", "example": { "name": "Ama Mensah", "email": "ama@kenteprints.com", "phone": "0244000000" }, "readOnly": true }, "plan": { "type": "string", "description": "Current plan name.", "example": "Pro", "readOnly": true }, "api_access": { "type": "string", "description": "\"read\" (Business) or \"full\" (Pro).", "example": "full", "readOnly": true }, "rate_limit_per_minute": { "type": "integer", "description": "Requests allowed per minute.", "example": 300, "readOnly": true }, "key_prefix": { "type": "string", "description": "First characters of the key in use.", "example": "bq_live_3f9a1c2e", "readOnly": true }, "limits": { "type": "object", "description": "Plan limits (null = unlimited).", "example": { "clients": null, "invoices": null, "sales": null, "branches": 5 }, "readOnly": true }, "usage": { "type": "object", "description": "Current usage counted against plan limits.", "example": { "clients": 182, "invoices": 940, "sales": 2210, "branches": 2 }, "readOnly": true } } }, "Clients": { "type": "object", "properties": { "id": { "type": "integer", "description": "Client ID.", "example": 2381, "readOnly": true }, "name": { "type": "string", "description": "Client or company name.", "example": "Akosua Boateng" }, "contact_person": { "type": "string", "description": "Contact person (for companies).", "example": "Kwame Boateng" }, "phone": { "type": "string", "description": "Phone number. Must be unique in the workspace.", "example": "0244123456" }, "email": { "type": "string", "description": "Email address. Must be unique in the workspace.", "example": "akosua@example.com" }, "gender": { "type": "string", "description": "\"male\" or \"female\".", "example": "female" }, "date_of_birth": { "type": "string", "format": "date", "description": "Date of birth (YYYY-MM-DD).", "example": "1992-04-18" }, "balance": { "type": "number", "description": "Account balance cache (credit on account).", "example": 0, "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "description": "When the client was added (UTC).", "example": "2026-09-14 10:22:05", "readOnly": true } } }, "Suppliers": { "type": "object", "properties": { "id": { "type": "integer", "description": "Supplier ID.", "example": 57, "readOnly": true }, "name": { "type": "string", "description": "Supplier name.", "example": "Accra Paper Mills" }, "phone": { "type": "string", "description": "Phone number.", "example": "0302123456" }, "email": { "type": "string", "description": "Email address.", "example": "sales@accrapaper.com" }, "notes": { "type": "string", "description": "Internal notes.", "example": "Delivers on Tuesdays." }, "created_at": { "type": "string", "format": "date-time", "description": "When the supplier was added (UTC).", "example": "2026-08-02 09:12:44", "readOnly": true } } }, "Products": { "type": "object", "properties": { "id": { "type": "integer", "description": "Product ID.", "example": 812, "readOnly": true }, "name": { "type": "string", "description": "Item name.", "example": "A2 Flyer (glossy)" }, "description": { "type": "string", "description": "Description shown on invoices and the store.", "example": "Full-colour, 150gsm" }, "price": { "type": "number", "description": "Selling price.", "example": 2.5 }, "category_id": { "type": "integer", "description": "Product category ID.", "example": 14 }, "kind": { "type": "string", "description": "\"product\", \"service\" or \"menu\" (from the category).", "example": "product", "readOnly": true }, "sellable": { "type": "boolean", "description": "true = catalogue item you sell; false = stock/inventory item.", "example": true }, "active": { "type": "boolean", "description": "Whether the item is active.", "example": true }, "unit": { "type": "string", "description": "Stock unit, e.g. pcs, kg, l, m.", "example": "pcs" }, "stock_qty": { "type": "number", "description": "Quantity on hand. Set on create only; use /stock/adjustments afterwards.", "example": 500 }, "reorder_level": { "type": "number", "description": "Low-stock warning level (inventory items).", "example": 50 }, "expiry_date": { "type": "string", "format": "date", "description": "Expiry date (inventory items)." }, "supplier_id": { "type": "integer", "description": "Default supplier ID.", "example": 57 }, "supplier_cost": { "type": "number", "description": "Cost price from the supplier.", "example": 1.1 }, "variations": { "type": "array", "items": { "type": "object" }, "description": "Sizes/options: [{id, label, price, stock_qty}]. Send on create to add variations.", "example": [ { "id": 813, "label": "Pack of 100", "price": 220, "stock_qty": 20 } ] }, "created_at": { "type": "string", "format": "date-time", "description": "When the item was added (UTC).", "example": "2026-07-20 15:40:11", "readOnly": true } } }, "ProductCategories": { "type": "object", "properties": { "id": { "type": "integer", "description": "Category ID.", "example": 14, "readOnly": true }, "name": { "type": "string", "description": "Category name.", "example": "Banners" }, "kind": { "type": "string", "description": "\"product\", \"service\" or \"menu\".", "example": "product" }, "store_visible": { "type": "boolean", "description": "Shown on the online store.", "example": true }, "product_count": { "type": "integer", "description": "Items in this category.", "example": 12, "readOnly": true } } }, "Stock": { "type": "object", "properties": { "product_id": { "type": "integer", "description": "Product ID.", "example": 812, "readOnly": true }, "name": { "type": "string", "description": "Item name.", "example": "A2 Flyer paper", "readOnly": true }, "unit": { "type": "string", "description": "Stock unit.", "example": "pcs", "readOnly": true }, "stock_qty": { "type": "number", "description": "Quantity on hand.", "example": 480, "readOnly": true }, "reorder_level": { "type": "number", "description": "Low-stock level.", "example": 50, "readOnly": true }, "low_stock": { "type": "boolean", "description": "true when stock_qty is at or below reorder_level.", "example": false, "readOnly": true }, "sellable": { "type": "boolean", "description": "Catalogue item (true) or inventory item (false).", "example": false, "readOnly": true }, "unit_cost": { "type": "number", "description": "Supplier cost per unit, if known.", "example": 1.1, "readOnly": true }, "stock_value": { "type": "number", "description": "stock_qty x unit_cost.", "example": 528, "readOnly": true } } }, "StockMovement": { "type": "object", "properties": { "id": { "type": "integer", "description": "Movement ID.", "example": 3301, "readOnly": true }, "product_id": { "type": "integer", "description": "Product ID.", "example": 812, "readOnly": true }, "name": { "type": "string", "description": "Item name at the time.", "example": "A2 Flyer paper", "readOnly": true }, "type": { "type": "string", "description": "add, discard, edit or create.", "example": "add", "readOnly": true }, "reason": { "type": "string", "description": "Discard reason: expired, broken, obsolete.", "readOnly": true }, "qty": { "type": "number", "description": "Quantity changed.", "example": 100, "readOnly": true }, "qty_before": { "type": "number", "description": "Quantity before.", "example": 380, "readOnly": true }, "qty_after": { "type": "number", "description": "Quantity after (null while pending).", "example": 480, "readOnly": true }, "status": { "type": "string", "description": "pending, approved or rejected.", "example": "approved", "readOnly": true }, "note": { "type": "string", "description": "Note.", "example": "Delivery from Accra Paper Mills", "readOnly": true }, "requested_by": { "type": "string", "description": "Who requested it.", "example": "API", "readOnly": true }, "requested_at": { "type": "string", "format": "date-time", "description": "When (UTC).", "example": "2026-10-02 08:15:00", "readOnly": true } } }, "Invoices": { "type": "object", "properties": { "id": { "type": "string", "description": "Invoice ID (used in URLs and public links).", "example": "66f1c2a9e4b1d", "readOnly": true }, "number": { "type": "string", "description": "Invoice number, generated automatically.", "example": "0042-37-1026", "readOnly": true }, "title": { "type": "string", "description": "Invoice title / subject.", "example": "Branded T-shirts — October order" }, "client_id": { "type": "integer", "description": "Client the invoice is billed to.", "example": 2381 }, "type": { "type": "string", "description": "\"proforma\", \"invoice\" or \"receipt\".", "example": "invoice", "readOnly": true }, "status": { "type": "string", "description": "\"open\", \"completed\" or \"discarded\".", "example": "open", "readOnly": true }, "confirmed": { "type": "boolean", "description": "Whether the proforma has been confirmed into an invoice.", "example": true, "readOnly": true }, "date": { "type": "string", "format": "date", "description": "Invoice date (YYYY-MM-DD).", "example": "2026-10-08" }, "due_date": { "type": "string", "format": "date", "description": "Payment due / quote expiry date.", "example": "2026-10-22" }, "tax_group_id": { "type": "integer", "description": "Tax group applied (see /tax-groups). Omit for the default group.", "example": 1 }, "discount_type": { "type": "string", "description": "\"amount\" or \"percent\".", "example": "percent" }, "discount_value": { "type": "number", "description": "Discount amount or percentage.", "example": 5 }, "subtotal": { "type": "number", "description": "Sum of line items.", "example": 1200, "readOnly": true }, "discount": { "type": "number", "description": "Discount applied.", "example": 60, "readOnly": true }, "tax_total": { "type": "number", "description": "Levies + VAT.", "example": 199.5, "readOnly": true }, "total": { "type": "number", "description": "Grand total.", "example": 1339.5, "readOnly": true }, "paid": { "type": "number", "description": "Payments received.", "example": 500, "readOnly": true }, "balance_due": { "type": "number", "description": "total − paid.", "example": 839.5, "readOnly": true }, "orders_created": { "type": "boolean", "description": "Production orders have been created from this invoice.", "example": false, "readOnly": true }, "public_url": { "type": "string", "description": "Client-facing link (works once sharing is enabled).", "example": "https://blueq.app/link/invoice/66f1c2a9e4b1d", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "description": "Created (UTC).", "example": "2026-10-08 09:14:00", "readOnly": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceItem" }, "description": "Line items (detail view and create).", "example": [] } } }, "InvoiceItem": { "type": "object", "properties": { "id": { "type": "integer", "description": "Line item ID.", "example": 9811, "readOnly": true }, "product_id": { "type": "integer", "description": "Catalogue product/service, or null for a custom line.", "example": 57 }, "name": { "type": "string", "description": "Line name. Defaults to the product name.", "example": "Round-neck T-shirt (L)" }, "description": { "type": "string", "description": "Extra detail shown under the name.", "example": "Navy, 2-colour print front" }, "qty": { "type": "number", "description": "Quantity (default 1).", "example": 40 }, "unit_price": { "type": "number", "description": "Unit price. Defaults to the product price.", "example": 30 }, "amount": { "type": "number", "description": "qty × unit_price.", "example": 1200, "readOnly": true } } }, "InvoicePayment": { "type": "object", "properties": { "id": { "type": "integer", "description": "Payment ID.", "example": 4410, "readOnly": true }, "amount": { "type": "number", "description": "Amount received.", "example": 500 }, "mode": { "type": "string", "description": "cash, momo, cheque, bank, card, credit (from account balance) or a custom mode.", "example": "momo" }, "date": { "type": "string", "format": "date", "description": "Payment date (default today).", "example": "2026-10-08" }, "remarks": { "type": "string", "description": "Reference or note.", "example": "MoMo ref 77812" } } }, "InvoiceReminder": { "type": "object", "properties": { "id": { "type": "integer", "description": "Reminder ID.", "example": 18, "readOnly": true }, "remind_at": { "type": "string", "format": "date-time", "description": "When to send (YYYY-MM-DD HH:MM, workspace time).", "example": "2026-10-20 09:00" }, "channels": { "type": "array", "items": { "type": "string" }, "description": "Any of email, sms, whatsapp.", "example": [ "email", "sms" ] }, "message": { "type": "string", "description": "Optional custom message (max 1000).", "example": "Friendly reminder — balance due Friday." }, "email_to": { "type": "array", "items": { "type": "string" }, "description": "Override recipients (defaults to the client).", "example": [] }, "sms_to": { "type": "array", "items": { "type": "string" }, "description": "Override SMS numbers.", "example": [] }, "whatsapp_to": { "type": "array", "items": { "type": "string" }, "description": "Override WhatsApp numbers.", "example": [] }, "whatsapp_pdf": { "type": "boolean", "description": "Attach the PDF on WhatsApp.", "example": false }, "recur": { "type": "string", "description": "\"\", \"daily\" or \"monthly\".", "example": "monthly" }, "recur_until": { "type": "string", "format": "date", "description": "Last date for repeating reminders.", "example": "2026-12-31" }, "status": { "type": "string", "description": "pending, sent or failed.", "example": "pending", "readOnly": true } } }, "Payments": { "type": "object", "properties": { "id": { "type": "integer", "description": "Payment ID.", "example": 4410, "readOnly": true }, "client_id": { "type": "integer", "description": "Client who paid.", "example": 2381, "readOnly": true }, "invoice_id": { "type": "string", "description": "Invoice the payment belongs to (null for account top-ups).", "example": "66f1c2a9e4b1d", "readOnly": true }, "amount": { "type": "number", "description": "Amount received.", "example": 500, "readOnly": true }, "mode": { "type": "string", "description": "cash, momo, cheque, bank, card, credit or a custom mode.", "example": "momo", "readOnly": true }, "date": { "type": "string", "format": "date", "description": "Payment date.", "example": "2026-10-08", "readOnly": true }, "remarks": { "type": "string", "description": "Reference or note.", "example": "MoMo ref 77812", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "description": "When it was recorded (UTC).", "example": "2026-10-08 11:02:40", "readOnly": true } } }, "Sales": { "type": "object", "properties": { "id": { "type": "integer", "description": "Sale ID.", "example": 812, "readOnly": true }, "date": { "type": "string", "format": "date", "description": "Sale date (default today).", "example": "2026-10-08" }, "client_id": { "type": "integer", "description": "Client, or null for a walk-in.", "example": 2381 }, "customer": { "type": "string", "description": "Customer name for walk-ins (defaults to \"Walk-in\").", "example": "Walk-in" }, "branch_id": { "type": "integer", "description": "Branch the sale was recorded at.", "example": 1, "readOnly": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SaleItem" }, "description": "Cart lines (at least one).", "example": [] }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/SalePayment" }, "description": "Payments taken. Omit for an unpaid sale.", "example": [] }, "discount_type": { "type": "string", "description": "\"amount\" or \"percent\".", "example": "amount" }, "discount_value": { "type": "number", "description": "Discount amount or percentage.", "example": 0 }, "tax_group_id": { "type": "integer", "description": "Tax group to apply, \"default\", or null for no tax." }, "remarks": { "type": "string", "description": "Internal note.", "example": "Paid at the counter" }, "subtotal": { "type": "number", "description": "Sum of lines.", "example": 250, "readOnly": true }, "discount": { "type": "number", "description": "Discount applied.", "example": 0, "readOnly": true }, "tax_total": { "type": "number", "description": "Taxes added.", "example": 0, "readOnly": true }, "total": { "type": "number", "description": "Grand total.", "example": 250, "readOnly": true }, "paid": { "type": "number", "description": "Total paid.", "example": 250, "readOnly": true }, "balance_due": { "type": "number", "description": "total − paid.", "example": 0, "readOnly": true }, "payment_status": { "type": "string", "description": "paid, partial or unpaid.", "example": "paid", "readOnly": true }, "invoice_id": { "type": "string", "description": "Invoice generated from this sale, if any.", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "description": "Recorded (UTC).", "example": "2026-10-08 13:40:11", "readOnly": true } } }, "SaleItem": { "type": "object", "properties": { "product_id": { "type": "integer", "description": "Catalogue product/service. Price defaults to its price.", "example": 57 }, "name": { "type": "string", "description": "Line name (required without product_id).", "example": "Lamination A3" }, "category": { "type": "string", "description": "Sales category for custom lines (default \"Counter / walk-in sales\").", "example": "Counter / walk-in sales" }, "qty": { "type": "number", "description": "Quantity.", "example": 2 }, "unit_price": { "type": "number", "description": "Unit price.", "example": 125 }, "amount": { "type": "number", "description": "qty × unit_price.", "example": 250, "readOnly": true } } }, "SalePayment": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount.", "example": 250 }, "mode": { "type": "string", "description": "cash, momo, card, bank, cheque…", "example": "cash" }, "date": { "type": "string", "format": "date", "description": "Payment date (default sale date).", "example": "2026-10-08" }, "reference": { "type": "string", "description": "Reference number.", "example": "" } } }, "Expenditure": { "type": "object", "properties": { "id": { "type": "integer", "description": "Expense ID.", "example": 305, "readOnly": true }, "date": { "type": "string", "format": "date", "description": "Expense date (default today).", "example": "2026-10-07" }, "payee": { "type": "string", "description": "Who was paid (defaults to the supplier name).", "example": "Accra Paper Mills" }, "supplier_id": { "type": "integer", "description": "Supplier (see /suppliers).", "example": 14 }, "supplier_invoice": { "type": "string", "description": "Supplier's invoice / bill number.", "example": "APM-55120" }, "linked_invoice_id": { "type": "string", "description": "Customer invoice this cost belongs to (job costing)." }, "category": { "type": "string", "description": "Summary of the line expense types.", "example": "Raw materials", "readOnly": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ExpenseItem" }, "description": "Lines (at least one).", "example": [] }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/ExpensePayment" }, "description": "Payments made. Omit for an unpaid bill.", "example": [] }, "total": { "type": "number", "description": "Total of all lines.", "example": 1450, "readOnly": true }, "paid": { "type": "number", "description": "Total paid.", "example": 1450, "readOnly": true }, "balance_due": { "type": "number", "description": "total − paid.", "example": 0, "readOnly": true }, "payment_status": { "type": "string", "description": "paid, partial or unpaid.", "example": "paid", "readOnly": true }, "branch_id": { "type": "integer", "description": "Branch.", "example": 1, "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "description": "Saved (UTC).", "example": "2026-10-07 16:20:00", "readOnly": true } } }, "ExpenseItem": { "type": "object", "properties": { "product_id": { "type": "integer", "description": "Stock product this purchase is for (adds to stock).", "example": 61 }, "name": { "type": "string", "description": "Line description (required without product_id).", "example": "A4 paper 80gsm (box)" }, "category": { "type": "string", "description": "Expense type, e.g. \"Raw materials\", \"Utilities\", \"Transport\".", "example": "Raw materials" }, "qty": { "type": "number", "description": "Quantity.", "example": 10 }, "unit": { "type": "string", "description": "Unit of measure (pcs, box, kg, l, m…).", "example": "box" }, "unit_price": { "type": "number", "description": "Price per unit (> 0).", "example": 145 }, "amount": { "type": "number", "description": "qty × unit_price.", "example": 1450, "readOnly": true }, "remarks": { "type": "string", "description": "Line note.", "example": "" }, "expiry_date": { "type": "string", "format": "date", "description": "Expiry date for perishable stock." } } }, "ExpensePayment": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount paid.", "example": 1450 }, "mode": { "type": "string", "description": "cash, momo, bank, cheque…", "example": "momo" }, "date": { "type": "string", "format": "date", "description": "Payment date (default expense date).", "example": "2026-10-07" }, "reference": { "type": "string", "description": "Reference.", "example": "MOMO-99812" }, "remarks": { "type": "string", "description": "Note.", "example": "" } } }, "Orders": { "type": "object", "properties": { "id": { "type": "integer", "description": "Order ID.", "example": 1204, "readOnly": true }, "job_id": { "type": "integer", "description": "Job (invoice line group) this order belongs to.", "example": 388 }, "invoice_id": { "type": "string", "description": "Source invoice.", "example": "66f1c2a9e4b1d", "readOnly": true }, "title": { "type": "string", "description": "What is being produced.", "example": "Round-neck T-shirt (L) — navy" }, "product_id": { "type": "integer", "description": "Catalogue product/service, if any.", "example": 57 }, "qty": { "type": "number", "description": "Quantity.", "example": 40 }, "status": { "type": "string", "description": "pending, in_progress, completed or cancelled.", "example": "in_progress", "readOnly": true }, "assigned_to": { "type": "integer", "description": "Team member (see /users).", "example": 77 }, "start_at": { "type": "string", "format": "date-time", "description": "Planned start (YYYY-MM-DD HH:MM).", "example": "2026-10-09 08:00" }, "end_at": { "type": "string", "format": "date-time", "description": "Planned finish.", "example": "2026-10-10 17:00" }, "remarks": { "type": "string", "description": "Production notes.", "example": "Use Pantone 2945C" }, "started_at": { "type": "string", "format": "date-time", "description": "When work began (UTC).", "example": "2026-10-09 08:12:00", "readOnly": true }, "completed_at": { "type": "string", "format": "date-time", "description": "When completed (UTC).", "readOnly": true }, "cancelled_at": { "type": "string", "format": "date-time", "description": "When cancelled (UTC).", "readOnly": true }, "processes": { "type": "array", "items": { "$ref": "#/components/schemas/OrderProcess" }, "description": "Processes (detail view). On create, pass an array of names.", "example": [] }, "created_at": { "type": "string", "format": "date-time", "description": "Created (UTC).", "example": "2026-10-08 15:00:00", "readOnly": true } } }, "OrderProcess": { "type": "object", "properties": { "id": { "type": "integer", "description": "Process ID.", "example": 5521, "readOnly": true }, "name": { "type": "string", "description": "Process name.", "example": "Screen print", "readOnly": true }, "done": { "type": "boolean", "description": "Completed.", "example": false, "readOnly": true }, "completed_at": { "type": "string", "format": "date-time", "description": "When it was ticked off (UTC).", "readOnly": true } } }, "Job": { "type": "object", "properties": { "id": { "type": "integer", "description": "Job ID.", "example": 388, "readOnly": true }, "invoice_id": { "type": "string", "description": "Invoice.", "example": "66f1c2a9e4b1d", "readOnly": true }, "invoice_item_id": { "type": "integer", "description": "Invoice line.", "example": 9811, "readOnly": true }, "title": { "type": "string", "description": "Line name.", "example": "Round-neck T-shirt (L)", "readOnly": true }, "qty": { "type": "number", "description": "Line quantity.", "example": 40, "readOnly": true }, "order_count": { "type": "integer", "description": "Orders under this job.", "example": 1, "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "description": "Created (UTC).", "example": "2026-10-08 15:00:00", "readOnly": true } } }, "Taxes": { "type": "object", "properties": { "id": { "type": "integer", "description": "Tax ID.", "example": 31, "readOnly": true }, "name": { "type": "string", "description": "Tax name.", "example": "VAT" }, "rate": { "type": "number", "description": "Percentage, 0 to 100.", "example": 15 }, "type": { "type": "string", "description": "\"levy\" or \"vat\".", "example": "vat" }, "sort": { "type": "integer", "description": "Display and calculation order.", "example": 40 }, "active": { "type": "boolean", "description": "Active taxes are added to the default tax group on create.", "example": true } } }, "TaxGroups": { "type": "object", "properties": { "id": { "type": "integer", "description": "Tax group ID.", "example": 4, "readOnly": true }, "name": { "type": "string", "description": "Group name.", "example": "Standard (VAT + levies)" }, "is_default": { "type": "boolean", "description": "Default group for new invoices and sales.", "example": true }, "active": { "type": "boolean", "description": "Whether the group can be selected.", "example": true }, "sort": { "type": "integer", "description": "Display order.", "example": 0 }, "tax_ids": { "type": "array", "items": { "type": "object" }, "description": "IDs of the taxes in this group.", "example": [ 28, 29, 30, 31 ] }, "taxes": { "type": "array", "items": { "type": "object" }, "description": "The active taxes in this group: [{id, name, rate, type}].", "example": [ { "id": 31, "name": "VAT", "rate": 15, "type": "vat" } ], "readOnly": true } } }, "Branches": { "type": "object", "properties": { "id": { "type": "integer", "description": "Branch ID.", "example": 3, "readOnly": true }, "name": { "type": "string", "description": "Branch name.", "example": "Kumasi Mall" }, "code": { "type": "string", "description": "Short code (stored uppercase).", "example": "KSI" }, "phone": { "type": "string", "description": "Phone (digits only).", "example": "0322000111" }, "email": { "type": "string", "description": "Email.", "example": "kumasi@kenteprints.com" }, "address": { "type": "string", "description": "Street address.", "example": "Shop 14, Kumasi City Mall" }, "town": { "type": "string", "description": "Town or city.", "example": "Kumasi" }, "is_default": { "type": "boolean", "description": "Default branch for new records.", "example": false }, "active": { "type": "boolean", "description": "Whether the branch is in use.", "example": true }, "created_at": { "type": "string", "format": "date-time", "description": "When it was added (UTC).", "example": "2026-05-11 12:00:00", "readOnly": true } } }, "Users": { "type": "object", "properties": { "id": { "type": "integer", "description": "User ID.", "example": 77, "readOnly": true }, "first_name": { "type": "string", "description": "First name.", "example": "Esi" }, "last_name": { "type": "string", "description": "Last name.", "example": "Mensah" }, "email": { "type": "string", "description": "Email (the invite is sent here). Unique per workspace.", "example": "esi@kenteprints.com" }, "phone": { "type": "string", "description": "Phone. Unique per workspace.", "example": "0201234567" }, "role": { "type": "string", "description": "Role key (see /roles), e.g. admin, manager, accountant, sales, production, viewer.", "example": "manager" }, "role_label": { "type": "string", "description": "Role name.", "example": "Manager", "readOnly": true }, "branch_id": { "type": "integer", "description": "Home branch (see /branches).", "example": 1 }, "active": { "type": "boolean", "description": "Can sign in. Invited users become active after accepting.", "example": true }, "invite_pending": { "type": "boolean", "description": "Invitation sent but not yet accepted.", "example": false, "readOnly": true } } }, "Roles": { "type": "object", "properties": { "key": { "type": "string", "description": "Role key, used as users.role.", "example": "manager", "readOnly": true }, "label": { "type": "string", "description": "Role name.", "example": "Front desk" }, "summary": { "type": "string", "description": "Short description.", "example": "Clients, invoices and POS only." }, "custom": { "type": "boolean", "description": "Created for this workspace (can be deleted).", "example": false, "readOnly": true }, "locked": { "type": "boolean", "description": "Privileges cannot be changed (super_admin).", "example": false, "readOnly": true }, "user_count": { "type": "integer", "description": "Team members with this role.", "example": 3, "readOnly": true }, "privileges": { "type": "object", "description": "module key => {view, add, update, delete}. On create/update, only modules you pass are changed.", "example": { "invoices": { "view": true, "add": true, "update": true, "delete": false } } } } }, "RoleModule": { "type": "object", "properties": { "key": { "type": "string", "description": "Module key, used in privileges.", "example": "invoices", "readOnly": true }, "label": { "type": "string", "description": "Module name.", "example": "Invoices", "readOnly": true }, "industry": { "type": "boolean", "description": "Only shown for some business types.", "example": false, "readOnly": true } } }, "Recipes": { "type": "object", "properties": { "id": { "type": "integer", "description": "Recipe ID.", "example": 41, "readOnly": true }, "name": { "type": "string", "description": "Recipe name.", "example": "Jollof rice (party pack)" }, "notes": { "type": "string", "description": "Method / notes.", "example": "Parboil rice 10 min before adding stew." }, "yield_qty": { "type": "number", "description": "How much one batch makes.", "example": 10 }, "yield_unit": { "type": "string", "description": "Yield unit (portion, kg, l, pcs…).", "example": "portion" }, "menu_product_id": { "type": "integer", "description": "Linked menu item in the catalogue, if published.", "example": 120, "readOnly": true }, "ingredients": { "type": "array", "items": { "$ref": "#/components/schemas/RecipeIngredient" }, "description": "Ingredients (at least one ingredient or base).", "example": [] }, "bases": { "type": "array", "items": { "$ref": "#/components/schemas/RecipeBase" }, "description": "Base recipes used inside this recipe.", "example": [] }, "variations": { "type": "array", "items": { "type": "object" }, "description": "Sizes defined in the app (read-only).", "example": [], "readOnly": true }, "cost": { "type": "number", "description": "Current cost of one batch (ingredients + add-ons).", "example": 182.5, "readOnly": true }, "cost_per_unit": { "type": "number", "description": "cost ÷ yield_qty.", "example": 18.25, "readOnly": true }, "publish_to_menu": { "type": "boolean", "description": "Create/refresh a sellable menu item (create only).", "example": false }, "menu_price": { "type": "number", "description": "Selling price for the menu item (with publish_to_menu).", "example": 35 }, "menu_category_id": { "type": "integer", "description": "Catalogue category for the menu item.", "example": 3 }, "created_at": { "type": "string", "format": "date-time", "description": "Created (UTC).", "example": "2026-09-30 12:00:00", "readOnly": true } } }, "RecipeIngredient": { "type": "object", "properties": { "product_id": { "type": "integer", "description": "Cost-of-Sale stock item.", "example": 61 }, "name": { "type": "string", "description": "Name for a non-stock ingredient.", "example": "Water" }, "qty": { "type": "number", "description": "Quantity per batch.", "example": 2.5 }, "unit": { "type": "string", "description": "Unit (g, kg, ml, l, pcs…).", "example": "kg" } } }, "RecipeBase": { "type": "object", "properties": { "recipe_id": { "type": "integer", "description": "Base recipe.", "example": 12 }, "variation_id": { "type": "integer", "description": "Size of the base recipe (0 = default).", "example": 0 }, "qty": { "type": "number", "description": "Quantity per batch.", "example": 1 }, "unit": { "type": "string", "description": "Unit.", "example": "portion" } } }, "Stores": { "type": "object", "properties": { "id": { "type": "integer", "description": "Store ID.", "example": 2, "readOnly": true }, "name": { "type": "string", "description": "Store name (at least 5 characters).", "example": "Kente Prints Shop" }, "description": { "type": "string", "description": "Shown on the storefront.", "example": "Custom T-shirts, banners and souvenirs." }, "phone": { "type": "string", "description": "Contact phone.", "example": "0244000111" }, "email": { "type": "string", "description": "Contact email.", "example": "shop@kenteprints.com" }, "slug": { "type": "string", "description": "Link name in the public URL (unique, at least 5 characters).", "example": "kente-prints" }, "public_url": { "type": "string", "description": "Public storefront URL.", "example": "https://blueq.app/link/store/kente-prints", "readOnly": true }, "template": { "type": "string", "description": "classic, market or list.", "example": "classic" }, "active": { "type": "boolean", "description": "Store is online.", "example": true }, "paystack_connected": { "type": "boolean", "description": "Paystack keys are configured (managed in the app).", "example": true, "readOnly": true }, "product_count": { "type": "integer", "description": "Active products listed.", "example": 48, "readOnly": true }, "settings": { "type": "object", "description": "Checkout settings: checkout_payment (\"paystack\" or \"place\"), pickup_enabled, delivery_enabled, create_orders, pos_create_orders, send_receipt, reset_order_daily, tax_group_id, payment_note.", "example": { "checkout_payment": "paystack", "pickup_enabled": true, "delivery_enabled": true, "send_receipt": true, "tax_group_id": null } }, "created_at": { "type": "string", "format": "date-time", "description": "Created (UTC).", "example": "2026-08-02 10:00:00", "readOnly": true } } }, "StoreOrders": { "type": "object", "properties": { "id": { "type": "integer", "description": "Order ID.", "example": 9031, "readOnly": true }, "store_id": { "type": "integer", "description": "Store.", "example": 2, "readOnly": true }, "number": { "type": "string", "description": "Order number (resets daily if configured).", "example": "014", "readOnly": true }, "receipt_number": { "type": "string", "description": "Receipt number.", "example": "R-00412", "readOnly": true }, "channel": { "type": "string", "description": "online or walkin.", "example": "online", "readOnly": true }, "status": { "type": "string", "description": "pending, paid or failed.", "example": "paid", "readOnly": true }, "payment_mode": { "type": "string", "description": "Paystack, Cash, Mobile Money, Card or Place order.", "example": "Paystack", "readOnly": true }, "customer": { "type": "object", "description": "name, phone, email, client_id.", "example": { "name": "Yaw Asante", "phone": "0244111222", "email": null, "client_id": 2399 }, "readOnly": true }, "fulfillment": { "type": "string", "description": "pickup or delivery.", "example": "delivery", "readOnly": true }, "delivery": { "type": "object", "description": "town, address, zone, fee (delivery orders).", "example": { "town": "East Legon", "address": "Lagos Ave 14", "zone": "Accra East", "fee": 25 }, "readOnly": true }, "subtotal": { "type": "number", "description": "Items total.", "example": 240, "readOnly": true }, "tax_total": { "type": "number", "description": "Taxes.", "example": 0, "readOnly": true }, "total": { "type": "number", "description": "Grand total.", "example": 265, "readOnly": true }, "picked_up": { "type": "boolean", "description": "Collected / delivered.", "example": false, "readOnly": true }, "sale_id": { "type": "integer", "description": "Sale recorded for the order (see /sales).", "example": 812, "readOnly": true }, "invoice_id": { "type": "string", "description": "Invoice/receipt generated.", "readOnly": true }, "pos_session_id": { "type": "integer", "description": "Till session (walk-in orders).", "readOnly": true }, "items": { "type": "array", "items": { "type": "object" }, "description": "product_id, name, qty, unit_price, amount (detail view).", "example": [], "readOnly": true }, "date": { "type": "string", "format": "date", "description": "Business date.", "example": "2026-10-08", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "description": "Placed (UTC).", "example": "2026-10-08 09:40:00", "readOnly": true }, "paid_at": { "type": "string", "format": "date-time", "description": "Paid (UTC).", "example": "2026-10-08 09:41:12", "readOnly": true } } }, "DeliveryZones": { "type": "object", "properties": { "id": { "type": "integer", "description": "Zone ID.", "example": 7, "readOnly": true }, "store_id": { "type": "integer", "description": "Store the zone belongs to.", "example": 2 }, "name": { "type": "string", "description": "Zone name.", "example": "Accra East" }, "price": { "type": "number", "description": "Delivery fee.", "example": 25 }, "towns": { "type": "array", "items": { "type": "string" }, "description": "Towns covered (at least one).", "example": [ "East Legon", "Madina", "Adenta" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Created (UTC).", "example": "2026-08-02 10:20:00", "readOnly": true } } }, "StoreAccounts": { "type": "object", "properties": { "id": { "type": "integer", "description": "Account ID.", "example": 311, "readOnly": true }, "email": { "type": "string", "description": "Sign-in email.", "example": "yaw.asante@example.com", "readOnly": true }, "name": { "type": "string", "description": "Full name.", "example": "Yaw Asante" }, "phone": { "type": "string", "description": "Phone.", "example": "0244111222" }, "order_count": { "type": "integer", "description": "Paid orders placed with this email.", "example": 4, "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "description": "Registered (UTC).", "example": "2026-09-01 18:30:00", "readOnly": true } } }, "Pos": { "type": "object", "properties": { "id": { "type": "integer", "description": "Session ID.", "example": 140, "readOnly": true }, "cashier_id": { "type": "integer", "description": "Team member running the till (see /users). Defaults to the workspace owner.", "example": 77 }, "cashier_name": { "type": "string", "description": "Cashier name.", "example": "Esi Mensah", "readOnly": true }, "status": { "type": "string", "description": "open, pending (closed, awaiting review), approved or rejected.", "example": "open", "readOnly": true }, "sale_count": { "type": "integer", "description": "Paid sales in the session.", "example": 23, "readOnly": true }, "total": { "type": "number", "description": "Sales total.", "example": 1840.5, "readOnly": true }, "opened_at": { "type": "string", "format": "date-time", "description": "Opened (UTC).", "example": "2026-10-08 07:58:00", "readOnly": true }, "closed_at": { "type": "string", "format": "date-time", "description": "Closed (UTC).", "readOnly": true }, "review_note": { "type": "string", "description": "Reviewer note.", "readOnly": true }, "reviewed_at": { "type": "string", "format": "date-time", "description": "Reviewed (UTC).", "readOnly": true } } }, "PosRegister": { "type": "object", "properties": { "name": { "type": "string", "description": "Till name shown on receipts.", "example": "Front counter" }, "phone": { "type": "string", "description": "Receipt phone.", "example": "0302000111" }, "email": { "type": "string", "description": "Receipt email.", "example": "counter@kenteprints.com" }, "address": { "type": "string", "description": "Receipt address.", "example": "Osu, Oxford St." }, "active": { "type": "boolean", "description": "Till can take sales.", "example": true }, "store_id": { "type": "integer", "description": "Store whose products and order numbers the till uses.", "example": 2 }, "tax_group_id": { "type": "integer", "description": "Tax group applied to sales (0 = none).", "example": 0 } } }, "PosSale": { "type": "object", "properties": { "cashier_id": { "type": "integer", "description": "Cashier with an open session (default: owner).", "example": 77 }, "items": { "type": "array", "items": { "type": "object" }, "description": "Lines: {\"product_id\": 57, \"qty\": 2}. Prices come from the catalogue.", "example": [ { "product_id": 57, "qty": 2 } ] }, "payment_mode": { "type": "string", "description": "Cash, Mobile Money or Card.", "example": "Cash" }, "customer_name": { "type": "string", "description": "Default \"Walk-in\".", "example": "Walk-in" }, "customer_phone": { "type": "string", "description": "Receipt SMS number.", "example": "" } } }, "Reports": { "type": "object", "properties": { "source": { "type": "string", "description": "Report key (see GET /reports).", "example": "sales", "readOnly": true }, "title": { "type": "string", "description": "Report title.", "example": "Sales", "readOnly": true }, "columns": { "type": "array", "items": { "type": "string" }, "description": "Column headings.", "example": [ "Date", "Category", "Product", "Customer", "Status", "Reference", "Amount (GHS)" ], "readOnly": true }, "rows": { "type": "array", "items": { "type": "array", "items": {} }, "description": "Rows in column order.", "example": [ [ "2026-10-08", "Products", "Kente stole", "Walk-in", "Paid", "S-0812", 240 ] ], "readOnly": true }, "items": { "type": "array", "items": { "type": "object" }, "description": "Rows keyed by snake_case column name.", "example": [ { "date": "2026-10-08", "category": "Products", "product": "Kente stole", "customer": "Walk-in", "status": "Paid", "reference": "S-0812", "amount_ghs": 240 } ], "readOnly": true }, "summary": { "type": "array", "items": { "type": "object" }, "description": "Headline figures: {label, value}.", "example": [ { "label": "Rows", "value": "58" }, { "label": "Amount", "value": "GHS 9,420.00" } ], "readOnly": true }, "total": { "type": "integer", "description": "Rows matching the filters.", "example": 58, "readOnly": true }, "truncated": { "type": "boolean", "description": "More rows match than were returned (raise limit, max 5000).", "example": false, "readOnly": true }, "filters": { "type": "object", "description": "Filters applied.", "example": { "start": "2026-10-01", "end": "2026-10-31" }, "readOnly": true } } }, "ReportSource": { "type": "object", "properties": { "source": { "type": "string", "description": "Report key, used in /reports/{source}.", "example": "payments", "readOnly": true }, "title": { "type": "string", "description": "Report title.", "example": "Payments", "readOnly": true }, "columns": { "type": "array", "items": { "type": "string" }, "description": "Columns the report returns.", "example": [ "Date", "Client", "Invoice", "Mode", "Type", "Amount (GHS)", "Remarks" ], "readOnly": true }, "charts": { "type": "array", "items": { "type": "string" }, "description": "Charts available at /reports/{source}/charts.", "example": [ "Payments by day", "Payments by mode" ], "readOnly": true }, "filters": { "type": "object", "description": "Query filters the report accepts: name => description.", "example": { "from": "Start date.", "to": "End date.", "client": "Client ID.", "payment_type": "credit or debit." }, "readOnly": true } } }, "CustomReport": { "type": "object", "properties": { "id": { "type": "integer", "description": "Custom report ID.", "example": 6, "readOnly": true }, "name": { "type": "string", "description": "Report name.", "example": "Monthly cash view" }, "sections": { "type": "array", "items": { "type": "object" }, "description": "Datasets: {\"source\":\"payments\",\"columns\":[\"Date\",\"Amount (GHS)\"],\"filters\":{\"payment_type\":\"credit\"},\"chart\":\"all\"}. Dates are supplied when the report is run.", "example": [ { "source": "payments", "columns": [ "Date", "Client", "Amount (GHS)" ], "filters": { "payment_type": "credit" }, "chart": "" } ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Last change (UTC).", "example": "2026-10-01 10:12:00", "readOnly": true } } }, "PageMeta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "Error": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "validation_failed" }, "message": { "type": "string", "example": "phone is required." }, "fields": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } } } } } } } } }