{ "openapi": "3.0.0", "info": { "title": "Zulu API", "description": "Modern REST API for Zulu Dashboard supporting both tenant-specific and system-level operations.\n\n## Authentication\n\n### Tenant API Keys (User-Generated)\nFor tenant-specific operations, use API keys generated from your account settings:\n```\nAuthorization: Bearer zulu_{64-character-hex-string}\n```\n\n**How to generate:**\n1. Log into your Zulu Dashboard\n2. Go to Settings > API tab\n3. Generate a new API key with a descriptive name\n4. Copy the key immediately (it won't be shown again)\n\n### System API Keys (Internal Use)\nFor system-level operations like trial creation:\n```\nAuthorization: Bearer zulu_internal_{64-character-hex-string}\n```\n\n**How to generate:**\n- System administrators only\n- Use the command-line script: `./scripts/api_key_generate.sh`\n- Generated keys are stored securely in the database\n\n## Available Operations\n\n### Public Endpoints\n- API status and version information\n\n### Tenant Endpoints (Require Tenant API Key)\n- Retrieve your account/tenant information\n- View trial status and plan details\n- Access usage statistics\n\n### System Endpoints (Require System API Key)\n- Create trial accounts\n- System-level account management\n- Internal operations and integrations\n\n## Rate Limiting\n- **Tenant Keys**: 60 requests per minute (configurable per key)\n- **System Keys**: Unlimited (for reliable system operations)\n- Rate limits are enforced per API key\n- Headers indicate current rate limit status\n\n## Security Best Practices\n1. **Store API keys securely** - Use environment variables or secure key management\n2. **Use HTTPS only** - Never send API keys over unencrypted connections\n3. **Rotate keys regularly** - Generate new keys and revoke old ones periodically\n4. **Limit key scope** - Use tenant keys for user operations, system keys for internal tasks\n5. **Monitor usage** - Check API key usage statistics regularly\n\n## Error Handling\nThe API returns standard HTTP status codes with detailed error messages:\n- `200` - Success\n- `201` - Created (for resource creation)\n- `400` - Bad Request (validation errors)\n- `401` - Unauthorized (missing/invalid/expired token)\n- `403` - Forbidden (insufficient permissions)\n- `409` - Conflict (duplicate resource)\n- `429` - Too Many Requests (rate limit exceeded)\n- `500` - Internal Server Error\n\nAll error responses include:\n```json\n{\n \"error\": \"error_type\",\n \"message\": \"Human-readable error description\"\n}\n```", "version": "1.0.0", "contact": { "name": "Zulu Support", "email": "support@getzulu.io", "url": "https://www.getzulu.io" }, "license": { "name": "Proprietary", "url": "https://www.getzulu.io/terms" } }, "servers": [ { "url": "https://dashboard.getzulu.io/api/v1", "description": "Current environment (Production)" } ], "security": [], "paths": { "/": { "get": { "summary": "API Status", "description": "Returns API version and status information", "tags": [ "Public" ], "security": [], "responses": { "200": { "description": "API status information", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Zulu API" }, "version": { "type": "string", "example": "1.0.0" }, "status": { "type": "string", "example": "active" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/client": { "get": { "tags": [ "Clients" ], "summary": "List clients", "description": "Retrieve a paginated list of clients with filtering and search capabilities. Supports exact match and partial (LIKE) search on key fields.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results (default: 20, max: 100)", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of results to skip for pagination", "schema": { "type": "integer", "default": 0 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order", "schema": { "type": "string", "enum": [ "name_asc", "name_desc", "company_asc", "company_desc", "email_asc", "email_desc", "newest", "oldest" ], "default": "name_asc" } }, { "name": "type", "in": "query", "required": false, "description": "Filter by client type", "schema": { "type": "integer", "enum": [ 0, 1, 2, 3 ], "description": "0=Cancelled, 1=Client, 2=Lead, 3=Prospect" } }, { "name": "search", "in": "query", "required": false, "description": "Universal search across company, first name, last name, email, and phone (partial match)", "schema": { "type": "string" } }, { "name": "company", "in": "query", "required": false, "description": "Filter by exact company name", "schema": { "type": "string" } }, { "name": "company_like", "in": "query", "required": false, "description": "Filter by company name (partial match)", "schema": { "type": "string" } }, { "name": "name_first", "in": "query", "required": false, "description": "Filter by exact first name", "schema": { "type": "string" } }, { "name": "name_first_like", "in": "query", "required": false, "description": "Filter by first name (partial match)", "schema": { "type": "string" } }, { "name": "name_last", "in": "query", "required": false, "description": "Filter by exact last name", "schema": { "type": "string" } }, { "name": "name_last_like", "in": "query", "required": false, "description": "Filter by last name (partial match)", "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "description": "Filter by exact email", "schema": { "type": "string" } }, { "name": "email_like", "in": "query", "required": false, "description": "Filter by email (partial match)", "schema": { "type": "string" } }, { "name": "phone", "in": "query", "required": false, "description": "Filter by exact phone number (matches e164 or national format)", "schema": { "type": "string" } }, { "name": "phone_like", "in": "query", "required": false, "description": "Filter by phone number (partial match on e164 or national format)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of clients retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "clients": { "type": "array", "items": { "$ref": "#/components/schemas/ClientSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Clients" ], "summary": "Create client", "description": "Create a new client with optional addresses and contacts. At least one identifying field (company, name_first, name_last, or email) is required.", "security": [ { "TenantAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientCreateInput" } } } }, "responses": { "201": { "description": "Client created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Client" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/client/{token}": { "get": { "tags": [ "Clients" ], "summary": "Get single client", "description": "Retrieve a single client by token including addresses, contacts, and meta data.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Client token (UUID)", "schema": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "Client retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Client" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": [ "Clients" ], "summary": "Update client", "description": "Update an existing client by token. Note: Addresses and contacts cannot be updated via this endpoint.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Client token (UUID)", "schema": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientUpdateInput" } } } }, "responses": { "200": { "description": "Client updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Client" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/supplier": { "get": { "tags": [ "Suppliers" ], "summary": "List suppliers", "description": "Retrieve a paginated list of suppliers with filtering and search capabilities.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results (default: 20, max: 100)", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of results to skip for pagination", "schema": { "type": "integer", "default": 0 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order", "schema": { "type": "string", "enum": [ "name_asc", "name_desc", "company_asc", "company_desc", "email_asc", "email_desc", "newest", "oldest" ], "default": "name_asc" } }, { "name": "search", "in": "query", "required": false, "description": "Universal search across company, first name, last name, email, and phone (partial match)", "schema": { "type": "string" } }, { "name": "company", "in": "query", "required": false, "description": "Filter by exact company name", "schema": { "type": "string" } }, { "name": "company_like", "in": "query", "required": false, "description": "Filter by company name (partial match)", "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "description": "Filter by exact email", "schema": { "type": "string", "format": "email" } }, { "name": "email_like", "in": "query", "required": false, "description": "Filter by email (partial match)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of suppliers retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "suppliers": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Suppliers" ], "summary": "Create supplier", "description": "Create a new supplier with optional addresses and contacts. At least one identifying field (company, name_first, name_last, or email) is required.", "security": [ { "TenantAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierCreateInput" } } } }, "responses": { "201": { "description": "Supplier created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Supplier" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/supplier/{token}": { "get": { "tags": [ "Suppliers" ], "summary": "Get single supplier", "description": "Retrieve a single supplier by token including addresses, contacts, and meta data.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Supplier token (UUID)", "schema": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "Supplier retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Supplier" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": [ "Suppliers" ], "summary": "Update supplier", "description": "Update an existing supplier by token. Note: Addresses and contacts cannot be updated via this endpoint.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Supplier token (UUID)", "schema": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierUpdateInput" } } } }, "responses": { "200": { "description": "Supplier updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Supplier" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/tenant_info": { "get": { "tags": [ "Tenant" ], "summary": "Get tenant information", "description": "Retrieve information about your tenant account including trial status, plan details, and usage.", "security": [ { "TenantAuth": [] } ], "responses": { "200": { "description": "Tenant information retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded" }, "data": { "type": "object", "properties": { "account_id": { "type": "integer", "description": "Account ID" }, "email": { "type": "string", "description": "Account email" }, "company": { "type": "string", "description": "Company name" }, "trial_expires_at": { "type": "string", "format": "date-time", "description": "Trial expiration date" }, "plan_id": { "type": "integer", "description": "Assigned plan ID" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/post/{type}": { "get": { "tags": [ "Posts" ], "summary": "List posts by type", "description": "Retrieve a paginated list of posts filtered by type. Supports filtering by status, parent, and various sort options.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "type", "in": "path", "required": true, "description": "Post type (e.g., page, blog, news, faqs, popup, form, template, document, etc.)", "schema": { "type": "string", "example": "page" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status", "schema": { "type": "string", "enum": [ "draft", "published", "hidden" ] } }, { "name": "parent_id", "in": "query", "required": false, "description": "Filter by parent post ID", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results (default: 20, max: 100)", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of results to skip for pagination", "schema": { "type": "integer", "default": 0 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order", "schema": { "type": "string", "enum": [ "newest", "oldest", "title_asc", "title_desc", "sort_asc", "sort_desc" ], "default": "newest" } } ], "responses": { "200": { "description": "List of posts retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "posts": { "type": "array", "items": { "$ref": "#/components/schemas/PostSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/post/{type}/{identifier}": { "get": { "tags": [ "Posts" ], "summary": "Get single post", "description": "Retrieve a single post by its ID or slug. The identifier can be either a numeric ID or a slug string.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "type", "in": "path", "required": true, "description": "Post type", "schema": { "type": "string", "example": "page" } }, { "name": "identifier", "in": "path", "required": true, "description": "Post ID (numeric) or slug (string)", "schema": { "type": "string", "example": "about-us" } } ], "responses": { "200": { "description": "Post retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Post" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/post": { "post": { "tags": [ "Posts" ], "summary": "Create new post", "description": "Create a new post.\n\n**Required fields:**\n- `type` - Post type (e.g. page, blog, news)\n- `title` - Post title (max 255 chars)\n\n**Optional fields:**\n- `content` - HTML content\n- `status` - draft (default), published, or hidden\n- `parent_id` - Parent post ID (default: 0)\n- `sort` - Sort order (default: 0)\n- `author_id` - Author user ID (must belong to account, defaults to API key owner)\n- `meta` - Key-value object for custom fields\n\nThe `slug` is auto-generated from the title.", "security": [ { "TenantAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostCreate" } } } }, "responses": { "201": { "description": "Post created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "example": "Post created successfully" }, "data": { "$ref": "#/components/schemas/Post" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/post/{id}": { "put": { "tags": [ "Posts" ], "summary": "Update existing post", "description": "Update an existing post. Only provided fields will be updated.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Post ID", "schema": { "type": "integer", "example": 123 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostUpdate" } } } }, "responses": { "200": { "description": "Post updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "example": "Post updated successfully" }, "data": { "$ref": "#/components/schemas/Post" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/product": { "get": { "tags": [ "Products" ], "summary": "List products", "description": "Retrieve a paginated list of products with filtering and search capabilities.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results (default: 20, max: 100)", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of results to skip for pagination", "schema": { "type": "integer", "default": 0 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order", "schema": { "type": "string", "enum": [ "name_asc", "name_desc", "sku_asc", "sku_desc", "price_asc", "price_desc", "newest", "oldest" ], "default": "name_asc" } }, { "name": "search", "in": "query", "required": false, "description": "Universal search across name, SKU, vendor SKU, and description (partial match)", "schema": { "type": "string" } }, { "name": "hidden", "in": "query", "required": false, "description": "Filter by website visibility. This flag only controls whether the product is hidden on front-end websites \u2014 it does not hide the product within Zulu itself. When true, returns only website-hidden products. When false, returns only website-visible products. When omitted, returns all.", "schema": { "type": "boolean" } }, { "name": "supplier", "in": "query", "required": false, "description": "Filter by supplier token (UUID)", "schema": { "type": "string", "format": "uuid" } }, { "name": "brand", "in": "query", "required": false, "description": "Filter by brand token (UUID)", "schema": { "type": "string", "format": "uuid" } }, { "name": "sku", "in": "query", "required": false, "description": "Filter by exact SKU", "schema": { "type": "string" } }, { "name": "sku_like", "in": "query", "required": false, "description": "Filter by SKU (partial match)", "schema": { "type": "string" } }, { "name": "name_like", "in": "query", "required": false, "description": "Filter by name (partial match)", "schema": { "type": "string" } }, { "name": "description_like", "in": "query", "required": false, "description": "Filter by description (partial match)", "schema": { "type": "string" } }, { "name": "sku_vendor", "in": "query", "required": false, "description": "Filter by exact vendor SKU", "schema": { "type": "string" } }, { "name": "barcode", "in": "query", "required": false, "description": "Filter by exact barcode", "schema": { "type": "string" } }, { "name": "barcode_like", "in": "query", "required": false, "description": "Filter by barcode (partial match)", "schema": { "type": "string" } }, { "name": "stock_type", "in": "query", "required": false, "description": "Filter by stock tracking. Omit or leave empty to ignore.", "schema": { "type": "string", "enum": [ "tracked", "untracked" ] } }, { "name": "category", "in": "query", "required": false, "description": "Filter by category token (UUID). Only returns products assigned to this category.", "schema": { "type": "string", "format": "uuid" } }, { "name": "tag", "in": "query", "required": false, "description": "Filter by tag option token (UUID). Only returns products with this tag option assigned.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of products retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Products" ], "summary": "Create product", "description": "Create a new product with optional prices, categories, and tags.\n\n**Required fields:**\n- `name` - Product name\n\n**Optional nested objects:**\n- `prices` - Object with price fields (price, price_special, price_ws1-7)\n- `categories` - Array of category product IDs\n- `tags` - Array of tag option IDs\n- `barcode` - Product barcode (stored as meta)", "security": [ { "TenantAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCreateInput" } } } }, "responses": { "201": { "description": "Product created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Product" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/product/{token}": { "get": { "tags": [ "Products" ], "summary": "Get single product", "description": "Retrieve a single product by token including prices, categories, tags, and meta data.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Product token", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Product" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": [ "Products" ], "summary": "Update product", "description": "Update product core fields. Prices cannot be updated via this endpoint \u2014 use PUT /product/{token}/price instead.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Product token", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductUpdateInput" } } } }, "responses": { "200": { "description": "Product updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Product" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/product/{token}/price": { "put": { "tags": [ "Products" ], "summary": "Update product prices", "description": "Update one or more price fields on a product. All changes are logged to the price audit trail.\n\n**Allowed fields:** price, price_special, price_ws1 through price_ws7\n\n**Not allowed:** price_purchase, price_latest_landed, price_average (system-managed)", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Product token", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductPriceUpdateInput" } } } }, "responses": { "200": { "description": "Product prices updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "token": { "type": "string" }, "name": { "type": "string" }, "sku": { "type": "string" }, "prices": { "$ref": "#/components/schemas/ProductPrices" }, "updated_fields": { "type": "array", "items": { "type": "string" }, "description": "List of price fields that were updated" } } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/product/{token}/category": { "put": { "tags": [ "Products" ], "summary": "Manage product categories", "description": "Replace all category assignments for a product. Provide the complete list of category tokens \u2014 any existing assignments not in the list will be removed. Use an empty array to clear all categories.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Product token", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "categories" ], "properties": { "categories": { "type": "array", "items": { "type": "string" }, "description": "Array of category product tokens", "example": [ "7ad2acde-4cdf-4b85-bf89-249586e7e686", "02312c04-cf99-4fcd-bb45-1a0dec9fc106" ] } } } } } }, "responses": { "200": { "description": "Product categories updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "token": { "type": "string" }, "name": { "type": "string" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCategoryItem" } } } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/product/{token}/tag": { "put": { "tags": [ "Products" ], "summary": "Manage product tags", "description": "Replace all tag assignments for a product. Provide the complete list of tag option tokens \u2014 any existing assignments not in the list will be removed. Ancestor tag options are automatically added (cascading hierarchy). Use an empty array to clear all tags.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Product token", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tags" ], "properties": { "tags": { "type": "array", "items": { "type": "string" }, "description": "Array of tag option tokens (UUID)", "example": [ "7ad2acde-4cdf-4b85-bf89-249586e7e686", "02312c04-cf99-4fcd-bb45-1a0dec9fc106" ] } } } } } }, "responses": { "200": { "description": "Product tags updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "token": { "type": "string" }, "name": { "type": "string" }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/ProductTagItem" } } } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/product/taxonomy": { "get": { "tags": [ "Products" ], "summary": "Get product taxonomy", "description": "Returns the full product category tree and tag hierarchy in a single request. Categories are nested by parent_id. Tags are nested by parent_tag_id with their options.", "security": [ { "TenantAuth": [] } ], "responses": { "200": { "description": "Taxonomy retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "categories": { "type": "array", "description": "Nested category tree", "items": { "$ref": "#/components/schemas/TaxonomyCategory" } }, "tags": { "type": "array", "description": "Nested tag hierarchy with options", "items": { "$ref": "#/components/schemas/TaxonomyTag" } }, "brands": { "type": "array", "description": "Product brands", "items": { "$ref": "#/components/schemas/TaxonomyBrand" } } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/product/{token}/category/{category_token}": { "put": { "tags": [ "Products" ], "summary": "Add category to product", "description": "Add a single category to a product. Duplicates are ignored.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Product token", "schema": { "type": "string" } }, { "name": "category_token", "in": "path", "required": true, "description": "Category product token", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Category added successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "token": { "type": "string" }, "name": { "type": "string" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCategoryItem" } } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Products" ], "summary": "Remove category from product", "description": "Remove a single category assignment from a product.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Product token", "schema": { "type": "string" } }, { "name": "category_token", "in": "path", "required": true, "description": "Category product token", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Category removed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "token": { "type": "string" }, "name": { "type": "string" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCategoryItem" } } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/product/{token}/tag/{tag_option_token}": { "put": { "tags": [ "Products" ], "summary": "Add tag to product", "description": "Add a tag option to a product. Ancestor tag options are automatically added (cascading hierarchy).", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Product token", "schema": { "type": "string" } }, { "name": "tag_option_token", "in": "path", "required": true, "description": "Tag option token", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tag added successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "token": { "type": "string" }, "name": { "type": "string" }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/ProductTagItem" } } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Products" ], "summary": "Remove tag from product", "description": "Remove a tag option assignment from a product.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Product token", "schema": { "type": "string" } }, { "name": "tag_option_token", "in": "path", "required": true, "description": "Tag option token", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tag removed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "token": { "type": "string" }, "name": { "type": "string" }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/ProductTagItem" } } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/note/{object}/{token}": { "get": { "tags": [ "Notes" ], "summary": "List notes for an entity", "description": "Returns a paginated list of notes for a given entity. Notes are ordered by date descending (newest first).", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "object", "in": "path", "required": true, "description": "Entity type: client, sale, or product", "schema": { "type": "string", "enum": [ "client", "sale", "product" ] } }, { "name": "token", "in": "path", "required": true, "description": "Entity token", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results per page (max 100)", "schema": { "type": "integer", "default": 5, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of results to skip", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of notes", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "notes": { "type": "array", "items": { "$ref": "#/components/schemas/NoteListItem" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Notes" ], "summary": "Create a note", "description": "Create a note on an entity. Notes are append-only via the API.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "object", "in": "path", "required": true, "description": "Entity type: client, sale, or product", "schema": { "type": "string", "enum": [ "client", "sale", "product" ] } }, { "name": "token", "in": "path", "required": true, "description": "Entity token", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteCreate" } } } }, "responses": { "201": { "description": "Note created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/NoteListItem" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/invoice": { "get": { "tags": [ "Invoices" ], "summary": "List invoices", "description": "Returns a paginated list of invoices with optional filtering by status, client, date range, due date range, reference, and search.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "description": "Filter by status: draft (parked/unsent), pending (approved, balance owing), paid (fully paid), void (voided/cancelled)", "schema": { "type": "string", "enum": [ "draft", "pending", "paid", "void" ] } }, { "name": "client", "in": "query", "description": "Filter by client token (UUID)", "schema": { "type": "string", "format": "uuid" } }, { "name": "client_email", "in": "query", "description": "Filter by client email address (exact match)", "schema": { "type": "string", "format": "email" } }, { "name": "date_from", "in": "query", "description": "Filter invoices dated on or after this date (ISO 8601)", "schema": { "type": "string", "format": "date-time" }, "example": "2025-01-01" }, { "name": "date_to", "in": "query", "description": "Filter invoices dated on or before this date (ISO 8601)", "schema": { "type": "string", "format": "date-time" }, "example": "2025-12-31" }, { "name": "due_from", "in": "query", "description": "Filter invoices due on or after this date (ISO 8601)", "schema": { "type": "string", "format": "date-time" } }, { "name": "due_to", "in": "query", "description": "Filter invoices due on or before this date (ISO 8601)", "schema": { "type": "string", "format": "date-time" } }, { "name": "reference", "in": "query", "description": "Filter by exact reference number", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Search across name, reference, and email", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort order", "schema": { "type": "string", "enum": [ "newest", "oldest", "due_date_asc", "due_date_desc", "reference_asc", "reference_desc" ], "default": "newest" } }, { "name": "limit", "in": "query", "description": "Number of results per page (max 100)", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of results to skip", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of invoices", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Invoices" ], "summary": "Create invoice", "description": "Create a new invoice with line items. Requires a client and at least one line item. Invoices are created as draft by default \u2014 set `authorise` to true to approve immediately. When a product token or SKU is provided on a line, price, description, SKU, and cost price are auto-filled from the product (but can be overridden).", "security": [ { "TenantAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceCreate" } } } }, "responses": { "201": { "description": "Invoice created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/InvoiceDetail" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/invoice/{token}": { "get": { "tags": [ "Invoices" ], "summary": "Get invoice detail", "description": "Returns full invoice detail including line items, payment summary, client, and web URL.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Invoice token", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invoice detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/InvoiceDetail" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": [ "Invoices" ], "summary": "Update invoice", "description": "Update invoice header fields. Cannot modify locked invoices (invoices with payments). Use the `authorise` flag to approve or revert to draft.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Invoice token", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceUpdate" } } } }, "responses": { "200": { "description": "Updated invoice detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/InvoiceDetail" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "Invoice is locked", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Conflict" }, "message": { "type": "string", "example": "Invoice is locked (has payments) and cannot be modified" } } } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/invoice/{token}/line": { "post": { "tags": [ "Invoices" ], "summary": "Add invoice line", "description": "Add a line item to an invoice. When a product token or SKU is provided, price, description, SKU, and cost price are auto-filled from the product (but can be overridden). Cannot modify locked invoices.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Invoice token", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceLineCreate" } } } }, "responses": { "201": { "description": "Line added, returns full invoice detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/InvoiceDetail" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "Invoice is locked", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Conflict" }, "message": { "type": "string", "example": "Invoice is locked (has payments) and cannot be modified" } } } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/invoice/{token}/line/{line_id}": { "put": { "tags": [ "Invoices" ], "summary": "Update invoice line", "description": "Update an existing line item on an invoice. When a product token or SKU is provided, price, description, SKU, and cost price are auto-filled from the product (but can be overridden). Cannot modify locked invoices.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Invoice token", "schema": { "type": "string" } }, { "name": "line_id", "in": "path", "required": true, "description": "Line item ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceLineUpdate" } } } }, "responses": { "200": { "description": "Line updated, returns full invoice detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/InvoiceDetail" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "Invoice is locked", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Conflict" }, "message": { "type": "string", "example": "Invoice is locked (has payments) and cannot be modified" } } } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Invoices" ], "summary": "Delete invoice line", "description": "Remove a line item from an invoice. Cannot modify locked invoices (invoices with payments). Returns the full updated invoice detail.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Invoice token", "schema": { "type": "string" } }, { "name": "line_id", "in": "path", "required": true, "description": "Line item ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Line deleted, returns full invoice detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/InvoiceDetail" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "Invoice is locked", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Conflict" }, "message": { "type": "string", "example": "Invoice is locked (has payments) and cannot be modified" } } } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/porder": { "get": { "tags": [ "Purchase Orders" ], "summary": "List purchase orders", "description": "Returns a paginated list of purchase orders with optional filtering by status, supplier, date range, due date range, reference, and search. Forex POs include `currency_code`, `fx_rate_to_local`, and `total_forex` in the response.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "description": "Filter by status: draft (parked/unsent), open (approved with outstanding receipts), fulfil (fully receipted), void (voided/cancelled)", "schema": { "type": "string", "enum": [ "draft", "open", "fulfil", "void" ] } }, { "name": "supplier", "in": "query", "description": "Filter by supplier token (UUID)", "schema": { "type": "string", "format": "uuid" } }, { "name": "date_from", "in": "query", "description": "Filter purchase orders dated on or after this date (ISO 8601)", "schema": { "type": "string", "format": "date-time" } }, { "name": "date_to", "in": "query", "description": "Filter purchase orders dated on or before this date (ISO 8601)", "schema": { "type": "string", "format": "date-time" } }, { "name": "due_from", "in": "query", "description": "Filter by expected delivery date >= this date (ISO 8601)", "schema": { "type": "string", "format": "date-time" } }, { "name": "due_to", "in": "query", "description": "Filter by expected delivery date <= this date (ISO 8601)", "schema": { "type": "string", "format": "date-time" } }, { "name": "reference", "in": "query", "description": "Filter by exact reference number", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Search across name, reference, custom_reference, and email", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort order", "schema": { "type": "string", "enum": [ "newest", "oldest", "due_date_asc", "due_date_desc", "reference_asc", "reference_desc" ], "default": "newest" } }, { "name": "limit", "in": "query", "description": "Number of results per page (max 100)", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of results to skip", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of purchase orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "porders": { "type": "array", "items": { "$ref": "#/components/schemas/PorderSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Purchase Orders" ], "summary": "Create purchase order", "description": "Create a new purchase order with line items. Requires a supplier and at least one line item. Purchase orders are created as draft by default \u2014 set `authorise` to true to approve immediately. For forex POs, supply `currency_code` and `fx_rate_to_local` on the header and `price_forex` on each line.", "security": [ { "TenantAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PorderCreate" } } } }, "responses": { "201": { "description": "Purchase order created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/PorderDetail" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/porder/{token}": { "get": { "tags": [ "Purchase Orders" ], "summary": "Get purchase order detail", "description": "Returns full purchase order detail including line items, supplier, totals, supplier-specific meta (invoice number, acceptance date, delivery date), and forex fields if applicable.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Purchase order token", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Purchase order detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/PorderDetail" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": [ "Purchase Orders" ], "summary": "Update purchase order", "description": "Update purchase order header fields. Cannot modify a PO that has receipts against it. Use the `authorise` flag to approve or revert to draft.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Purchase order token", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PorderUpdate" } } } }, "responses": { "200": { "description": "Updated purchase order detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/PorderDetail" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "Purchase order has receipts and cannot be modified", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Conflict" }, "message": { "type": "string", "example": "Purchase order has receipts against it and cannot be modified" } } } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/porder/{token}/line": { "post": { "tags": [ "Purchase Orders" ], "summary": "Add purchase order line", "description": "Add a line item to a purchase order. When a product token or SKU is provided, price, description, SKU, and cost price are auto-filled from the product (but can be overridden). For forex POs, supply `price_forex` and the controller derives the local-currency price using the parent PO's `fx_rate_to_local`.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Purchase order token", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PorderLineCreate" } } } }, "responses": { "201": { "description": "Line added, returns full purchase order detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/PorderDetail" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "Purchase order has receipts and cannot be modified", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Conflict" }, "message": { "type": "string", "example": "Purchase order has receipts against it and cannot be modified" } } } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/porder/{token}/line/{line_id}": { "put": { "tags": [ "Purchase Orders" ], "summary": "Update purchase order line", "description": "Update an existing line item on a purchase order. Cannot modify a PO that has receipts against it.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Purchase order token", "schema": { "type": "string" } }, { "name": "line_id", "in": "path", "required": true, "description": "Line item ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PorderLineUpdate" } } } }, "responses": { "200": { "description": "Line updated, returns full purchase order detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/PorderDetail" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "Purchase order has receipts and cannot be modified", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Conflict" }, "message": { "type": "string", "example": "Purchase order has receipts against it and cannot be modified" } } } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Purchase Orders" ], "summary": "Delete purchase order line", "description": "Remove a line item from a purchase order. Cannot modify a PO that has receipts against it. Returns the full updated purchase order detail.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Purchase order token", "schema": { "type": "string" } }, { "name": "line_id", "in": "path", "required": true, "description": "Line item ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Line deleted, returns full purchase order detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/PorderDetail" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "Purchase order has receipts and cannot be modified", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Conflict" }, "message": { "type": "string", "example": "Purchase order has receipts against it and cannot be modified" } } } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/jobcard": { "get": { "tags": [ "Job Cards" ], "summary": "List job cards", "description": "Returns a paginated list of job cards with optional filtering by client, reference, status, or search term.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of results to return (max 100)", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of results to skip", "schema": { "type": "integer", "default": 0 } }, { "name": "client", "in": "query", "description": "Filter by client token", "schema": { "type": "string" } }, { "name": "reference", "in": "query", "description": "Filter by exact external reference", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by status code", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "description": "Search across title, notes, and external reference", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of job cards", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "jobcards": { "type": "array", "items": { "$ref": "#/components/schemas/JobCardSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "Job Cards" ], "summary": "Create job card", "description": "Create a new job card. Title is required. If a reference is provided it must be unique within the tenant.", "security": [ { "TenantAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCardCreateInput" } } } }, "responses": { "201": { "description": "Job card created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/JobCardDetail" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "409": { "$ref": "#/components/responses/ConflictError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/jobcard/{token}": { "get": { "tags": [ "Job Cards" ], "summary": "Get job card detail", "description": "Retrieve a single job card by token including description, dates, total, and pipeline item.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Job card token", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job card detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/JobCardDetail" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": [ "Job Cards" ], "summary": "Update job card", "description": "Update an existing job card. All fields are optional but at least one must be provided. Reference uniqueness is enforced (excluding the current job card). Pass an empty string for reference to clear it.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Job card token", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCardUpdateInput" } } } }, "responses": { "200": { "description": "Job card updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/JobCardDetail" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "$ref": "#/components/responses/ConflictError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/file": { "post": { "tags": [ "Files" ], "summary": "Upload file", "description": "Upload a file via multipart form data. Optionally attach it to an object (job card, client, or pipeline item).\n\n**Limits:**\n- Maximum file size: 50 MB\n- File extension must be in the allowed list\n- Images are auto-resized to max 1024px width", "security": [ { "TenantAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The file to upload" }, "object": { "type": "string", "enum": [ "jobcard", "client", "pipeline_item" ], "description": "Object type to attach the file to" }, "object_id": { "type": "string", "description": "Token of the object to attach to (required when object is provided)" }, "name": { "type": "string", "description": "Custom display name for the file" }, "folder_id": { "type": "integer", "description": "Folder ID for file placement" } } } } } }, "responses": { "201": { "description": "File uploaded", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/FileUploadResponse" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "413": { "description": "File too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "File too large" }, "message": { "type": "string", "example": "Maximum file size is 50MB" } } } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/product/{token}/image": { "post": { "tags": [ "Products" ], "summary": "Upload product image(s)", "description": "Upload one or more images for a product, exclusive to the product endpoint.\n\nProvide images **either** as multipart files **or** by absolute URL (the server downloads them):\n- `file` \u2014 a single image file\n- `files[]` \u2014 multiple image files\n- `url` \u2014 a single absolute http(s) URL\n- `urls[]` \u2014 multiple absolute http(s) URLs\n\n**Rules:**\n- JPG and PNG only (validated by content, not just extension)\n- Maximum size 15 MB per image; images over 2 MB are resized down to 1440px wide\n- Set the main image with `is_main=true` (applies to the first submitted image) or `main_index` (0-based index of the submitted image to make main)\n- If the product has no main image yet, the first stored image becomes the main automatically\n\nReturns the refreshed image set for the product.", "security": [ { "TenantAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Product token" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "A single JPG/PNG image" }, "files[]": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Multiple JPG/PNG images" }, "url": { "type": "string", "description": "Absolute http(s) URL of an image to download" }, "is_main": { "type": "boolean", "description": "Mark the first submitted image as the product main image" }, "main_index": { "type": "integer", "description": "0-based index of the submitted image to set as main" } } } }, "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Absolute http(s) URL of an image to download" }, "urls": { "type": "array", "items": { "type": "string" }, "description": "Absolute http(s) URLs of images to download" }, "is_main": { "type": "boolean", "description": "Mark the first submitted image as the product main image" }, "main_index": { "type": "integer", "description": "0-based index of the submitted image to set as main" } } } } } }, "responses": { "201": { "description": "Image(s) stored", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "token": { "type": "string" }, "name": { "type": "string" }, "stored": { "type": "array", "items": { "type": "string" }, "description": "Filenames stored in this request" }, "errors": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Per-image failures, if any" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/ProductImage" } } } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "tags": [ { "name": "Public", "description": "Public endpoints (no authentication required)" }, { "name": "Clients", "description": "Client management" }, { "name": "Files", "description": "File uploads" }, { "name": "Invoices", "description": "Invoice management" }, { "name": "Job Cards", "description": "Job card management" }, { "name": "Notes", "description": "Notes on entities" }, { "name": "Posts", "description": "Content management" }, { "name": "Products", "description": "Product catalogue" }, { "name": "Purchase Orders", "description": "Purchase order management (incl. forex POs)" }, { "name": "Suppliers", "description": "Supplier management" }, { "name": "Tenant", "description": "Tenant account information" } ], "components": { "securitySchemes": { "TenantAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Tenant API key authentication. Use your generated API key from Settings > API." }, "SystemApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "System API Key", "description": "System-level API key for internal operations. Only available to administrators." } }, "schemas": { "Post": { "type": "object", "description": "Full post object with content and meta data", "properties": { "id": { "type": "integer", "description": "Post ID", "example": 123 }, "token": { "type": "string", "description": "Unique token identifier", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "type": { "type": "string", "description": "Post type", "example": "page" }, "title": { "type": "string", "description": "Post title", "example": "About Us" }, "slug": { "type": "string", "description": "URL-friendly slug", "example": "about-us" }, "content": { "type": "string", "description": "Post content (HTML)", "example": "

Welcome to our company...

" }, "status": { "type": "string", "enum": [ "draft", "published", "hidden" ], "description": "Publication status", "example": "published" }, "sort": { "type": "integer", "description": "Sort order", "example": 0 }, "parent_id": { "type": "integer", "description": "Parent post ID (0 for none)", "example": 0 }, "author_id": { "type": "integer", "description": "Author user ID", "example": 1 }, "stat_add": { "type": "integer", "description": "Created timestamp (Unix)", "example": 1705123456 }, "stat_update": { "type": "integer", "description": "Last updated timestamp (Unix)", "example": 1705123456 }, "meta": { "type": "object", "description": "Key-value meta data", "additionalProperties": { "type": "string" }, "example": { "seo_title": "About Us | Company", "seo_description": "Learn about our company" } } } }, "PostSummary": { "type": "object", "description": "Post summary for list views (excludes content)", "properties": { "id": { "type": "integer", "description": "Post ID", "example": 123 }, "token": { "type": "string", "description": "Unique token identifier" }, "type": { "type": "string", "description": "Post type", "example": "page" }, "title": { "type": "string", "description": "Post title", "example": "About Us" }, "slug": { "type": "string", "description": "URL-friendly slug", "example": "about-us" }, "status": { "type": "string", "enum": [ "draft", "published", "hidden" ], "example": "published" }, "sort": { "type": "integer", "description": "Sort order", "example": 0 }, "parent_id": { "type": "integer", "description": "Parent post ID", "example": 0 }, "author_id": { "type": "integer", "description": "Author user ID", "example": 1 }, "stat_add": { "type": "integer", "description": "Created timestamp (Unix)", "example": 1705123456 }, "stat_update": { "type": "integer", "description": "Last updated timestamp (Unix)", "example": 1705123456 } } }, "PostCreate": { "type": "object", "description": "Request body for creating a new post", "required": [ "type", "title" ], "properties": { "type": { "type": "string", "description": "Post type (page, blog, news, faqs, popup, form, etc.)", "example": "page" }, "title": { "type": "string", "description": "Post title", "example": "New Page" }, "content": { "type": "string", "description": "Post content (HTML)", "example": "

Page content here...

" }, "status": { "type": "string", "enum": [ "draft", "published", "hidden" ], "default": "draft", "description": "Publication status" }, "parent_id": { "type": "integer", "description": "Parent post ID (0 for none)", "default": 0 }, "sort": { "type": "integer", "description": "Sort order", "default": 0 }, "author_id": { "type": "integer", "description": "Author user ID (must be valid user in account, defaults to API key owner)" }, "meta": { "type": "object", "description": "Key-value meta data", "additionalProperties": { "type": "string" }, "example": { "seo_title": "New Page Title" } } } }, "PostUpdate": { "type": "object", "description": "Request body for updating a post (all fields optional)", "properties": { "title": { "type": "string", "description": "Post title", "example": "Updated Title" }, "content": { "type": "string", "description": "Post content (HTML)" }, "status": { "type": "string", "enum": [ "draft", "published", "hidden" ], "description": "Publication status" }, "parent_id": { "type": "integer", "description": "Parent post ID" }, "sort": { "type": "integer", "description": "Sort order" }, "author_id": { "type": "integer", "description": "Author user ID (must be valid user in account)" }, "meta": { "type": "object", "description": "Key-value meta data to update", "additionalProperties": { "type": "string" } } } }, "Pagination": { "type": "object", "description": "Pagination information", "properties": { "total": { "type": "integer", "description": "Total number of results", "example": 100 }, "limit": { "type": "integer", "description": "Results per page", "example": 20 }, "offset": { "type": "integer", "description": "Current offset", "example": 0 }, "has_more": { "type": "boolean", "description": "Whether more results exist", "example": true } } }, "ClientSummary": { "type": "object", "description": "Client summary for list views", "properties": { "token": { "type": "string", "format": "uuid", "description": "Client token (UUID)", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "company": { "type": "string", "description": "Company name", "example": "Acme Corporation" }, "name_first": { "type": "string", "description": "First name", "example": "John" }, "name_last": { "type": "string", "description": "Last name", "example": "Smith" }, "name": { "type": "string", "description": "Display name (company or full name)", "example": "Acme Corporation" }, "email": { "type": "string", "format": "email", "description": "Email address", "example": "john@acme.com" }, "phones": { "type": "object", "description": "Phone numbers keyed by type (home, mobile, work, fax, tollfree)", "additionalProperties": { "$ref": "#/components/schemas/PhoneEntry" }, "example": { "mobile": { "number": "+64211234567", "formatted": "(021) 123 4567", "is_primary": true } } }, "website": { "type": "string", "description": "Website URL", "example": "https://acme.com" }, "type": { "type": "string", "description": "Client type label", "enum": [ "Client", "Lead", "Prospect", "Cancelled" ], "example": "Client" }, "type_code": { "type": "integer", "description": "Client type code (0=Cancelled, 1=Client, 2=Lead, 3=Prospect)", "example": 1 }, "created_at": { "type": "string", "format": "date-time", "description": "Created timestamp (ISO 8601)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last updated timestamp (ISO 8601)" } } }, "Client": { "type": "object", "description": "Full client object with addresses, contacts, and meta data", "properties": { "token": { "type": "string", "format": "uuid", "description": "Client token (UUID)", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "company": { "type": "string", "description": "Company name", "example": "Acme Corporation" }, "name_first": { "type": "string", "description": "First name", "example": "John" }, "name_last": { "type": "string", "description": "Last name", "example": "Smith" }, "name": { "type": "string", "description": "Display name (company or full name)", "example": "Acme Corporation" }, "name_full": { "type": "string", "description": "Full display name", "example": "Acme Corporation - John Smith" }, "contact_name": { "type": "string", "description": "Contact person name", "example": "John Smith" }, "email": { "type": "string", "format": "email", "description": "Email address", "example": "john@acme.com" }, "phone": { "type": "string", "description": "Legacy phone number field", "example": "+1 555-1234" }, "phones": { "type": "object", "description": "Phone numbers keyed by type (home, mobile, work, fax, tollfree)", "additionalProperties": { "$ref": "#/components/schemas/PhoneEntry" }, "example": { "home": { "number": "+6491234567", "formatted": "(09) 123 4567", "is_primary": true }, "mobile": { "number": "+64211234567", "formatted": "(021) 123 4567" } } }, "website": { "type": "string", "description": "Website URL", "example": "https://acme.com" }, "reference": { "type": "string", "description": "Internal reference code", "example": "ACME-001" }, "company_size": { "type": "string", "description": "Company size", "example": "50-100" }, "comments": { "type": "string", "description": "Free-text comments on the client record" }, "notes": { "type": "array", "description": "Recent CRM notes (last 5, newest first)", "items": { "$ref": "#/components/schemas/NoteListItem" } }, "type": { "type": "string", "description": "Client type label", "enum": [ "Client", "Lead", "Prospect", "Cancelled" ], "example": "Client" }, "type_code": { "type": "integer", "description": "Client type code (0=Cancelled, 1=Client, 2=Lead, 3=Prospect)", "example": 1 }, "mail_stop": { "type": "boolean", "description": "Whether client has opted out of emails", "example": false }, "xero_id": { "type": "string", "description": "Xero integration ID" }, "refer": { "type": "string", "description": "Referral source" }, "team_id": { "type": "integer", "description": "Assigned team ID" }, "created_at": { "type": "string", "format": "date-time", "description": "Created timestamp (ISO 8601)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last updated timestamp (ISO 8601)" }, "meta": { "type": "object", "description": "Key-value meta data", "additionalProperties": { "type": "string" }, "example": { "mobile": "+1 555-5678", "currency_code": "USD" } }, "addresses": { "type": "array", "description": "Client addresses", "items": { "$ref": "#/components/schemas/ClientAddress" } }, "contacts": { "type": "array", "description": "Client contacts", "items": { "$ref": "#/components/schemas/ClientContact" } } } }, "ClientAddress": { "type": "object", "description": "Client address", "properties": { "type": { "type": "string", "description": "Address type", "enum": [ "billing", "shipping", "physical" ], "example": "billing" }, "main": { "type": "boolean", "description": "Whether this is the main address of this type" }, "contact": { "type": "string", "description": "Contact person at this address" }, "contact_phone": { "type": "string", "description": "Contact phone at this address" }, "address": { "type": "string", "description": "Street address", "example": "123 Main Street" }, "suburb": { "type": "string", "description": "Suburb/neighborhood" }, "city": { "type": "string", "description": "City", "example": "New York" }, "state": { "type": "string", "description": "State/province", "example": "NY" }, "country": { "type": "string", "description": "Country", "example": "United States" }, "post_code": { "type": "string", "description": "Postal/ZIP code", "example": "10001" } } }, "ClientContact": { "type": "object", "description": "Client contact person", "properties": { "name_first": { "type": "string", "description": "First name", "example": "Jane" }, "name_last": { "type": "string", "description": "Last name", "example": "Doe" }, "email": { "type": "string", "format": "email", "description": "Email address", "example": "jane@acme.com" }, "phone": { "type": "string", "description": "Legacy phone number field" }, "phones": { "type": "object", "description": "Phone numbers keyed by type (home, mobile, work, fax, tollfree)", "additionalProperties": { "$ref": "#/components/schemas/PhoneEntry" } }, "role": { "type": "string", "description": "Role/title", "example": "Purchasing Manager" }, "main": { "type": "boolean", "description": "Whether this is the primary contact" } } }, "PhoneEntry": { "type": "object", "description": "A phone number entry", "properties": { "number": { "type": "string", "description": "Phone number in E.164 format", "example": "+64211234567" }, "formatted": { "type": "string", "description": "Formatted national number", "example": "(021) 123 4567" }, "is_primary": { "type": "boolean", "description": "Whether this is the primary phone number (only present when true)" } } }, "ClientCreateInput": { "type": "object", "description": "Input for creating a new client. At least one of company, name_first, name_last, or email is required.", "properties": { "company": { "type": "string", "description": "Company name", "example": "Acme Corporation" }, "name_first": { "type": "string", "description": "First name", "example": "John" }, "name_last": { "type": "string", "description": "Last name", "example": "Smith" }, "email": { "type": "string", "format": "email", "description": "Email address", "example": "john@acme.com" }, "phone": { "type": "string", "description": "Legacy phone number field", "example": "+1 555-1234" }, "phones": { "type": "object", "description": "Phone numbers keyed by type. Pass a number string to create/update, or empty string to remove.", "additionalProperties": { "type": "string" }, "example": { "mobile": "+64211234567", "home": "+6491234567" } }, "website": { "type": "string", "description": "Website URL", "example": "https://acme.com" }, "reference": { "type": "string", "description": "Internal reference code", "example": "ACME-001" }, "company_size": { "type": "string", "description": "Company size", "example": "50-100" }, "comments": { "type": "string", "description": "Free-text comments on the client record" }, "type": { "type": "integer", "description": "Client type (0=Cancelled, 1=Client, 2=Lead, 3=Prospect)", "default": 1, "example": 1 }, "refer": { "type": "string", "description": "Referral source" }, "mail_stop": { "type": "boolean", "description": "Opt out of emails", "default": false }, "addresses": { "type": "array", "description": "Client addresses to create", "items": { "$ref": "#/components/schemas/AddressInput" } }, "contacts": { "type": "array", "description": "Client contacts to create", "items": { "$ref": "#/components/schemas/ContactInput" } } } }, "SupplierCreateInput": { "type": "object", "description": "Input for creating a new supplier. At least one of company, name_first, name_last, or email is required.", "properties": { "company": { "type": "string", "description": "Company name", "example": "Supplier Co" }, "name_first": { "type": "string", "description": "First name", "example": "John" }, "name_last": { "type": "string", "description": "Last name", "example": "Smith" }, "email": { "type": "string", "format": "email", "description": "Email address", "example": "john@supplier.com" }, "phone": { "type": "string", "description": "Phone number" }, "website": { "type": "string", "description": "Website URL" }, "reference": { "type": "string", "description": "Internal reference code" }, "notes": { "type": "string", "description": "Internal notes" }, "currency_code": { "type": "string", "description": "Supplier currency code (e.g., USD, NZD)", "example": "USD" }, "mail_stop": { "type": "boolean", "description": "Opt out of emails", "default": false }, "addresses": { "type": "array", "description": "Supplier addresses to create", "items": { "$ref": "#/components/schemas/AddressInput" } }, "contacts": { "type": "array", "description": "Supplier contacts to create", "items": { "$ref": "#/components/schemas/ContactInput" } } } }, "AddressInput": { "type": "object", "description": "Input for creating an address", "properties": { "type": { "type": "string", "description": "Address type", "enum": [ "billing", "shipping", "physical" ], "default": "shipping", "example": "shipping" }, "main": { "type": "boolean", "description": "Whether this is the main address of this type", "default": false }, "contact": { "type": "string", "description": "Contact person at this address" }, "contact_phone": { "type": "string", "description": "Contact phone at this address" }, "address": { "type": "string", "description": "Street address", "example": "123 Main Street" }, "suburb": { "type": "string", "description": "Suburb/neighborhood" }, "city": { "type": "string", "description": "City", "example": "New York" }, "state": { "type": "string", "description": "State/province", "example": "NY" }, "country": { "type": "string", "description": "Country", "example": "United States" }, "post_code": { "type": "string", "description": "Postal/ZIP code", "example": "10001" } } }, "ContactInput": { "type": "object", "description": "Input for creating a contact", "properties": { "name_first": { "type": "string", "description": "First name", "example": "Jane" }, "name_last": { "type": "string", "description": "Last name", "example": "Doe" }, "email": { "type": "string", "format": "email", "description": "Email address", "example": "jane@acme.com" }, "phone": { "type": "string", "description": "Legacy phone number field" }, "mobile": { "type": "string", "description": "Legacy mobile phone number field" }, "phones": { "type": "object", "description": "Phone numbers keyed by type. Pass a number string to create/update, or empty string to remove.", "additionalProperties": { "type": "string" }, "example": { "mobile": "+64211234567" } }, "role": { "type": "string", "description": "Role/title", "example": "Purchasing Manager" }, "main": { "type": "boolean", "description": "Whether this is the primary contact", "default": false }, "notes": { "type": "string", "description": "Contact notes" } } }, "ClientUpdateInput": { "type": "object", "description": "Input for updating a client. All fields are optional. Note: Addresses and contacts cannot be updated via this endpoint.", "properties": { "company": { "type": "string", "description": "Company name", "example": "Acme Corporation" }, "name_first": { "type": "string", "description": "First name", "example": "John" }, "name_last": { "type": "string", "description": "Last name", "example": "Smith" }, "email": { "type": "string", "format": "email", "description": "Email address", "example": "john@acme.com" }, "phone": { "type": "string", "description": "Legacy phone number field", "example": "+1 555-1234" }, "phones": { "type": "object", "description": "Phone numbers keyed by type. Pass a number string to create/update, or empty string to remove.", "additionalProperties": { "type": "string" }, "example": { "mobile": "+64211234567" } }, "website": { "type": "string", "description": "Website URL", "example": "https://acme.com" }, "reference": { "type": "string", "description": "Internal reference code", "example": "ACME-001" }, "company_size": { "type": "string", "description": "Company size", "example": "50-100" }, "comments": { "type": "string", "description": "Free-text comments on the client record" }, "type": { "type": "integer", "description": "Client type (0=Cancelled, 1=Client, 2=Lead, 3=Prospect)", "example": 1 }, "refer": { "type": "string", "description": "Referral source" }, "mail_stop": { "type": "boolean", "description": "Opt out of emails" } } }, "SupplierUpdateInput": { "type": "object", "description": "Input for updating a supplier. All fields are optional. Note: Addresses and contacts cannot be updated via this endpoint.", "properties": { "company": { "type": "string", "description": "Company name", "example": "Supplier Co" }, "name_first": { "type": "string", "description": "First name", "example": "John" }, "name_last": { "type": "string", "description": "Last name", "example": "Smith" }, "email": { "type": "string", "format": "email", "description": "Email address", "example": "john@supplier.com" }, "phone": { "type": "string", "description": "Phone number" }, "website": { "type": "string", "description": "Website URL" }, "reference": { "type": "string", "description": "Internal reference code" }, "notes": { "type": "string", "description": "Internal notes" }, "currency_code": { "type": "string", "description": "Supplier currency code (e.g., USD, NZD)", "example": "USD" }, "mail_stop": { "type": "boolean", "description": "Opt out of emails" } } }, "SupplierSummary": { "type": "object", "description": "Supplier summary for list views", "properties": { "token": { "type": "string", "format": "uuid", "description": "Supplier token (UUID)", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "company": { "type": "string", "description": "Company name", "example": "Supplier Co" }, "name_first": { "type": "string", "description": "First name", "example": "John" }, "name_last": { "type": "string", "description": "Last name", "example": "Smith" }, "name": { "type": "string", "description": "Display name (company or full name)", "example": "Supplier Co" }, "email": { "type": "string", "format": "email", "description": "Email address", "example": "john@supplier.com" }, "phone": { "type": "string", "description": "Phone number" }, "website": { "type": "string", "description": "Website URL" }, "currency_code": { "type": "string", "description": "Supplier currency code (defaults to tenant currency if not set)", "example": "USD" }, "created_at": { "type": "string", "format": "date-time", "description": "Created timestamp (ISO 8601)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last updated timestamp (ISO 8601)" } } }, "ProductSummary": { "type": "object", "description": "Product summary for list views", "properties": { "token": { "type": "string", "description": "Product token" }, "name": { "type": "string", "description": "Product name", "example": "Widget A" }, "sku": { "type": "string", "description": "SKU", "example": "WID-001" }, "sku_vendor": { "type": "string", "description": "Vendor SKU" }, "barcode": { "type": "string", "nullable": true, "description": "Product barcode (null if not set)" }, "type": { "type": "string", "description": "Product type", "example": "product" }, "type_variant": { "type": "integer", "description": "Variant flag (0=standalone, 1=variant)" }, "slug": { "type": "string", "description": "URL-friendly slug", "example": "widget-a" }, "description": { "type": "string", "nullable": true, "description": "Plain text description (HTML stripped, max 1024 chars). Use GET /product/{token} for full HTML." }, "status": { "type": "integer", "description": "Status (0=inactive, 1=active)", "example": 1 }, "hide": { "type": "integer", "description": "Website hidden flag \u2014 controls front-end website visibility only, does not hide the product in Zulu (0=visible, 1=hidden)", "example": 0 }, "prices": { "type": "object", "description": "Retail prices only", "properties": { "price": { "type": "number", "format": "float", "example": 29.99 }, "price_special": { "type": "number", "format": "float", "example": 0 } } }, "stock": { "$ref": "#/components/schemas/ProductStock" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/ProductImage" } }, "brand": { "type": "object", "nullable": true, "description": "Product brand", "properties": { "token": { "type": "string", "format": "uuid", "description": "Brand token" }, "title": { "type": "string", "description": "Brand name" } } }, "supplier": { "type": "object", "nullable": true, "description": "Product supplier", "properties": { "token": { "type": "string", "format": "uuid", "description": "Supplier token" }, "name": { "type": "string", "description": "Supplier name" }, "email": { "type": "string", "format": "email", "description": "Supplier email" } } }, "parent_id": { "type": "integer", "description": "Parent product ID" }, "web_url": { "type": "string", "nullable": true, "description": "Public web URL for the product (null if website module not enabled)" }, "created_at": { "type": "string", "format": "date-time", "description": "Created timestamp (ISO 8601)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last updated timestamp (ISO 8601)" } } }, "Product": { "type": "object", "description": "Full product object with prices, categories, tags, and meta", "properties": { "token": { "type": "string", "description": "Product token" }, "name": { "type": "string", "description": "Product name", "example": "Widget A" }, "sku": { "type": "string", "description": "SKU", "example": "WID-001" }, "sku_vendor": { "type": "string", "description": "Vendor SKU" }, "slug": { "type": "string", "description": "URL-friendly slug" }, "description": { "type": "string", "description": "Product description" }, "type": { "type": "string", "description": "Product type", "example": "product" }, "type_variant": { "type": "integer", "description": "Variant flag" }, "status": { "type": "integer", "description": "Status (0=inactive, 1=active)" }, "hide": { "type": "integer", "description": "Website hidden flag \u2014 controls front-end website visibility only, does not hide the product in Zulu" }, "hide_public": { "type": "integer", "description": "Public hidden flag" }, "brand": { "type": "object", "nullable": true, "description": "Product brand", "properties": { "token": { "type": "string", "format": "uuid", "description": "Brand token" }, "title": { "type": "string", "description": "Brand name" } } }, "supplier": { "type": "object", "nullable": true, "description": "Product supplier", "properties": { "token": { "type": "string", "format": "uuid", "description": "Supplier token" }, "name": { "type": "string", "description": "Supplier name" }, "email": { "type": "string", "format": "email", "description": "Supplier email" } } }, "parent_id": { "type": "integer", "description": "Parent product ID" }, "sort": { "type": "integer", "description": "Sort order" }, "prices": { "$ref": "#/components/schemas/ProductPrices" }, "stock": { "$ref": "#/components/schemas/ProductStock" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/ProductImage" } }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCategoryItem" } }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/ProductTagItem" } }, "meta": { "type": "object", "description": "Product meta data", "additionalProperties": { "type": "string" }, "example": { "barcode": "1234567890123" } }, "web_url": { "type": "string", "nullable": true, "description": "Public web URL for the product (null if website module not enabled)" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ProductPrices": { "type": "object", "description": "All product price fields", "properties": { "price": { "type": "number", "format": "float", "description": "Retail price", "example": 29.99 }, "price_special": { "type": "number", "format": "float", "description": "Special/promotional price", "example": 24.99 }, "price_purchase": { "type": "number", "format": "float", "description": "Purchase price (system-managed)" }, "price_latest_landed": { "type": "number", "format": "float", "description": "Latest landed cost (system-managed)" }, "price_average": { "type": "number", "format": "float", "description": "Weighted average cost (system-managed)" }, "price_ws1": { "type": "number", "format": "float", "description": "Wholesale price 1" }, "price_ws2": { "type": "number", "format": "float", "description": "Wholesale price 2" }, "price_ws3": { "type": "number", "format": "float", "description": "Wholesale price 3" }, "price_ws4": { "type": "number", "format": "float", "description": "Wholesale price 4" }, "price_ws5": { "type": "number", "format": "float", "description": "Wholesale price 5" }, "price_ws6": { "type": "number", "format": "float", "description": "Wholesale price 6" }, "price_ws7": { "type": "number", "format": "float", "description": "Wholesale price 7" } } }, "ProductStock": { "type": "object", "description": "Product stock levels", "properties": { "on_hand": { "type": "number", "format": "float", "description": "Current available stock on hand", "example": 42 }, "allocated": { "type": "number", "format": "float", "description": "Stock allocated to orders", "example": 5 }, "on_order": { "type": "number", "format": "float", "description": "Stock on unfulfilled purchase orders", "example": 20 } } }, "ProductImage": { "type": "object", "description": "A product image", "properties": { "filename": { "type": "string", "description": "Image filename within the product folder", "example": "red-widget.jpg" }, "url": { "type": "string", "description": "Relative URL to the image", "example": "file/product/123/red-widget.jpg" }, "is_main": { "type": "boolean", "description": "Whether this is the product main image" } } }, "ProductCategoryItem": { "type": "object", "description": "Product category assignment", "properties": { "id": { "type": "integer", "description": "Category product ID", "example": 42 }, "name": { "type": "string", "description": "Category name", "example": "Electronics" }, "slug": { "type": "string", "description": "Category slug", "example": "electronics" } } }, "ProductTagItem": { "type": "object", "description": "Product tag assignment", "properties": { "tag_option_id": { "type": "integer", "description": "Tag option ID", "example": 7 }, "tag_option_token": { "type": "string", "description": "Tag option token", "example": "7ad2acde-4cdf-4b85-bf89-249586e7e686" }, "tag_name": { "type": "string", "description": "Tag group name", "example": "Material" }, "option_name": { "type": "string", "description": "Tag option value", "example": "Metal" } } }, "ProductCreateInput": { "type": "object", "description": "Input for creating a new product", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Product name", "example": "Widget A" }, "sku": { "type": "string", "description": "SKU", "example": "WID-001" }, "sku_vendor": { "type": "string", "description": "Vendor SKU" }, "description": { "type": "string", "description": "Product description" }, "status": { "type": "integer", "description": "Status (0=inactive, 1=active)", "default": 1 }, "hide": { "type": "integer", "description": "Website hidden flag \u2014 controls front-end website visibility only, does not hide the product in Zulu", "default": 0 }, "hide_public": { "type": "integer", "description": "Public hidden flag", "default": 0 }, "brand": { "type": "string", "format": "uuid", "description": "Brand token (UUID)" }, "supplier": { "type": "string", "format": "uuid", "description": "Supplier token (UUID)" }, "parent_id": { "type": "integer", "description": "Parent product ID" }, "sort": { "type": "integer", "description": "Sort order" }, "barcode": { "type": "string", "description": "Product barcode", "example": "1234567890123" }, "prices": { "type": "object", "description": "Initial prices (only user-editable fields: price, price_special, price_ws1-7)", "properties": { "price": { "type": "number", "format": "float", "example": 29.99 }, "price_special": { "type": "number", "format": "float" }, "price_ws1": { "type": "number", "format": "float" }, "price_ws2": { "type": "number", "format": "float" }, "price_ws3": { "type": "number", "format": "float" }, "price_ws4": { "type": "number", "format": "float" }, "price_ws5": { "type": "number", "format": "float" }, "price_ws6": { "type": "number", "format": "float" }, "price_ws7": { "type": "number", "format": "float" } } }, "categories": { "type": "array", "items": { "type": "integer" }, "description": "Array of category product IDs", "example": [ 42, 55 ] }, "tags": { "type": "array", "items": { "type": "integer" }, "description": "Array of tag option IDs", "example": [ 7, 12 ] } } }, "ProductUpdateInput": { "type": "object", "description": "Input for updating a product. All fields optional. Prices cannot be updated here \u2014 use PUT /product/{token}/price.", "properties": { "name": { "type": "string", "description": "Product name" }, "sku": { "type": "string", "description": "SKU" }, "sku_vendor": { "type": "string", "description": "Vendor SKU" }, "description": { "type": "string", "description": "Product description" }, "status": { "type": "integer", "description": "Status (0=inactive, 1=active)" }, "hide": { "type": "integer", "description": "Website hidden flag \u2014 controls front-end website visibility only, does not hide the product in Zulu" }, "hide_public": { "type": "integer", "description": "Public hidden flag" }, "brand": { "type": "string", "format": "uuid", "description": "Brand token (UUID). Pass null to clear." }, "supplier": { "type": "string", "format": "uuid", "description": "Supplier token (UUID). Pass null to clear." }, "parent_id": { "type": "integer", "description": "Parent product ID" }, "sort": { "type": "integer", "description": "Sort order" }, "barcode": { "type": "string", "description": "Product barcode" } } }, "ProductPriceUpdateInput": { "type": "object", "description": "Input for updating product prices. Only user-editable price fields are accepted. System-managed fields (price_purchase, price_latest_landed, price_average) are rejected.", "properties": { "price": { "type": "number", "format": "float", "description": "Retail price", "example": 29.99 }, "price_special": { "type": "number", "format": "float", "description": "Special price" }, "price_ws1": { "type": "number", "format": "float", "description": "Wholesale price 1" }, "price_ws2": { "type": "number", "format": "float", "description": "Wholesale price 2" }, "price_ws3": { "type": "number", "format": "float", "description": "Wholesale price 3" }, "price_ws4": { "type": "number", "format": "float", "description": "Wholesale price 4" }, "price_ws5": { "type": "number", "format": "float", "description": "Wholesale price 5" }, "price_ws6": { "type": "number", "format": "float", "description": "Wholesale price 6" }, "price_ws7": { "type": "number", "format": "float", "description": "Wholesale price 7" } } }, "TaxonomyCategory": { "type": "object", "description": "Category node in the taxonomy tree", "properties": { "token": { "type": "string", "description": "Category token", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "name": { "type": "string", "description": "Category name", "example": "Electronics" }, "slug": { "type": "string", "description": "URL-safe slug", "example": "electronics" }, "children": { "type": "array", "description": "Child categories", "items": { "$ref": "#/components/schemas/TaxonomyCategory" } } } }, "TaxonomyTag": { "type": "object", "description": "Tag group node in the taxonomy tree", "properties": { "token": { "type": "string", "description": "Tag group token", "example": "7ad2acde-4cdf-4b85-bf89-249586e7e686" }, "title": { "type": "string", "description": "Tag group title", "example": "Color" }, "slug": { "type": "string", "description": "URL-safe slug", "example": "color" }, "options": { "type": "array", "description": "Tag options within this group", "items": { "type": "object", "properties": { "token": { "type": "string", "description": "Tag option token", "example": "02312c04-cf99-4fcd-bb45-1a0dec9fc106" }, "title": { "type": "string", "description": "Option title", "example": "Red" }, "slug": { "type": "string", "description": "URL-safe slug", "example": "red" } } } }, "children": { "type": "array", "description": "Child tag groups", "items": { "$ref": "#/components/schemas/TaxonomyTag" } } } }, "TaxonomyBrand": { "type": "object", "description": "Brand in the taxonomy list", "properties": { "token": { "type": "string", "format": "uuid", "description": "Brand token" }, "title": { "type": "string", "description": "Brand name", "example": "Nike" }, "slug": { "type": "string", "description": "URL-safe slug", "example": "nike" } } }, "InvoiceSummary": { "type": "object", "description": "Invoice summary for list views", "properties": { "token": { "type": "string", "description": "Invoice token" }, "reference": { "type": "string", "description": "Formatted invoice reference", "example": "INV-001042" }, "reference_no": { "type": "integer", "description": "Raw reference sequence number", "example": 1042 }, "name": { "type": "string", "description": "Invoice name", "example": "Invoice #1042" }, "date": { "type": "string", "format": "date-time", "nullable": true, "description": "Invoice date (ISO 8601)" }, "date_due": { "type": "string", "format": "date-time", "nullable": true, "description": "Due date (ISO 8601)" }, "status": { "type": "string", "enum": [ "draft", "pending", "paid", "void" ], "description": "Invoice status", "example": "pending" }, "client_reference": { "type": "string", "nullable": true, "description": "Client reference / purchase order number", "example": "PO-2026-001" }, "client": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InvoiceClient" } ], "description": "Client object or null if no client assigned" }, "total": { "type": "number", "format": "float", "description": "Invoice total (inc tax)", "example": 150 }, "total_paid": { "type": "number", "format": "float", "description": "Total amount paid", "example": 100 }, "balance": { "type": "number", "format": "float", "description": "Outstanding balance", "example": 50 }, "web_url": { "type": "string", "nullable": true, "description": "Public web URL for payment (null if website module not enabled)" } } }, "InvoiceDetail": { "type": "object", "description": "Full invoice detail with lines and payment summary", "properties": { "token": { "type": "string", "description": "Invoice token" }, "reference": { "type": "string", "description": "Formatted invoice reference", "example": "INV-001042" }, "reference_no": { "type": "integer", "description": "Raw reference sequence number", "example": 1042 }, "name": { "type": "string", "description": "Invoice name" }, "date": { "type": "string", "format": "date-time", "nullable": true, "description": "Invoice date (ISO 8601)" }, "date_due": { "type": "string", "format": "date-time", "nullable": true, "description": "Due date (ISO 8601)" }, "status": { "type": "string", "enum": [ "draft", "pending", "paid", "void" ], "description": "Invoice status", "example": "pending" }, "client_reference": { "type": "string", "nullable": true, "description": "Client reference / purchase order number", "example": "PO-2026-001" }, "email": { "type": "string", "format": "email", "nullable": true, "description": "Invoice email address" }, "tax_method": { "type": "integer", "description": "Tax method (0=exclusive, 1=inclusive)" }, "tax_rate": { "type": "number", "format": "float", "description": "Tax rate percentage", "example": 15 }, "tax_disable": { "type": "integer", "description": "Tax disabled flag (0=enabled, 1=disabled)" }, "note_print": { "type": "string", "nullable": true, "description": "Notes displayed on the printed/PDF invoice. Supports HTML." }, "note_internal": { "type": "string", "nullable": true, "description": "Internal notes visible only within the system. Not shown on printed invoices. Supports HTML." }, "client": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InvoiceClient" } ], "description": "Client object or null" }, "lines": { "type": "array", "description": "Invoice line items", "items": { "$ref": "#/components/schemas/InvoiceLine" } }, "payment_summary": { "$ref": "#/components/schemas/InvoicePaymentSummary" }, "web_url": { "type": "string", "nullable": true, "description": "Public web URL for payment" }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Created timestamp (ISO 8601)" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Last updated timestamp (ISO 8601)" } } }, "InvoiceLine": { "type": "object", "description": "Invoice line item", "properties": { "id": { "type": "integer", "description": "Line item ID, used as line_id for update/delete operations", "example": 267 }, "sku": { "type": "string", "nullable": true, "description": "Product SKU", "example": "WID-001" }, "product_token": { "type": "string", "format": "uuid", "nullable": true, "description": "Product token (null for manual lines)" }, "description": { "type": "string", "nullable": true, "description": "Line item description", "example": "Widget A" }, "quantity": { "type": "number", "format": "float", "description": "Quantity", "example": 2 }, "discount": { "type": "number", "format": "float", "description": "Discount amount", "example": 0 }, "unit_price": { "type": "number", "format": "float", "description": "Unit price", "example": 29.99 }, "line_total": { "type": "number", "format": "float", "description": "Line total", "example": 59.98 } } }, "InvoicePaymentSummary": { "type": "object", "description": "Invoice payment breakdown", "properties": { "subtotal": { "type": "number", "format": "float", "description": "Subtotal before tax", "example": 130.43 }, "tax": { "type": "number", "format": "float", "description": "Tax amount", "example": 19.57 }, "total": { "type": "number", "format": "float", "description": "Invoice total", "example": 150 }, "paid": { "type": "number", "format": "float", "description": "Total paid", "example": 100 }, "balance": { "type": "number", "format": "float", "description": "Outstanding balance", "example": 50 } } }, "InvoiceClient": { "type": "object", "description": "Client reference on an invoice", "properties": { "token": { "type": "string", "format": "uuid", "description": "Client token" }, "name": { "type": "string", "description": "Client display name", "example": "Acme Corp" }, "email": { "type": "string", "format": "email", "nullable": true, "description": "Client email" } } }, "NoteListItem": { "type": "object", "description": "CRM note entry", "properties": { "date": { "type": "string", "format": "date-time", "nullable": true, "description": "Note date (ISO 8601)" }, "action": { "type": "string", "description": "Note action key. Tenant-managed per object type (see Settings \u2192 Note Actions); the legacy defaults phone, email, meet, conference always resolve. Empty string for no action." }, "title": { "type": "string", "description": "Note title", "example": "Follow-up call" }, "content": { "type": "string", "nullable": true, "description": "Note content (plain text, truncated to 128 chars)", "example": "Discussed pricing options..." } } }, "NoteCreate": { "type": "object", "required": [ "title" ], "description": "Create a new note on an entity", "properties": { "title": { "type": "string", "description": "Note title", "example": "Follow-up call" }, "content": { "type": "string", "description": "Note content (HTML allowed)", "example": "Discussed pricing options and agreed on next steps." }, "action": { "type": "string", "description": "Note action key. Tenant-managed per object type (see Settings \u2192 Note Actions); the legacy defaults phone, email, meet, conference always resolve. Empty string for no action.", "default": "" }, "date": { "type": "string", "format": "date-time", "description": "Note date (ISO 8601). Defaults to now." } } }, "InvoiceCreate": { "type": "object", "required": [ "client", "lines" ], "description": "Create a new invoice. Invoices are created as draft by default.", "properties": { "client": { "type": "string", "format": "uuid", "description": "Client token (UUID)" }, "name": { "type": "string", "description": "Invoice name/title. Defaults to client name.", "example": "Website redesign" }, "date": { "type": "string", "format": "date-time", "description": "Invoice date (ISO 8601). Defaults to today.", "example": "2026-02-18" }, "date_due": { "type": "string", "format": "date-time", "description": "Due date (ISO 8601). Defaults to client payment terms.", "example": "2026-03-18" }, "email": { "type": "string", "format": "email", "description": "Invoice email address. Defaults to client email." }, "tax_method": { "type": "integer", "description": "Tax method (0=exclusive, 1=inclusive). Defaults to account setting." }, "tax_rate": { "type": "number", "format": "float", "description": "Tax rate percentage. Defaults to account setting.", "example": 15 }, "tax_disable": { "type": "integer", "description": "Disable tax (0=enabled, 1=disabled)", "default": 0 }, "client_reference": { "type": "string", "description": "Client reference or purchase order number", "example": "PO-2026-001" }, "authorise": { "type": "boolean", "description": "Set to true to approve the invoice immediately instead of saving as draft", "default": false }, "note_print": { "type": "string", "description": "Notes displayed on the printed/PDF invoice. Supports HTML." }, "note_internal": { "type": "string", "description": "Internal notes visible only within the system. Not shown on printed invoices. Supports HTML." }, "lines": { "type": "array", "minItems": 1, "description": "Line items. At least one is required.", "items": { "$ref": "#/components/schemas/InvoiceLineCreate" } } } }, "InvoiceUpdate": { "type": "object", "description": "Update invoice header fields. Only provided fields are updated. Cannot modify locked invoices (invoices with payments).", "properties": { "client": { "type": "string", "format": "uuid", "description": "Client token (UUID). Also updates invoice name to the new client name." }, "name": { "type": "string", "description": "Invoice name/title" }, "date": { "type": "string", "format": "date-time", "description": "Invoice date (ISO 8601)" }, "date_due": { "type": "string", "format": "date-time", "description": "Due date (ISO 8601)" }, "email": { "type": "string", "format": "email", "description": "Invoice email address" }, "tax_method": { "type": "integer", "description": "Tax method (0=exclusive, 1=inclusive)" }, "tax_rate": { "type": "number", "format": "float", "description": "Tax rate percentage" }, "tax_disable": { "type": "integer", "description": "Disable tax (0=enabled, 1=disabled)" }, "client_reference": { "type": "string", "description": "Client reference or purchase order number" }, "authorise": { "type": "boolean", "description": "Set to true to approve, false to revert to draft" }, "note_print": { "type": "string", "description": "Notes displayed on the printed/PDF invoice. Supports HTML." }, "note_internal": { "type": "string", "description": "Internal notes visible only within the system. Not shown on printed invoices. Supports HTML." } } }, "InvoiceLineCreate": { "type": "object", "description": "Create a line item. Provide a product token or SKU to auto-fill price, description, SKU, and cost price from the product. Any explicitly provided values override the auto-filled ones.", "properties": { "product": { "type": "string", "format": "uuid", "description": "Product token (UUID). Auto-fills price, description, SKU, and cost price." }, "sku": { "type": "string", "description": "Product SKU. Used to look up product if product token not provided. Also auto-fills fields from product.", "example": "WID-001" }, "description": { "type": "string", "description": "Line item description. Auto-filled from product name if product provided.", "example": "Widget A" }, "quantity": { "type": "number", "format": "float", "description": "Quantity", "default": 1, "example": 2 }, "price": { "type": "number", "format": "float", "description": "Unit price. Auto-filled from product sell price if product provided.", "example": 29.99 }, "discount": { "type": "number", "format": "float", "description": "Flat discount amount", "default": 0, "example": 5 }, "extra": { "type": "number", "format": "float", "description": "Additional surcharge amount", "default": 0 }, "sort": { "type": "integer", "description": "Sort order position" } } }, "InvoiceLineUpdate": { "type": "object", "description": "Update a line item. Provide a product token or SKU to re-resolve and auto-fill fields. Any explicitly provided values override auto-filled ones.", "properties": { "product": { "type": "string", "format": "uuid", "description": "Product token (UUID). Auto-fills price, description, SKU, and cost price." }, "sku": { "type": "string", "description": "Product SKU. Used to look up product if product token not provided." }, "description": { "type": "string", "description": "Line item description" }, "quantity": { "type": "number", "format": "float", "description": "Quantity" }, "price": { "type": "number", "format": "float", "description": "Unit price" }, "discount": { "type": "number", "format": "float", "description": "Flat discount amount" }, "extra": { "type": "number", "format": "float", "description": "Additional surcharge amount" }, "sort": { "type": "integer", "description": "Sort order position" } } }, "PorderSupplier": { "type": "object", "description": "Supplier reference on a purchase order", "properties": { "token": { "type": "string", "format": "uuid", "description": "Supplier token (UUID)" }, "name": { "type": "string", "description": "Supplier display name", "example": "Euro Goods GmBH" }, "email": { "type": "string", "format": "email", "nullable": true, "description": "Supplier email" } } }, "PorderLine": { "type": "object", "description": "Purchase order line item. Forex fields (`unit_price_forex`, `line_total_forex`, `unit_price_landed`, `line_total_landed`) are only present on forex POs.", "properties": { "id": { "type": "integer", "description": "Line item ID, used as line_id for update/delete operations", "example": 75 }, "sku": { "type": "string", "nullable": true, "description": "Product SKU", "example": "103046" }, "product_token": { "type": "string", "format": "uuid", "nullable": true, "description": "Product token (null for manual lines)" }, "description": { "type": "string", "nullable": true, "description": "Line item description", "example": "Gouda Cheese" }, "quantity": { "type": "number", "format": "float", "description": "Quantity", "example": 10 }, "discount": { "type": "number", "format": "float", "description": "Discount amount", "example": 0 }, "unit_price": { "type": "number", "format": "float", "description": "Unit price in local currency", "example": 78.63 }, "line_total": { "type": "number", "format": "float", "description": "Line total in local currency", "example": 786.2 }, "unit_price_forex": { "type": "number", "format": "float", "nullable": true, "description": "Unit price in supplier currency (forex POs only)", "example": 42.5 }, "line_total_forex": { "type": "number", "format": "float", "nullable": true, "description": "Line total in supplier currency (forex POs only)", "example": 425 }, "unit_price_landed": { "type": "number", "format": "float", "nullable": true, "description": "Final landed unit cost in local currency, including allocated landed costs (forex POs only, populated by the receipt/landed-cost flow)" }, "line_total_landed": { "type": "number", "format": "float", "nullable": true, "description": "Final landed line total in local currency (forex POs only)" } } }, "PorderTotals": { "type": "object", "description": "Purchase order totals. `total_forex` only present on forex POs.", "properties": { "subtotal": { "type": "number", "format": "float", "description": "Subtotal before tax", "example": 841.7 }, "tax": { "type": "number", "format": "float", "description": "Tax amount", "example": 126.26 }, "total": { "type": "number", "format": "float", "description": "Order total in local currency", "example": 967.96 }, "total_forex": { "type": "number", "format": "float", "nullable": true, "description": "Order total in supplier currency (forex POs only)", "example": 455 } } }, "PorderSummary": { "type": "object", "description": "Purchase order summary for list views. Forex fields only present on forex POs.", "properties": { "token": { "type": "string", "description": "Purchase order token" }, "reference": { "type": "string", "description": "Formatted PO reference", "example": "PO-000049" }, "reference_no": { "type": "integer", "description": "Raw reference sequence number", "example": 49 }, "custom_reference": { "type": "string", "nullable": true, "description": "Custom reference set by the user", "example": "API-TEST-FOREX-001" }, "name": { "type": "string", "description": "PO name (typically the supplier)", "example": "Euro Goods GmBH" }, "date": { "type": "string", "format": "date-time", "nullable": true, "description": "PO date (ISO 8601)" }, "date_due": { "type": "string", "format": "date-time", "nullable": true, "description": "Expected delivery date (ISO 8601)" }, "status": { "type": "string", "enum": [ "draft", "open", "fulfil", "void" ], "description": "PO status", "example": "open" }, "supplier": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PorderSupplier" } ], "description": "Supplier object or null" }, "total": { "type": "number", "format": "float", "description": "Order total in local currency", "example": 967.96 }, "currency_code": { "type": "string", "nullable": true, "description": "ISO 4217 currency code (only present on forex POs)", "example": "EUR" }, "fx_rate_to_local": { "type": "number", "format": "float", "nullable": true, "description": "FX rate from supplier currency to local currency (only present on forex POs)", "example": 1.85 }, "total_forex": { "type": "number", "format": "float", "nullable": true, "description": "Order total in supplier currency (only present on forex POs)", "example": 455 } } }, "PorderDetail": { "type": "object", "description": "Full purchase order detail with lines, supplier, totals, and meta. Forex fields (`currency_code`, `fx_rate_to_local`) only present on forex POs.", "properties": { "token": { "type": "string", "description": "Purchase order token" }, "reference": { "type": "string", "description": "Formatted PO reference", "example": "PO-000049" }, "reference_no": { "type": "integer", "description": "Raw reference sequence number", "example": 49 }, "custom_reference": { "type": "string", "nullable": true, "description": "Custom reference set by the user" }, "name": { "type": "string", "description": "PO name" }, "date": { "type": "string", "format": "date-time", "nullable": true, "description": "PO date (ISO 8601)" }, "date_due": { "type": "string", "format": "date-time", "nullable": true, "description": "Expected delivery date (ISO 8601)" }, "status": { "type": "string", "enum": [ "draft", "open", "fulfil", "void" ], "description": "PO status" }, "email": { "type": "string", "format": "email", "nullable": true, "description": "PO email address" }, "tax_method": { "type": "integer", "description": "Tax method (0=exclusive, 1=inclusive)" }, "tax_rate": { "type": "number", "format": "float", "description": "Tax rate percentage", "example": 15 }, "tax_disable": { "type": "integer", "description": "Tax disabled flag (0=enabled, 1=disabled)" }, "note_print": { "type": "string", "nullable": true, "description": "Notes displayed on the printed/PDF PO. Supports HTML." }, "note_internal": { "type": "string", "nullable": true, "description": "Internal notes visible only within the system. Supports HTML." }, "supplier_invoice_no": { "type": "string", "nullable": true, "description": "Supplier's invoice number once received", "example": "INV-EU-9001" }, "supplier_acceptance_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Date the supplier accepted the PO (ISO 8601)" }, "supplier_invoice_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Date of the supplier's invoice (ISO 8601)" }, "deliver_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Expected delivery date (ISO 8601)" }, "supplier": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PorderSupplier" } ], "description": "Supplier object or null" }, "lines": { "type": "array", "description": "Purchase order line items", "items": { "$ref": "#/components/schemas/PorderLine" } }, "totals": { "$ref": "#/components/schemas/PorderTotals" }, "currency_code": { "type": "string", "nullable": true, "description": "ISO 4217 currency code (only present on forex POs)", "example": "EUR" }, "fx_rate_to_local": { "type": "number", "format": "float", "nullable": true, "description": "FX rate from supplier currency to local currency (only present on forex POs)", "example": 1.85 }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Created timestamp (ISO 8601)" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Last updated timestamp (ISO 8601)" } } }, "PorderCreate": { "type": "object", "required": [ "supplier", "lines" ], "description": "Create a new purchase order. POs are created as draft by default. For forex POs, supply both `currency_code` and `fx_rate_to_local`, plus `price_forex` on each line.", "properties": { "supplier": { "type": "string", "format": "uuid", "description": "Supplier token (UUID)" }, "name": { "type": "string", "description": "PO name. Defaults to supplier name." }, "date": { "type": "string", "format": "date-time", "description": "PO date (ISO 8601). Defaults to today.", "example": "2026-05-11" }, "date_due": { "type": "string", "format": "date-time", "description": "Expected delivery date (ISO 8601)" }, "email": { "type": "string", "format": "email", "description": "PO email address. Defaults to supplier email." }, "tax_method": { "type": "integer", "description": "Tax method (0=exclusive, 1=inclusive). Defaults to account setting." }, "tax_rate": { "type": "number", "format": "float", "description": "Tax rate percentage. Defaults to account setting." }, "tax_disable": { "type": "integer", "description": "Disable tax (0=enabled, 1=disabled)" }, "custom_reference": { "type": "string", "description": "Custom reference / supplier reference number", "example": "API-TEST-FOREX-001" }, "client_reference": { "type": "string", "description": "Internal client reference field" }, "authorise": { "type": "boolean", "description": "Set to true to approve the PO immediately instead of saving as draft", "default": false }, "note_print": { "type": "string", "description": "Notes displayed on the printed/PDF PO. Supports HTML." }, "note_internal": { "type": "string", "description": "Internal notes. Supports HTML." }, "supplier_invoice_no": { "type": "string", "description": "Supplier's invoice number" }, "supplier_acceptance_date": { "type": "string", "format": "date-time", "description": "Date the supplier accepted the PO (ISO 8601)" }, "supplier_invoice_date": { "type": "string", "format": "date-time", "description": "Date of the supplier's invoice (ISO 8601)" }, "deliver_date": { "type": "string", "format": "date-time", "description": "Expected delivery date (ISO 8601)" }, "currency_code": { "type": "string", "description": "ISO 4217 currency code for forex POs. Omit (or set to local currency) for non-forex.", "example": "EUR" }, "fx_rate_to_local": { "type": "number", "format": "float", "description": "FX rate from supplier currency to local currency. Required when `currency_code` is foreign.", "example": 1.85 }, "lines": { "type": "array", "minItems": 1, "description": "Line items. At least one is required.", "items": { "$ref": "#/components/schemas/PorderLineCreate" } } } }, "PorderUpdate": { "type": "object", "description": "Update purchase order header fields. Only provided fields are updated. Cannot modify a PO that has receipts against it.", "properties": { "supplier": { "type": "string", "format": "uuid", "description": "Supplier token (UUID)" }, "name": { "type": "string", "description": "PO name" }, "date": { "type": "string", "format": "date-time", "description": "PO date (ISO 8601)" }, "date_due": { "type": "string", "format": "date-time", "description": "Expected delivery date (ISO 8601)" }, "email": { "type": "string", "format": "email", "description": "PO email address" }, "tax_method": { "type": "integer", "description": "Tax method (0=exclusive, 1=inclusive)" }, "tax_rate": { "type": "number", "format": "float", "description": "Tax rate percentage" }, "tax_disable": { "type": "integer", "description": "Disable tax (0=enabled, 1=disabled)" }, "custom_reference": { "type": "string", "description": "Custom reference / supplier reference number" }, "client_reference": { "type": "string", "description": "Internal client reference field" }, "authorise": { "type": "boolean", "description": "Set to true to approve, false to revert to draft" }, "note_print": { "type": "string", "description": "Notes displayed on the printed/PDF PO. Supports HTML." }, "note_internal": { "type": "string", "description": "Internal notes. Supports HTML." }, "supplier_invoice_no": { "type": "string", "description": "Supplier's invoice number" }, "supplier_acceptance_date": { "type": "string", "format": "date-time", "description": "Date the supplier accepted the PO (ISO 8601)" }, "supplier_invoice_date": { "type": "string", "format": "date-time", "description": "Date of the supplier's invoice (ISO 8601)" }, "deliver_date": { "type": "string", "format": "date-time", "description": "Expected delivery date (ISO 8601)" }, "currency_code": { "type": "string", "description": "ISO 4217 currency code. Set to local currency or empty to clear forex." }, "fx_rate_to_local": { "type": "number", "format": "float", "description": "FX rate from supplier currency to local currency. Required when `currency_code` is foreign." } } }, "PorderLineCreate": { "type": "object", "description": "Create a line item on a purchase order. Provide a product token or SKU to auto-fill price, description, SKU, and cost price from the product. For forex POs, supply `price_forex` (in supplier currency); the controller computes the local-currency `price` using the parent PO's `fx_rate_to_local`.", "properties": { "product": { "type": "string", "format": "uuid", "description": "Product token (UUID). Auto-fills price, description, SKU, and cost price." }, "sku": { "type": "string", "description": "Product SKU. Used to look up product if product token not provided.", "example": "103046" }, "description": { "type": "string", "description": "Line item description" }, "quantity": { "type": "number", "format": "float", "description": "Quantity", "default": 1, "example": 10 }, "price": { "type": "number", "format": "float", "description": "Unit price in local currency. Auto-filled from product purchase price if a product is provided. On forex POs, prefer `price_forex` instead." }, "price_forex": { "type": "number", "format": "float", "description": "Unit price in supplier currency (forex POs only). Local-currency `price` is computed from this and the parent PO's `fx_rate_to_local`.", "example": 42.5 }, "discount": { "type": "number", "format": "float", "description": "Flat discount amount", "default": 0 }, "extra": { "type": "number", "format": "float", "description": "Additional surcharge amount", "default": 0 }, "sort": { "type": "integer", "description": "Sort order position" }, "ex_price_base": { "type": "number", "format": "float", "description": "Cost base for the line. Auto-filled from product's average cost if a product is provided." } } }, "PorderLineUpdate": { "type": "object", "description": "Update a line item on a purchase order. Provide a product token or SKU to re-resolve and auto-fill fields.", "properties": { "product": { "type": "string", "format": "uuid", "description": "Product token (UUID)" }, "sku": { "type": "string", "description": "Product SKU" }, "description": { "type": "string", "description": "Line item description" }, "quantity": { "type": "number", "format": "float", "description": "Quantity" }, "price": { "type": "number", "format": "float", "description": "Unit price in local currency" }, "price_forex": { "type": "number", "format": "float", "description": "Unit price in supplier currency (forex POs only)" }, "discount": { "type": "number", "format": "float", "description": "Flat discount amount" }, "extra": { "type": "number", "format": "float", "description": "Additional surcharge amount" }, "sort": { "type": "integer", "description": "Sort order position" }, "ex_price_base": { "type": "number", "format": "float", "description": "Cost base for the line" } } }, "Supplier": { "type": "object", "description": "Full supplier object with addresses, contacts, and meta data", "properties": { "token": { "type": "string", "format": "uuid", "description": "Supplier token (UUID)", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "company": { "type": "string", "description": "Company name", "example": "Supplier Co" }, "name_first": { "type": "string", "description": "First name", "example": "John" }, "name_last": { "type": "string", "description": "Last name", "example": "Smith" }, "name": { "type": "string", "description": "Display name (company or full name)", "example": "Supplier Co" }, "name_full": { "type": "string", "description": "Full display name", "example": "Supplier Co - John Smith" }, "contact_name": { "type": "string", "description": "Contact person name", "example": "John Smith" }, "email": { "type": "string", "format": "email", "description": "Email address", "example": "john@supplier.com" }, "phone": { "type": "string", "description": "Phone number" }, "website": { "type": "string", "description": "Website URL" }, "reference": { "type": "string", "description": "Internal reference code" }, "notes": { "type": "string", "description": "Internal notes" }, "currency_code": { "type": "string", "description": "Supplier currency code (defaults to tenant currency if not set)", "example": "USD" }, "is_forex": { "type": "boolean", "description": "Whether this is a foreign currency supplier", "example": true }, "mail_stop": { "type": "boolean", "description": "Whether supplier has opted out of emails", "example": false }, "xero_id": { "type": "string", "description": "Xero integration ID" }, "created_at": { "type": "string", "format": "date-time", "description": "Created timestamp (ISO 8601)" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last updated timestamp (ISO 8601)" }, "meta": { "type": "object", "description": "Key-value meta data", "additionalProperties": { "type": "string" } }, "addresses": { "type": "array", "description": "Supplier addresses", "items": { "$ref": "#/components/schemas/ClientAddress" } }, "contacts": { "type": "array", "description": "Supplier contacts", "items": { "$ref": "#/components/schemas/ClientContact" } } } }, "JobCardSummary": { "type": "object", "description": "Job card summary for list views", "properties": { "token": { "type": "string", "description": "Job card token", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "reference": { "type": "string", "nullable": true, "description": "External reference", "example": "JC-001" }, "internal_reference": { "type": "string", "description": "System-generated internal reference", "example": "JOB-00042" }, "title": { "type": "string", "description": "Job card title", "example": "Kitchen renovation" }, "status": { "type": "string", "description": "Status label", "example": "In Progress" }, "status_code": { "type": "integer", "description": "Status code", "example": 1 }, "client_token": { "type": "string", "nullable": true, "description": "Associated client token" }, "start_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Start date (ISO 8601)" }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Created timestamp (ISO 8601)" } } }, "JobCardDetail": { "type": "object", "description": "Full job card detail including description, end date, total, and pipeline item", "properties": { "token": { "type": "string", "description": "Job card token" }, "reference": { "type": "string", "nullable": true, "description": "External reference" }, "internal_reference": { "type": "string", "description": "System-generated internal reference" }, "title": { "type": "string", "description": "Job card title" }, "status": { "type": "string", "description": "Status label" }, "status_code": { "type": "integer", "description": "Status code" }, "client_token": { "type": "string", "nullable": true, "description": "Associated client token" }, "start_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Start date (ISO 8601)" }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Created timestamp (ISO 8601)" }, "description": { "type": "string", "nullable": true, "description": "Job card description" }, "end_date": { "type": "string", "format": "date-time", "nullable": true, "description": "End date (ISO 8601)" }, "total": { "type": "number", "format": "float", "description": "Job card total value", "example": 1500 }, "pipeline_item_id": { "type": "integer", "nullable": true, "description": "Associated pipeline item ID" } } }, "JobCardCreateInput": { "type": "object", "description": "Input for creating a job card", "required": [ "title" ], "properties": { "title": { "type": "string", "description": "Job card title", "example": "Kitchen renovation" }, "reference": { "type": "string", "description": "External reference (must be unique)", "example": "JC-001" }, "description": { "type": "string", "description": "Job card description" }, "start_date": { "type": "string", "format": "date-time", "description": "Start date (ISO 8601)", "example": "2026-03-01T00:00:00Z" }, "end_date": { "type": "string", "format": "date-time", "description": "End date (ISO 8601)", "example": "2026-04-01T00:00:00Z" }, "status": { "type": "integer", "description": "Status code" }, "client": { "type": "string", "description": "Client token to associate" } } }, "JobCardUpdateInput": { "type": "object", "description": "Input for updating a job card. All fields are optional but at least one must be provided.", "properties": { "title": { "type": "string", "description": "Job card title" }, "description": { "type": "string", "description": "Job card description" }, "start_date": { "type": "string", "format": "date-time", "description": "Start date (ISO 8601)" }, "end_date": { "type": "string", "format": "date-time", "description": "End date (ISO 8601)" }, "status": { "type": "integer", "description": "Status code" }, "reference": { "type": "string", "description": "External reference (must be unique, empty string to clear)" }, "client": { "type": "string", "description": "Client token to associate" } } }, "FileUploadResponse": { "type": "object", "description": "File upload response with metadata", "properties": { "token": { "type": "string", "description": "File token" }, "name": { "type": "string", "description": "Display name", "example": "Project Plan" }, "filename": { "type": "string", "description": "Original filename", "example": "project-plan.pdf" }, "extension": { "type": "string", "description": "File extension", "example": "pdf" }, "size": { "type": "object", "description": "File size with human-readable unit", "properties": { "value": { "type": "number", "format": "float", "description": "Size value", "example": 2.4 }, "unit": { "type": "string", "description": "Size unit", "example": "MB" } } }, "object": { "type": "string", "nullable": true, "description": "Attached object type", "example": "jobcard" }, "object_id": { "type": "integer", "nullable": true, "description": "Attached object ID" } } } }, "responses": { "ValidationError": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "validation_failed" }, "message": { "type": "string", "example": "Required field is missing" } } } } } }, "UnauthorizedError": { "description": "Authentication failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "unauthorized" }, "message": { "type": "string", "example": "Invalid or missing authentication token" } } } } } }, "NotFoundError": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found" }, "message": { "type": "string", "example": "The requested resource does not exist" } } } } } }, "ConflictError": { "description": "Resource conflict (e.g. duplicate reference)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Conflict" }, "message": { "type": "string", "example": "A resource with this reference already exists" }, "data": { "type": "object", "properties": { "existing_token": { "type": "string", "description": "Token of the existing conflicting resource" } } } } } } } }, "InternalServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "internal_error" }, "message": { "type": "string", "example": "An unexpected error occurred" } } } } } } } } }