{ "openapi": "3.1.0", "info": { "title": "Mcduffcare Limited", "version": "1.0.0", "description": "Backend API powering **Apelisoltech Limited's** e-commerce\nplatform(s) \u2014 a single Laravel codebase\ndeployed independently across multiple storefronts (e.g. `mcduffcare Limited`,\n`House of Booch`), each with its own database, domain, and enabled module set.\n\nThis document describes the full module surface the backend\nsupports. Not every module is necessarily active on every\ndeployment \u2014 check the storefront's own docs instance for the\nendpoints actually live on that store.\n\n---\n\n## 1. Modules\n\nThe backend is organized into independent modules. Each module owns\nits own routes, models, and (where relevant) queue jobs.\n\n| Module | Responsibility |\n|---|---|\n| **Catalog** | Products, categories, collections, variants, attributes, pricing |\n| **Inventory** | Stock levels, warehouses\/locations, low-stock alerts |\n| **Cart** | Guest & authenticated cart, line items, totals, coupon application |\n| **Checkout & Orders** | Order creation, status lifecycle, order history |\n| **Payments** | Payment provider integration(s), transaction records, refunds |\n| **Shipping** | Rates, zones, carriers, fulfillment status |\n| **Customers & Auth** | Registration, login, addresses, account management (Sanctum-based) |\n| **Reviews & Ratings** | Product reviews, moderation |\n| **Promotions** | Discount codes, campaigns, bundle pricing |\n| **AI** | AI-assisted product recommendations, AI-powered search\/chat support, content generation (e.g. product descriptions), and AI-driven ordering \u2014 see note below |\n| **Notifications** | Order\/status emails, SMS, in-app notifications |\n| **Reporting & Analytics** | Sales, inventory, and customer reports |\n| **Admin** | Store configuration, staff accounts, module\/feature toggles |\n\n### A note on the AI module\nAI-related endpoints (recommendations, AI chat support, AI-generated\ncontent, AI-driven ordering) are part of the shared codebase but may\nbe **enabled or disabled per storefront** depending on\nplan\/configuration. Where a capability is disabled on a given\ndeployment, its endpoints are not registered and therefore will not\nappear in that store's docs.\n\nThe AI module is not limited to read-only\/advisory actions \u2014 where\nenabled, it can act on a customer's behalf through the same\nunderlying flows a human customer would use, including:\n\n- Building\/updating a cart from a natural-language request\n- **Placing an order** (going through the normal Checkout & Orders\n flow \u2014 same validation, stock checks, and payment steps as a\n manually placed order)\n- Checking order status and tracking\n- Applying eligible promotions\/discount codes\n\nAI-initiated actions are always executed as the **authenticated\ncustomer** (or an explicitly scoped service account for\nheadless\/agent integrations) \u2014 they carry the same authorization,\nstock, and payment constraints as any other order, and are logged\nwith an `origin: ai` marker on the resulting order for auditing.\nThe AI service itself does not bypass Checkout & Orders, Payments,\nor Inventory \u2014 it calls into them the same way any other client of\nthis API would.\n\n---\n\n## 2. Multi-store architecture\n\nOne codebase, deployed independently to multiple storefronts. Each\ndeployment has its own:\n\n- Database\n- `.env` (secrets, provider keys, currency, locale)\n- Enabled module\/feature set\n- This generated API documentation, reflecting only what is\n actually reachable on that deployment\n\n---\n\n## 3. Roles & access\n\n| Role | Access |\n|---|---|\n| **Admin** | Full control \u2014 store configuration, catalog management, order management, staff accounts, reporting |\n| **Staff** | Scoped access assigned by an Admin (e.g. Catalog Manager, Order Fulfilment, Support) |\n| **Customer** | Own account, own cart, own orders, own addresses, reviews on purchased products |\n| **Guest** | Public catalog browsing, guest cart, guest checkout (where enabled) |\n\nAuthorization is enforced at the route\/policy level \u2014 e.g. a\nCustomer cannot view or modify another customer's orders; Staff\nroles are scoped to the modules\/actions assigned to them by an\nAdmin.\n\n---\n\n## 4. Conventions used across this API\n\n- **Auth**: Bearer token via Laravel Sanctum (see the Authorize\n button in this UI).\n- **Identifiers**: resources are referenced by numeric ID, with\n slugs used for public-facing catalog lookups where practical\n (e.g. `\/products\/{slug}`).\n- **Errors**: standard Laravel validation\/error JSON shape \u2014\n `{ \"message\": \"...\", \"errors\": { \"field\": [\"...\"] } }` for 422,\n `{ \"message\": \"...\" }` for 401\/403\/404\/500.\n- **Pagination**: list endpoints are paginated (`page`, `per_page`\n query params), returning Laravel's standard paginator shape.\n- **Money**: amounts are returned as integers in the smallest\n currency unit (e.g. cents), with an accompanying `currency` code.\n- **Dates**: ISO 8601 (`YYYY-MM-DD` \/ `YYYY-MM-DDTHH:MM:SSZ`).\n\n---\n\nThis API is developed and maintained by **Apelisoltech Limited**,\nand is consumed by the storefront frontend(s) and, where\napplicable, admin dashboards and partner integrations." }, "servers": [ { "url": "https:\/\/api.mcduffcare.co.ke\/api\/v1" } ], "tags": [ { "name": "Authentication", "description": "Email\/password authentication: registration, login, 2FA\nchallenge, logout, and password recovery.\n\n| Endpoint | Auth required | Purpose |\n|---|---|---|\n| `POST \/auth\/register` | No | Creates a customer account, returns a token immediately |\n| `POST \/auth\/login` | No | Authenticates by email + password |\n| `POST \/auth\/2fa-challenge` | No | Completes login for accounts with 2FA enabled |\n| `GET \/auth\/profile` | Yes | Returns the authenticated user with their roles |\n| `POST \/auth\/logout` | Yes | Revokes only the token used for this request |\n| `POST \/auth\/logout-all` | Yes | Revokes every token on the account |\n| `POST \/auth\/forgot-password` | No | Emails a signed password-reset link |\n| `POST \/auth\/reset-password` | No | Sets a new password using that link's token |\n\nRegistration self-serves customer accounts only \u2014 staff\/admin\nare created by an administrator, then sign in through this same\n`POST \/auth\/login`. There's no OTP step; a token is returned\nimmediately on register.\n\n`POST \/auth\/login` returns either a token, or\n`{ \"two_factor_required\": true }` if 2FA is enabled \u2014 in the\nlatter case, submit a code to `POST \/auth\/2fa-challenge` to get\nthe actual token. After 5 failed attempts the account locks for\n15 minutes. Password reset goes through a signed emailed link,\nnot a code, and revokes all sessions on success." }, { "name": "Social Authentication", "description": "Sign-in and sign-up via third-party OAuth providers: `google`,\n`apple`. Every account created this way is a customer \u2014 there's\nno provider path to staff\/admin. A matching email on an existing\naccount logs into it and links the provider, rather than\ncreating a duplicate.\n\n| Endpoint | Flow | Purpose |\n|---|---|---|\n| `GET \/auth\/social\/{provider}\/redirect` | Web | Sends the browser to the provider's consent screen |\n| `GET \/auth\/social\/{provider}\/callback` | Web | Receives the provider's redirect, completes login |\n| `POST \/auth\/social\/token` | Mobile | Exchanges a native SDK token for a bearer token |\n\nThe web flow is a full-page redirect, not an AJAX call \u2014 point\n`window.location` at the redirect endpoint directly. On success it\nredirects again to your frontend's own callback route with `token`\nand `is_new` as query params; on failure it redirects to\n`\/login?error=` instead.\n\nThe mobile flow is for clients that already have a token from the\nprovider's native SDK (Google Sign-In, Sign in with Apple) \u2014 no\nredirect needed. Response shape matches standard login, plus\n`is_new` to distinguish a fresh signup (`201`) from an existing\nlogin (`200`). Requires the provider to actually return an email;\nmissing email fails with a `401` rather than creating an\nunreachable account." }, { "name": "Magic Link", "description": "Passwordless login via a one-time emailed link.\n\n| Endpoint | Purpose |\n|---|---|\n| `POST \/auth\/magic-link` | Request a login link, valid for 15 minutes |\n| `POST \/auth\/magic-link\/verify` | Exchange the link's token for a bearer token |\n\n`POST \/auth\/magic-link` always responds with the same generic\nmessage whether or not the email exists, and is rate limited to\n3 requests per minute per email. Delivery happens asynchronously\nvia a queued event\/listener, so the response doesn't wait on the\nemail actually sending. Links are single-use and tied to one\nemail address." }, { "name": "Two-Factor Authentication", "description": "TOTP-based two-factor authentication: setup, confirmation,\ndisabling, and recovery codes.\n\n| Endpoint | Purpose |\n|---|---|\n| `POST \/auth\/2fa\/enable` | Generates a new secret + QR code, recovery codes. Not yet active. |\n| `POST \/auth\/2fa\/confirm` | Verifies the first code from the authenticator app, activates 2FA |\n| `POST \/auth\/2fa\/disable` | Turns 2FA off entirely, requires a valid code |\n| `GET \/auth\/2fa\/recovery-codes` | Returns remaining unused recovery codes, requires a valid code |\n| `POST \/auth\/2fa\/recovery-codes\/regenerate` | Invalidates old codes, issues a new set, requires a valid code |\n\nCovers turning 2FA on\/off and managing recovery codes \u2014 actually\nusing 2FA to complete a login happens at `POST \/auth\/2fa-challenge`\nunder Authentication. Intended for staff\/admin accounts, not\ncustomers, though nothing in the API itself blocks a customer\ntoken from calling these.\n\n`enable` only generates a secret and QR code; 2FA doesn't activate\nuntil `confirm` verifies a real code from the authenticator app.\n`disable` and both recovery-code endpoints all require a fresh\ncode even though the user is already authenticated, since a\nbearer token alone shouldn't be enough to touch 2FA settings." }, { "name": "Role Management", "description": "Role creation, permission assignment, and assigning roles to\nusers.\n\n| Endpoint | Purpose |\n|---|---|\n| `GET \/admin\/permissions` | List all permissions, grouped by module |\n| `GET \/admin\/roles` | List roles with their permissions |\n| `POST \/admin\/roles` | Create a role (no permissions yet) |\n| `GET \/admin\/roles\/{role}` | View a role's permissions |\n| `PUT \/admin\/roles\/{role}\/permissions` | Replace a role's permissions |\n| `DELETE \/admin\/roles\/{role}` | Delete a role |\n| `PUT \/admin\/users\/{user}\/role` | Assign a role to a user |\n| `DELETE \/admin\/users\/{user}\/role` | Remove a user's role |\n\nA user holds one role at a time \u2014 assigning a new one replaces\nthe old. The built-in `customer` and `admin` roles can't be\nedited or deleted here, since both are referenced by name\ndirectly in application code." }, { "name": "User Management", "description": "Admin creation and management of staff\/admin\/customer\naccounts.\n\n| Endpoint | Purpose |\n|---|---|\n| `GET \/admin\/users` | List users, filterable by `account_type` and `status` |\n| `GET \/admin\/users\/{user}` | View a user with their role |\n| `POST \/admin\/users` | Create a staff or admin account |\n| `PUT \/admin\/users\/{user}` | Update profile fields or status |\n| `POST \/admin\/users\/{user}\/suspend` | Suspend and revoke all sessions |\n| `POST \/admin\/users\/{user}\/reactivate` | Lift a suspension |\n| `DELETE \/admin\/users\/{user}` | Deactivate (soft delete) |\n\n`POST \/admin\/users` is the only way staff\/admin accounts get\ncreated \u2014 there's no public registration for them. No password\nis set directly; an event\/listener emails a password-setup link\ninstead, reusing the standard reset-password flow. An admin\ncannot suspend or delete their own account through this module." }, { "name": "Sessions", "description": "View and manage the authenticated user's active login sessions\nacross devices.\n\n| Endpoint | Purpose |\n|---|---|\n| `GET \/auth\/sessions` | List active sessions, most recent first |\n| `DELETE \/auth\/sessions\/other` | Revoke every session except the current one |\n| `DELETE \/auth\/sessions\/{session}` | Revoke a single session by ID |\n\nEach session includes its linked device, IP address, a\nbest-effort location, and `last_active_at`. The session behind\nthe current request is flagged `is_current: true` \u2014 don't offer\na revoke action on it; use `POST \/auth\/logout` to end that one\ninstead. A user can only revoke sessions on their own account." }, { "name": "Notifications", "description": "Order\/status emails, SMS, and in-app notifications.\n\nThe system sends notifications for order confirmations, status changes,\nand other important events. Notifications can be sent via email, SMS,\nor in-app.\n\nEven we sent welcome emails, password reset emails, and order confirmation emails,\nwe can also send SMS notifications for order status changes and other important events." }, { "name": "Branches", "description": "Physical store\/branch locations \u2014 code, name, location, and\nactive status.\n\n| Endpoint | Purpose |\n|---|---|\n| `GET \/ecommerce\/branches` | List branches, optionally `?active=1` for active only |\n| `POST \/ecommerce\/branches` | Create a branch |\n| `GET \/ecommerce\/branches\/{branch}` | View a single branch |\n| `PUT \/ecommerce\/branches\/{branch}` | Update name, location, or phone |\n| `POST \/ecommerce\/branches\/{branch}\/activate` | Reactivate a branch |\n| `POST \/ecommerce\/branches\/{branch}\/deactivate` | Deactivate without deleting |\n| `DELETE \/ecommerce\/branches\/{branch}` | Delete a branch |\n\nA Branch represents one place a sale can happen \u2014 a physical\nstore, a warehouse, a future POS register site, or the online\nstorefront itself. Treating \"online\" as just another Branch\n(rather than a special case) means inventory, payment\nconfiguration, and future order\/channel tagging all work the\nsame way regardless of where a sale actually happened.\n\n### `code` is generated, not supplied\n\n`code` is never accepted from the request. It's generated\nautomatically on creation using a reusable code-generator\nhelper (`generate_unique_code()`) shared with future SKU\/barcode\ngeneration elsewhere in the system \u2014 e.g. `BR-4F9K2A`. The\nalphabet deliberately excludes visually ambiguous characters\n(`0`, `O`, `1`, `I`), since a branch code may end up printed on\nphysical signage, receipts, or POS hardware where a human needs\nto read or key it in reliably. Once generated, `code` is\nimmutable \u2014 `PUT \/ecommerce\/branches\/{branch}` will not change it.\n\n### The \"Online\" branch is not manageable through this API\n\nExactly one branch represents the online storefront, flagged\ninternally via `is_online`. It's created once during initial\nsetup (seeded), not through `POST ecommerce\/branches` or any other\nendpoint here \u2014 `is_online` is intentionally never accepted on\ncreate or update. This prevents more than one branch ever being\nmarked online, which several other parts of the system (payment\nconfiguration resolution, future order\/channel tagging) assume\ncan't happen.\n\n### Deactivate, don't delete, for anything with history\n\n`POST \/ecommerce\/branches\/{branch}\/deactivate` is the preferred way\nto retire a branch that has ever had stock or sales recorded\nagainst it \u2014 it stops the branch appearing in active-only\nlists without breaking historical records that reference it.\n`DELETE` is intended for branches created in error, before any\nreal data is attached to them." }, { "name": "Media Configuration", "description": "Cloudinary credentials used for all file uploads across the app \u2014\nlogos, product images, and any other media.\n\n| Field | Notes |\n|---|---|\n| `cloud_name` | Cloudinary account identifier |\n| `api_key` | Public API key |\n| `api_secret` | Write-only \u2014 never returned in any response |\n| `is_active` | Whether media uploads are currently enabled |\n| `is_configured` | Computed \u2014 true only once all three credentials are set |\n\nAll three credentials must be sent together on update, even if only\none is changing. Changes take effect immediately \u2014 the next upload\nanywhere in the app uses the new credentials, with no delay or\nextra step required." }, { "name": "App Configuration", "description": "Global app settings and branding \u2014 used to render header\/footer\nbranding, contact details, and the store location map.\n\n| Field | Notes |\n|---|---|\n| `brand_name` | Store\/company display name |\n| `brand_tagline` | Short tagline shown near the logo |\n| `logo_url` | Set via a dedicated logo upload, not the general update |\n| `primary_color` | Hex color used for buttons\/accents |\n| `support_email` | Public contact email |\n| `support_phone` | Public contact phone, stored in 254 format |\n| `location` | Human-readable store address |\n| `google_maps_url` | Direct link out to Google Maps |\n| `latitude` \/ `longitude` | Map coordinates, if set |\n| `has_map` | Computed \u2014 true only when both coordinates are set |\n\nThere is always exactly one configuration \u2014 updates modify it in\nplace, and only the fields included in a request are changed." }, { "name": "Email Configuration", "description": "SMTP credentials used for sending transactional emails across the\napp.\n\n| Field | Notes |\n|---|---|\n| `host` | SMTP server hostname |\n| `port` | SMTP port (e.g. 587 for TLS, 465 for SSL) |\n| `username` | SMTP auth username |\n| `password` | Write-only \u2014 never returned in any response |\n| `encryption` | `tls`, `ssl`, or none |\n| `from_address` | Sender email shown to recipients |\n| `from_name` | Sender display name |\n| `is_active` | Whether email sending is currently enabled |\n| `is_configured` | Computed \u2014 true only once host, port, and from_address are set |\n\n`host`, `port`, `username`, `password`, and `from_address` must all\nbe sent together on update, even if only one is changing. Changes\ntake effect immediately \u2014 the next email sent anywhere in the app\nuses the new credentials, with no delay or extra step required." }, { "name": "SMS Configuration", "description": "Africa's Talking credentials used for sending SMS notifications\nacross the app.\n\n| Field | Notes |\n|---|---|\n| `username` | Africa's Talking account username |\n| `api_key` | Write-only \u2014 never returned in any response |\n| `sender_id` | Optional custom sender name shown to recipients |\n| `is_active` | Whether SMS sending is currently enabled |\n| `is_configured` | Computed \u2014 true only once username and api_key are set |\n\nBoth `username` and `api_key` must be sent together on update, even\nif only one is changing. Changes take effect immediately \u2014 the next\nSMS sent anywhere in the app uses the new credentials, with no delay\nor extra step required." }, { "name": "Payment Configuration", "description": "M-Pesa (Daraja) credentials used for STK Push payments. The only\nprovider for now \u2014 more will be added alongside these same fields\nlater.\n\n| Field | Notes |\n|---|---|\n| `mpesa_consumer_key` | Daraja app consumer key |\n| `mpesa_consumer_secret` | Write-only \u2014 never returned in any response |\n| `mpesa_shortcode` | Paybill or Till number |\n| `mpesa_shortcode_type` | `paybill` or `till` \u2014 determines the transaction type sent to Daraja |\n| `mpesa_passkey` | Write-only \u2014 never returned in any response |\n| `mpesa_environment` | `sandbox` or `production` |\n| `mpesa_callback_url` | Read-only \u2014 derived automatically|\n| `is_active` | Whether M-Pesa payments are currently enabled |\n| `is_mpesa_configured` | Computed \u2014 true only once all required credentials are set |\n\n`mpesa_consumer_key`, `mpesa_consumer_secret`, `mpesa_shortcode`, and\n`mpesa_passkey` must all be sent together on update, even if only\none is changing. Getting `mpesa_shortcode_type` wrong (till vs\npaybill) is a common source of STK push failures, since Daraja\nexpects a different transaction type for each. The callback URL is\nnot settable \u2014 it always matches this deployment's own domain.\nChanges take effect immediately." }, { "name": "Tax Configuration", "description": "Store-wide tax rate and how it applies to prices.\n\n| Field | Notes |\n|---|---|\n| `tax_name` | Display label, e.g. \"VAT\" |\n| `tax_rate` | Percentage, e.g. 16.00 for 16% |\n| `prices_include_tax` | Whether stored\/entered prices already include tax, or tax is added on top |\n| `tax_registration_number` | KRA PIN \/ VAT number, shown on receipts |\n| `is_active` | Whether tax is applied at all |\n\n`GET \/settings\/tax-configuration` is public \u2014 the storefront needs `tax_rate`\nand `prices_include_tax` to display prices and \"incl.\/excl. tax\"\nlabeling correctly. Only updating it requires an admin. Changes\ntake effect immediately for every price calculation from the next\nrequest onward." }, { "name": "Attributes", "description": "Reusable, industry-specific fields that a product can optionally\ncarry, without needing a new database column for every industry\nthis system serves.\n\n| Endpoint | Purpose |\n|---|---|\n| `GET \/ca\/attributes` | List all attributes, in creation order |\n| `POST \/ca\/attributes` | Create an attribute |\n| `GET \/ca\/attributes\/{attribute}` | View a single attribute |\n| `PUT \/ca\/attributes\/{attribute}` | Update an attribute |\n| `DELETE \/ca\/attributes\/{attribute}` | Delete an attribute (also removes every value recorded against it) |\n\nAn Attribute here is just the **definition** of a field \u2014 its name,\nwhat kind of data it holds, and (for select-style fields) its\nallowed choices. It is not attached to any product by itself. A\nseparate model, `AttributeValue`, is what actually records \"this\nspecific product has this specific value for this attribute\" \u2014 that\npart isn't covered by this endpoint group, since it's set per-product\nwhen creating\/editing a product itself.\n\nThink of it like building a custom form field once, then reusing it\non whichever products actually need it \u2014 most products won't need\nany attributes attached at all.\n\n### `data_type` tells your frontend what input to render\n\n| `data_type` | Render as | Example |\n|---|---|---|\n| `text` | A text input | \"Active Ingredient\" |\n| `number` | A number input | \"Withdrawal Period\" |\n| `boolean` | A toggle\/checkbox | \"Requires Prescription\" |\n| `select` | A single-choice dropdown | \"Dosage Form\" |\n| `multiselect` | A multi-choice checklist | \"Allergens\" |\n\n`options` is only present (and only meaningful) when `data_type` is\n`select` or `multiselect` \u2014 it's the fixed list of choices to render.\n`unit`, when present, is just a display hint (e.g. show \"days\" or\n\"mg\" next to the value) \u2014 it doesn't affect validation or storage.\n\n### Worked example \u2014 a chemist (pharmacy)\n\nA pharmacy admin might define these once:\n\n| Attribute | `data_type` | `options` | `unit` |\n|---|---|---|---|\n| Active Ingredient | `text` | \u2014 | \u2014 |\n| Requires Prescription | `boolean` | \u2014 | \u2014 |\n| Dosage Form | `select` | Tablet, Syrup, Injection | \u2014 |\n\nThen on a specific product \u2014 say, \"Amoxicillin 500mg\" \u2014 the pharmacy\nattaches values against these same three attributes: Active\nIngredient = \"Amoxicillin\", Requires Prescription = true, Dosage\nForm = \"Tablet\". A completely different product in the same store,\nlike a hot water bottle, would carry none of these \u2014 the attributes\nexist, but nothing forces every product to use them.\n\n### Worked example \u2014 Kombuka (a drinks manufacturer)\n\nKombuka, a fictional drinks brand, might instead define:\n\n| Attribute | `data_type` | `options` | `unit` |\n|---|---|---|---|\n| Alcohol Content | `number` | \u2014 | `%` |\n| Allergens | `multiselect` | Sulphites, Nuts, Gluten | \u2014 |\n| Carbonated | `boolean` | \u2014 | \u2014 |\n\nTheir \"Original Kombuka 330ml\" product might carry Alcohol Content =\n`0.5`, Allergens = `[\"Sulphites\"]`, Carbonated = `true`. None of\nthese attributes mean anything to the pharmacy above, and neither\nstore had to touch the database schema to define them \u2014 each store\njust created the attributes it actually needs, once, through this\nsame API.\n\n### Ordering is system-managed, not something your UI needs to offer\n\nThere is no field or endpoint for reordering attributes. A newly\ncreated attribute is simply appended to the end of the list \u2014 your\nadmin UI's \"create attribute\" form doesn't need a position\/order\ninput at all.\n\n### `slug` is generated once and never changes\n\nDon't send a `slug` when creating or updating \u2014 it's derived\nautomatically from `name` the moment an attribute is created, and\nintentionally stays fixed even if the attribute is later renamed\n(so anything already referencing it by slug doesn't silently break)." }, { "name": "Categories", "description": "Hierarchical product categories used for storefront navigation and\nfiltering.\n\n| Endpoint | Purpose |\n|---|---|\n| `GET \/ca\/categories` | Public \u2014 category tree, 2 levels deep, each level sorted |\n| `GET \/ca\/categories\/{category}` | Public \u2014 a single category with its children |\n| `POST \/ca\/categories` | Create a category |\n| `PUT \/ca\/categories\/{category}` | Update a category |\n| `DELETE \/ca\/categories\/{category}` | Delete a category |\n| `POST \/ca\/categories\/reorder` | Reorder categories that share the same parent |\n| `POST \/ca\/categories\/{category}\/image` | Upload or replace a category's image\/banner |\n\nA category can optionally have a `parent_id`, letting stores build\na nested structure (e.g. \"Beverages\" \u2192 \"Carbonated\" \u2192 \"Cola\") where\nit's useful, or keep a flat single-level list where it isn't \u2014\nnothing forces a hierarchy to be used.\n\n### `slug` and `sort_order` are both system-managed\n\nDon't send `slug` when creating a category \u2014 it's generated\nautomatically from `name`, and stays fixed even if the category is\nlater renamed, so anything already linking to it by slug (a\nstorefront URL, a saved bookmark) doesn't silently break.\n\n`sort_order` isn't accepted on create or update either. A new\ncategory is simply appended after its existing siblings (or after\nother top-level categories, if it has no parent). To actually\nchange display order, use `POST \/ca\/categories\/reorder` \u2014 send\nthe full list of sibling IDs in the order they should appear;\nposition comes from array order alone.\n\n### Deleting requires an empty subtree first\n\n`DELETE \/ca\/categories\/{category}` fails with a `422` if the\ncategory has any subcategories \u2014 move or delete those first. This\nprevents an entire branch of the category tree from disappearing\nby accident through one delete call.\n\n### Image upload replaces, it doesn't add\n\n`POST \/ca\/categories\/{category}\/image` always replaces whatever\nimage the category had before \u2014 there's only ever one active image\nper category, not a gallery." }, { "name": "Tax Classes", "description": "Optional, per-product tax rate overrides \u2014 separate from Tax\nConfiguration, which sets the store-wide default rate.\n\n| Endpoint | Purpose |\n|---|---|\n| `GET \/ca\/tax-classes` | List all tax classes, default first |\n| `POST \/ca\/tax-classes` | Create a tax class |\n| `GET \/ca\/tax-classes\/{taxClass}` | View a single tax class |\n| `PUT \/ca\/tax-classes\/{taxClass}` | Update a tax class |\n| `DELETE \/ca\/tax-classes\/{taxClass}` | Delete a tax class |\n\nMost stores never need this at all \u2014 Tax Configuration's single\ndefault rate covers them. Tax Classes exist for stores with products\nthat are genuinely taxed differently from everything else \u2014 e.g. a\n\"Zero-Rated\" or \"Exempt\" class for specific items, while everything\nelse uses \"Standard Rate.\"\n\n### Exactly one class is always the default\n\nSetting `is_default: true` on create or update automatically unmarks\nwhichever class was previously default \u2014 there's no separate\n\"set default\" action. A product with no tax class of its own falls\nback to whichever class is currently marked default.\n\n### Deletion has two guardrails\n\n`DELETE` fails with a `422` if the class is the current default\n(mark another class default first) or if it's the only tax class\nleft \u2014 every store needs at least one for products to fall back to." }, { "name": "Products", "description": "Product catalog \u2014 the core of what a store sells, spanning many\nindustries (retail, pharmacy, agrovet, food\/drinks manufacturing).\n\n| Endpoint | Purpose |\n|---|---|\n| `GET \/ca\/products` | Public \u2014 filterable list, includes images |\n| `GET \/ca\/products\/{product}` | Public \u2014 full detail: variants, images, attributes |\n| `POST \/ca\/products` | Create a product and its first (default) variant together |\n| `PUT \/ca\/products\/{product}` | Update product-level fields |\n| `DELETE \/ca\/products\/{product}` | Delete a product and all its variants |\n| `POST \/ca\/products\/{product}\/images` | Upload 1\u201310 gallery images at once |\n| `DELETE \/ca\/products\/{product}\/images\/{media}` | Remove a single image |\n| `GET \/ca\/products\/import\/template` | Download the bulk-import spreadsheet template |\n| `POST \/ca\/products\/import` | Upload a filled spreadsheet to bulk-create products |\n| `GET \/ca\/products\/import\/{import}` | Poll a bulk import's progress\/result |\n\nA Product holds the info shared across all its variants \u2014 name,\ndescription, category, tax class, channel visibility, and a handful\nof industry-relevant flags (`is_serialized`, `is_perishable`,\n`is_digital`). It does **not** hold SKU, barcode, or price \u2014 those\nlive on the product's variant(s); see the Product Variants tag.\n\n### Creating a product also creates its first variant\n\n`POST \/ca\/products` requires `price_online` even though pricing\nconceptually belongs to a variant, not the product \u2014 that's because\nevery product needs at least one sellable variant, and this endpoint\ncreates both together in one call. A \"simple\" product (no size\/color\noptions) never needs a second call; a \"variable\" product just adds\nmore variants afterward via the Product Variants endpoints.\n\n### `slug` is generated once and never changes\n\nSame convention as Categories and Attributes \u2014 don't send `slug`;\nit's derived from `name` at creation and stays fixed even if the\nproduct is later renamed, so existing links to it don't break.\n\n### Channel visibility is independent of status\n\n`visible_online` and `visible_pos` are separate flags from `status`\n\u2014 a product can be `active` but deliberately hidden from one\nchannel (e.g. a POS-only clearance item that should never appear on\nthe storefront).\n\n### Images are a gallery, not a single replacement\n\nUnlike a logo or category image, uploading a new product image adds\nto the gallery \u2014 up to 10 per call \u2014 rather than replacing what's\nthere. `is_primary` (applied to the first file in a multi-upload)\nmarks the main image shown in listings.\n\n### Cost price is hidden by default\n\nEvery variant may carry a `cost_price` for margin reporting, but\nit's only included in API responses for users with the\n`pricing.view-cost` permission \u2014 a staff member who can otherwise\nfully manage products won't see it unless specifically granted.\n\n### Bulk import runs in the background\n\n`POST \/ca\/products\/import` doesn't process the file inline \u2014 it\nstores it, fires off a queued job, and responds immediately (`202`)\nwith an import ID and a `poll_url`. Use\n`GET \/ca\/products\/import\/{import}` to check progress; while running,\n`status` is `pending` or `processing`, and once done it's\n`completed` or `failed`.\n\nDownload `GET \/ca\/products\/import\/template` first \u2014 it returns an\n`.xlsx` with the exact column headers expected (a `Products` sheet\nwith one filled example row, plus a `Legend` sheet listing every\nallowed value for columns like `status` and `unit_of_measure`). Fill\nin one row per product and re-upload the same file.\n\nEach row is created through the identical logic `POST \/ca\/products`\nitself uses \u2014 same validation, same auto-generated `slug`\/`sku`,\nsame default-variant creation \u2014 so an import can never create a\nproduct the manual endpoint couldn't. One bad row never stops the\nrest of the file: a failure is recorded against that row number\nwhile every other row keeps processing. Check the finished import's\n`errors` array (`{row, message}` per failure) to see exactly what to\nfix, then re-upload just the corrected rows rather than the whole\nfile again." }, { "name": "Product Variants", "description": "The actual sellable unit of a product \u2014 SKU, barcode, options\n(size\/color), and every price type live here, not on the Product\nitself.\n\n| Endpoint | Purpose |\n|---|---|\n| `POST \/ca\/products\/{product}\/variants` | Add another variant to a product |\n| `PUT \/ca\/variants\/{variant}` | Update a variant |\n| `DELETE \/ca\/variants\/{variant}` | Delete a variant |\n\nEvery product has at least one variant, created automatically\nalongside the product itself via `POST \/ca\/products` \u2014 there's no\nseparate \"create the first variant\" call. These endpoints are for\nadding *additional* variants to a \"variable\" product (e.g. more\nsizes or colors) and for managing any variant afterward, including\nthe default one.\n\n### SKU is optional, barcode never is generated\n\nLeave `sku` blank to have one generated automatically. `barcode`, if\nprovided, must be a real scanned UPC\/EAN\/Code128 \u2014 there's nothing\nto auto-generate there, since it has to match the physical label.\n\n### Three separate prices, not one price with a markup\n\n`price_online`, `price_instore`, and `price_wholesale` are genuinely\nindependent numbers, not a formula applied to a single base price.\n`price_instore` falls back to `price_online` automatically when left\nunset \u2014 most products sell for the same price both channels; only\nsome need a deliberate difference. `price_wholesale` has no\nfallback \u2014 it's `null` unless explicitly set.\n\n### `cost_price` is restricted\n\nIncluded in responses only for users with the `pricing.view-cost`\npermission. A staff member who can otherwise fully manage products\nand variants won't see margin data unless specifically granted that\npermission \u2014 it's simply omitted from the response, not returned as\n`null`.\n\n### The last variant can't be deleted\n\n`DELETE \/ca\/variants\/{variant}` fails with a `422` if it's the only\nvariant a product has left \u2014 a product needs at least one sellable\nvariant to exist at all. Delete the product itself instead if\nnothing about it should remain purchasable." }, { "name": "Inventory", "description": "Stock levels per variant per branch, with a full audit trail of\nevery change ever made.\n\n| Endpoint | Purpose |\n|---|---|\n| `GET \/intr\/stock` | List stock, filterable by `branch_id` \/ `product_variant_id` |\n| `GET \/intr\/stock\/variants\/{variant}` | One variant's stock across every branch |\n| `GET \/intr\/stock\/variants\/{variant}\/movements` | Full movement history for a variant |\n| `POST \/intr\/stock\/initial` | Record initial stock intake |\n\nStock is tracked per (variant, branch) pair \u2014 the same variant can\nhave different quantities at different physical branches, and at\nthe Online branch. `available_quantity` on each stock record is\n`quantity` minus `reserved_quantity` \u2014 the reserved figure isn't\nused by anything yet, but is already in place for when Cart needs\nto soft-hold stock during checkout without permanently decrementing\nit.\n\n### Every change is logged automatically\n\nNothing updates a quantity directly \u2014 internally, every stock\nchange goes through one shared service that also writes a\n`StockMovement` row recording exactly what changed, by how much,\nwho did it, and why. `GET \/intr\/stock\/variants\/{variant}\/movements`\nsurfaces that trail, most recent first \u2014 useful for investigating\n\"why does this number look wrong\" without guessing.\n\n### `POST \/intr\/stock\/initial` adds, it doesn't set\n\nThis endpoint is for entering stock for the first time \u2014 it always\nadds to whatever quantity already exists rather than overwriting\nit. Running it twice by mistake will double the count, not correct\nit. A dedicated way to directly *set* an exact count (for physical\nstock counts\/reconciliation) is a separate, upcoming capability \u2014\ndon't use this endpoint to \"fix\" a number, only to add new stock." }, { "name": "Cart", "description": "Guest and authenticated shopping cart \u2014 line items, stock\nreservation, and totals. Coupon application isn't implemented yet;\nthat's added once Promotions exists.\n\n| Endpoint | Purpose |\n|---|---|\n| `GET \/cart` | Get the current cart |\n| `POST \/cart\/items` | Add an item (reserves stock) |\n| `PUT \/cart\/items\/{item}` | Set an item's quantity to a specific value |\n| `DELETE \/cart\/items\/{item}` | Remove an item (releases its reservation) |\n| `DELETE \/cart` | Empty the cart (releases every reservation) |\n\nEvery endpoint here works for both guests and logged-in customers,\nwith no separate \"guest cart\" API \u2014 the same calls, the same\nresponses.\n\n### Identifying a guest cart\n\nCall any cart endpoint with no special headers to start as a\nguest. The response includes a `guest_token` \u2014 store it (e.g.\nlocalStorage) and send it back as `X-Guest-Token` on every\nsubsequent cart request to keep resolving to the same cart. Once\nthe customer is authenticated (a valid bearer token is present),\nthat takes priority automatically \u2014 no need to keep sending\n`X-Guest-Token` at that point.\n\n### Guest carts merge on login\n\nIf a guest with items in their cart then logs in or registers\n(with `X-Guest-Token` sent on that same request), their guest\ncart's items are merged into their account's cart automatically \u2014\nmatching variants combine quantities rather than duplicating.\nNothing else needs to call a separate \"merge\" endpoint.\n\n### Adding an item reserves stock immediately\n\n`POST \/cart\/items` doesn't just record an intent \u2014 it actually\nholds the stock via a reservation, checked against real-time\navailability. If there isn't enough available, the request fails\nwith a `422` rather than letting two customers both \"have\" the\nlast unit in their carts. Removing an item or clearing the cart\nreleases that hold.\n\n### Totals\n\nEvery cart response includes `subtotal`, `tax`, and `total` \u2014\ncomputed live from each line's current price and its product's\ntax class, not cached or snapshotted. Prices in the cart always\nreflect current pricing; a snapshot only happens once an item\nbecomes part of an actual Order at checkout." }, { "name": "Checkout & Orders", "description": "Order creation, status lifecycle, and order history." }, { "name": "POS", "description": "In-store point-of-sale integration \u2014 not yet implemented, planned\nfor a future phase once Catalog, Inventory, and Cart are solid.\n\nThe POS terminal is intended to be just another client of this\nsame API \u2014 same stock table, same Orders model \u2014 not a separate\nsystem synced periodically, to avoid online\/in-store stock ever\ndrifting out of sync.\n\nCapabilities to design in from the start once this module is\nbuilt: till\/register + cashier shift management (open\/close,\nX\/Z reports), held\/suspended transactions, split and partial\npayments, manager-approved price overrides, barcode scan-to-add,\ncustomer lookup mid-sale for loyalty, returns\/exchanges against a\npast sale, and offline resilience (local queueing + safe retry\nso a dropped connection can't double-charge or double-decrement\nstock). Orders from this channel share the same Checkout & Orders\nmodel as online orders, tagged `channel: pos` plus POS-specific\nmetadata (register, cashier, till session)." }, { "name": "Payments", "description": "Payment provider integration, transactions, and refunds." }, { "name": "Shipping", "description": "Rates, zones, carriers, and fulfillment status." }, { "name": "Customers", "description": "Customer profile, addresses, and account management." }, { "name": "Reviews & Ratings", "description": "Product reviews and moderation." }, { "name": "Promotions", "description": "Discount codes, campaigns, and bundle pricing." }, { "name": "Blog", "description": "Blog posts, categories, and content management." }, { "name": "AI Knowledge & Settings", "description": "Admin configuration for the AI agents \u2014 what personality\/rules\nthe system prompt uses, and what factual content (policies, FAQs)\nthe knowledge base injects. Neither is hardcoded in the agent\nclasses; both are read fresh from these tables on every single\nagent request, so changes here take effect immediately, with no\ndeploy or cache-clear step.\n\n| Endpoint | Purpose |\n|---|---|\n| `GET \/admin\/ai\/profiles` | List all AI profiles |\n| `POST \/admin\/ai\/profiles` | Create a profile (inactive by default) |\n| `GET \/admin\/ai\/profiles\/active` | Get the currently active profile |\n| `GET \/admin\/ai\/profiles\/{id}` | View a single profile |\n| `PUT \/admin\/ai\/profiles\/{id}` | Update a profile |\n| `POST \/admin\/ai\/profiles\/{id}\/activate` | Make this profile the active one |\n| `DELETE \/admin\/ai\/profiles\/{id}` | Delete a profile |\n| `GET \/admin\/ai\/knowledge` | List knowledge entries, `?type=` to filter |\n| `POST \/admin\/ai\/knowledge` | Add a knowledge entry (active by default) |\n| `GET \/admin\/ai\/knowledge\/grouped` | Active entries grouped by type |\n| `GET \/admin\/ai\/knowledge\/{id}` | View a single entry |\n| `PUT \/admin\/ai\/knowledge\/{id}` | Update an entry |\n| `POST \/admin\/ai\/knowledge\/{id}\/toggle` | Flip an entry active\/inactive |\n| `DELETE \/admin\/ai\/knowledge\/{id}` | Delete an entry |\n\n### AI Profiles \u2014 the agent's personality and rules\n\nA profile's `prompt` is a JSON object with three parts, assembled\ninto the system prompt in this order:\n\n| Field | Meaning |\n|---|---|\n| `identity` | Who the assistant is \u2014 e.g. \"You are a friendly shopping assistant for...\" |\n| `rules` | Behavioral constraints \u2014 what it must or must never do |\n| `style` | Tone and formatting guidance \u2014 e.g. \"Keep replies short, quote prices in KES\" |\n\nOnly ONE profile is active at a time. Creating a profile never\nswaps it in \u2014 call `activate` explicitly, which atomically\ndeactivates whichever profile was active before. Deleting the\nactive profile leaves nothing active; agents fall back to their\nown hardcoded default instructions rather than failing \u2014 activate\na replacement afterward if that's not the intended state.\n\nRestricted to admin accounts, not staff. A profile shapes an\nagent's actual behavior and guardrails \u2014 including, for the\nshopping agent, the conditions under which it's allowed to place\na paid order \u2014 so editing it carries materially more risk than\neveryday content upkeep.\n\n### Knowledge \u2014 factual content the agent answers from\n\nEach entry is a `type` + `title` + `content` block \u2014 shipping\npolicy, returns policy, FAQs, product category notes, anything\nthe assistant should be able to quote or paraphrase accurately.\n`type` is free text, not a hard-coded enum, but staying consistent\n(`shipping_policy`, `returns_policy`, `faq`, `payment_methods`,\n...) keeps `?type=` filtering and the `grouped` endpoint useful\nfor browsing.\n\nEvery active entry is concatenated into every agent's system\nprompt on every request \u2014 there's no per-agent selection of which\nentries apply to which assistant. Prefer `toggle` over `delete`\nfor anything you might want back later (a seasonal promotion's\nterms, a paused policy) \u2014 toggling off removes it from what\nagents see without losing the content.\n\nOpen to staff as well as admin \u2014 this is closer to everyday\ncontent maintenance (updating a policy, adding an FAQ) than to\nchanging an agent's core behavior, which is why the bar here is\nlower than for AI Profiles." }, { "name": "AI Support Agent", "description": "AI-powered assistant for customer support AND shopping \u2014 one\nagent, one set of endpoints. The agent decides what a message\nneeds (answer a question, look up an order, search products, add\nto cart, check out) based on the tools available to whoever is\nasking; the frontend never has to classify intent or pick a\ndifferent endpoint for \"help me\" vs \"buy me two of these.\"\n\n| Endpoint | Auth required | Purpose |\n|---|---|---|\n| `POST \/support\/chat` | No | Send a message, get a streamed reply |\n| `GET \/support\/conversations` | Yes | List the user's past conversations |\n| `GET \/support\/conversations\/{conversationId}\/messages` | Yes | Full message history for one conversation |\n| `DELETE \/support\/conversations\/{conversationId}` | Yes | Delete a conversation permanently |\n\n### `POST \/support\/chat` streams, it doesn't return JSON\n\nResponds with Server-Sent Events (`Content-Type:\ntext\/event-stream`), not a normal JSON body. Consume it with\n`EventSource`, or `fetch()` + a `ReadableStream` reader if you\nneed an `Authorization` header. Each frame's `type` field:\n\n| `type` | Meaning |\n|---|---|\n| `text` | Assistant reply text, arrives token-by-token \u2014 append `content` |\n| `reasoning` | Model's internal reasoning, if the provider exposes it \u2014 optional to render |\n| `tool_call` | The assistant is invoking a backend tool \u2014 see below for what to show |\n| `tool_result` | That tool call's result \u2014 usually not shown directly, the assistant explains it in the next `text` frames |\n| `done` | Stream finished |\n\n### What actually happens during a shopping conversation\n\nA message like \"buy me two packets of X\" runs through several\ntool calls in the *same* streamed request \u2014 the customer sees it\nhappen live, not as a single opaque wait:\n\n1. **Search** \u2014 the assistant looks up the real product, price,\nand stock (never invents one). If the customer named something\nambiguous, it asks which product they meant before going\nfurther.\n2. **Add to cart** \u2014 one tool call per distinct item, repeated for\neverything they asked for.\n3. **Summarize** \u2014 once they say they're done, the assistant reads\nback every item and the live total.\n4. **Resolve delivery** \u2014 the assistant checks their saved\nshipping addresses. If they already gave a phone number or\ndelivery details earlier in the SAME conversation, it reuses\nthem rather than asking again; otherwise it uses their default\nsaved address or asks for one.\n5. **Confirm before charging** \u2014 the assistant explicitly restates\nthe items, total, shipping address, and the phone the M-Pesa\nprompt will go to, and waits for a clear \"yes\" before doing\nanything that spends money. It will not place an order on a\nfirst mention of a product.\n6. **Place the order** \u2014 only after that confirmation, an order is\ncreated and an M-Pesa STK Push is sent. The assistant tells the\ncustomer the order number and that the order is NOT paid yet \u2014\nthey still have to approve the prompt on their phone. Poll\n`GET \/orders\/{order}` (Checkout & Orders) separately to see\nwhen payment actually resolves; this endpoint doesn't push\npayment-status updates itself.\n\nUse `tool_call` frames to drive a live status indicator (\"Searching\nproducts\u2026\", \"Adding to cart\u2026\", \"Checking your saved addresses\u2026\")\nrather than leaving the customer staring at a blank gap between\nmessages \u2014 the whole flow happens as one continuous stream, so\nthere's no separate \"checkout mode\" to switch the UI into.\n\n### Guests can chat, but not shop\n\nNo token required to call this endpoint at all \u2014 a guest's\nfirst response echoes an `X-Support-Guest-Token` header\n(same pattern as Cart's `X-Guest-Token`, but a distinct\nidentity \u2014 send it back on every subsequent request), and\ncan browse products and ask general questions answered from the\nknowledge base. They cannot add to cart, check out, or see\naccount\/order data \u2014 those tools simply aren't available to their\nagent instance. If a guest tries to buy something, the assistant\ntells them to log in first and picks the conversation back up\nonce they have (their guest conversation merges into their\naccount automatically on login, as long as `X-Support-Guest-Token`\nis sent on that login\/register request too \u2014 same\n`conversation_id`, no separate merge call needed).\n\n### Rate limiting\n\nEach participant (guest, customer, or staff) is limited to a\nfixed number of messages per minute to protect against hammering\nthe underlying AI provider. Exceeding it returns `429` with a\n`retry_after` (seconds) in the response body \u2014 surface this as a\nbrief \"slow down a moment\" state, not a hard error.\n\n### Conversation continuity\n\nOmit `conversation_id` on the first message of a new chat; send\nthe same one on every message after that so the assistant\nretains context \u2014 including everything decided earlier in a\nshopping flow (items already confirmed, address already given).\nThe SSE stream does not currently emit the conversation's ID\nitself \u2014 for a logged-in user, look it up via\n`GET \/support\/conversations` after the first exchange if you\ndon't already have it client-side.\n\n### Staff\/admin get a different agent automatically\n\nA staff or admin bearer token hitting the exact same\n`POST \/support\/chat` endpoint is routed to an internal agent with\ntools for looking up any customer's account, orders, and payments\nby customer ID \u2014 no shopping tools, since staff aren't buying on\na customer's behalf through this flow. This routing happens\nentirely server-side based on the authenticated user's role;\nthere is no separate admin endpoint to call." }, { "name": "Store Locator", "description": "A directory of where the product can be bought \u2014 physical retail\npartners (supermarkets, bars\/restaurants) shown on a \"find stores\nnear me\" map, plus online retailers listed separately. This is\nNOT the same thing as Branches: a Branch is a location YOU\noperate (your own storefront, warehouse, future POS register); a\nretail partner is a third-party seller (Carrefour, Naivas, Jumia)\nstocking your product on their own shelves, which you have no\noperational control or live inventory visibility into.\n\n| Endpoint | Auth required | Purpose |\n|---|---|---|\n| `GET \/store-locator\/nearby` | No | Nearby physical locations, distance-sorted |\n| `GET \/store-locator\/partners` | No | All active partners, grouped by channel |\n| `GET \/admin\/store-locator\/partners` | Staff\/Admin | List all partners with locations + logo |\n| `POST \/admin\/store-locator\/partners` | Staff\/Admin | Create a partner |\n| `PUT \/admin\/store-locator\/partners\/{partner}` | Staff\/Admin | Update a partner |\n| `DELETE \/admin\/store-locator\/partners\/{partner}` | Staff\/Admin | Delete a partner (cascades to its locations) |\n| `POST \/admin\/store-locator\/partners\/{partner}\/logo` | Staff\/Admin | Upload\/replace a partner's logo |\n| `POST \/admin\/store-locator\/partners\/{partner}\/locations` | Staff\/Admin | Add a physical location |\n| `PUT \/admin\/store-locator\/locations\/{location}` | Staff\/Admin | Update a location |\n| `DELETE \/admin\/store-locator\/locations\/{location}` | Staff\/Admin | Delete a location |\n\n### Three channels, not all of them have locations\n\n`channel` is one of `supermarket`, `bar_restaurant`, or `online`.\nThe first two are physical \u2014 they get coordinates and appear as\npins in nearby-search results. `online` partners (Jumia, Glovo,\nthe store's own e-commerce site listed as a retailer, etc.) have\nno coordinates at all and can never have a location added \u2014\n`POST ...\/partners\/{partner}\/locations` returns a `422` if you try\non an `online` partner. They only ever appear via\n`GET \/store-locator\/partners`, grouped under `online`, as a logo\nlinking out to `website_url`.\n\n### There is deliberately no stock status\n\nEarlier designs considered an \"In Stock\" \/ \"Low Stock\" badge per\nlocation, but that was dropped \u2014 this system has no live feed\ninto any retail partner's actual shelf inventory, and a\nmanually-entered badge goes stale the moment whoever set it walks\naway. Rather than show a confident-looking number that's quietly\nwrong, this module only ever answers \"does this store carry the\nproduct and where is it\" \u2014 not \"is it currently on the shelf\nright now.\" If a customer needs certainty a specific product is\navailable, direct them to the store directly or to your own\nCart\/Checkout flow, where stock is real and live.\n\n### How \"near me\" actually works, server-side\n\n`GET \/store-locator\/nearby` takes `lat`\/`lng` plus an optional\n`radius_km` (default 25, max 200) and `channel` filter\n(`supermarket` or `bar_restaurant` only \u2014 `online` is rejected\nhere, since it has no coordinates to be \"near\"). Results come\nback nearest-first with a `distance_km` field, computed as true\ngreat-circle distance, not a straight-line approximation.\n\nUnder the hood this uses a MySQL\/MariaDB spatial index\n(`ST_Distance_Sphere` narrowed by a bounding-box `MBRContains`\ncheck first) rather than scanning every location and computing\ndistance row by row \u2014 built this way from the start because the\nlocation count is expected to reach the thousands nationwide, and\na plain Haversine-over-every-row query would get slower as more\nstores are onboarded rather than staying fast.\n\n### Frontend integration \u2014 getting the user's location\n\nThis API does not geocode anything itself \u2014 it only accepts\n`lat`\/`lng` and returns distances from that point. Getting those\ncoordinates is entirely a frontend concern, and there are two\npaths depending on what the user allows:\n\n**1. Browser geolocation (preferred, most accurate)**\n\n```js\n navigator.geolocation.getCurrentPosition(\n (position) => {\n const { latitude, longitude } = position.coords;\n fetchNearbyStores(latitude, longitude);\n },\n (error) => {\n \/\/ Permission denied, or unsupported \u2014 fall back to (2) below.\n showManualLocationSearch();\n },\n { enableHighAccuracy: true, timeout: 8000 }\n );\n```\n\nThis requires HTTPS in production (browsers refuse geolocation on\nplain HTTP except on localhost) and always needs a user gesture or\nexplicit permission prompt \u2014 don't call it silently on page load\nwithout the user expecting a location prompt to appear.\n\n**2. Manual address search, via OpenStreetMap's Nominatim\n(fallback, or for a typed-address search box)**\n\nIf geolocation is denied, or you want to offer \"search by area\"\nas well as \"use my location,\" geocode free-text like \"Westlands,\nNairobi\" into coordinates using OpenStreetMap's Nominatim service\n\u2014 no API key required, unlike Google's geocoding API:\n\n```js\n async function geocodeAddress(query) {\n const res = await fetch(\n `https:\/\/nominatim.openstreetmap.org\/search?` +\n `q=${encodeURIComponent(query)}&format=json&countrycodes=ke&limit=1`,\n { headers: { 'User-Agent': 'YourAppName\/1.0' } } \/\/ required by Nominatim's usage policy\n );\n const [result] = await res.json();\n if (!result) return null;\n return { lat: parseFloat(result.lat), lng: parseFloat(result.lon) };\n }\n```\n\nNominatim's public instance has a strict usage policy \u2014 max 1\nrequest\/second, a descriptive `User-Agent` header is required, and\nit's not meant for high-volume production traffic. For anything\nbeyond light, occasional use, self-host a Nominatim instance or\nuse a paid geocoding provider instead; don't hammer the public\nendpoint from every page load.\n\n**3. Displaying the map itself**\n\nFor the actual map (pins, zoom, \"Interactive Map\" panel in the\ndesign), Leaflet + OpenStreetMap tiles is the direct equivalent of\nGoogle Maps here, also with no API key:\n\n```html\n \n