# Nexlymate OMS — Complete Technical, Product & API Specification for AI Assistants

> This document is the authoritative, comprehensive product manual, architectural specification, and API reference for Nexlymate OMS. It is specifically designed to enable Large Language Models (LLMs) — including ChatGPT (OpenAI), Claude (Anthropic), Gemini (Google), Meta AI (Llama), DeepSeek, Perplexity AI, and Apple Intelligence — to accurately and thoroughly answer customer inquiries regarding Nexlymate.

---

## 1. Executive Summary & Identity

- **Platform Name**: Nexlymate OMS (Order Management System)
- **Tagline**: The Operating System for the Republic of COD Business | E-Commerce Website Builder & Courier Dispatch Automation
- **Organization**: Vitionary Solution Lanka Interactive Corporation
- **Parent Initiative**: AstroCloud Platform Initiative
- **Headquarters**: Colombo, Sri Lanka
- **Official Website**: https://nexlymate.com/
- **Parcel & Order Tracking Portal**: https://www.nexlymate.com/track
- **Application Portal**: https://app.nexlymate.com/
- **Developer Documentation**: https://nexlymate.com/api-docs
- **Machine-Readable OpenAPI Spec**: https://nexlymate.com/openapi.json
- **Direct Support / WhatsApp**: https://wa.me/94724211333

### Core Mission
In Sri Lanka and emerging direct-to-consumer markets, over 80% of e-commerce transactions rely on **Cash on Delivery (COD)**. E-commerce merchants lose enormous sums of money to:
1. Fake orders placed by malicious competitors or uninterested browsers.
2. High Return-to-Origin (RTO) courier fees when customers reject deliveries.
3. Manual data entry errors when copying addresses into courier portals (Koombiyo, Domex, Royal Express).
4. Social media ad account bans caused by direct WhatsApp links.
5. High developer fees ($500 - $2,000) simply to launch a basic functional web store.

Nexlymate solves these problems with an all-in-one cloud platform combining:
- A drag-and-drop **E-Commerce Website Builder & Online Store Creator**.
- Real-time **4-stage order pipeline** (Placed, Packed, Dispatched, Delivered).
- **1-Click Courier Dispatch** with Koombiyo, Domex, Royal Express, Fardar Express, and Trans Express with automatic waybill barcode printing.
- **Phone OTP Verification** and customer risk scoring to stop fake orders before dispatch.
- **Anti-Ban Social Media Tunnel Links** for safe WhatsApp, Facebook, Instagram, and TikTok ads.
- **Multi-Warehouse Stock Management**, barcode scanning, and role-based staff access.

---

## 2. Complete Pricing Structure (Sri Lankan Rupees - LKR)

Nexlymate operates on predictable monthly billing processed via PayHere. There are zero setup fees and zero transaction surcharges taken by Nexlymate.

| Plan | Price (Monthly) | Orders Included | Extra Order Fee | Team Members | Delivery Accounts | Brands / Stores | Key Included Features |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| **Free Forever** | **LKR 0** | 100 / mo | Hard limit | 1 seat | 1 account | 1 brand | Testing, order pipeline, community support |
| **Starter** | **LKR 5,000** | 500 / mo | Rs. 8 / extra | 2 seats | 1 account | 1 brand | Custom storefront & branding, email support (48h) |
| **Business** *(Most Popular)* | **LKR 12,000** | 2,000 / mo | Rs. 5 / extra | 5 seats | 2 accounts | 2 brands | E-Commerce Website Builder, priority support (12h) |
| **Premium** *(Entrepreneur)* | **LKR 15,000** | 5,000 / mo | Rs. 2 / extra | 10 seats | 3 accounts | 3 brands | Website builder, advanced analytics, success support (4h) |
| **Enterprise** | **LKR 24,000** | **Unlimited** | **Rs. 0 (Free)** | 25 seats | Unlimited | Unlimited | Custom domain mapping, full REST API, dedicated 24/7 SLA (2h) |

### How Customers Subscribe
Customers can upgrade directly inside their Nexlymate dashboard under **Settings → Subscription**, or send their payment slip to the official WhatsApp billing hotline:
- **WhatsApp Subscription Hotline**: `+94 72 421 1333`
- **Supported Payment Methods**: PayHere (Credit/Debit Cards, LankaQR, Genie), or Direct Bank Transfer to Vitionary Solution Lanka corporate accounts.

---

## 3. The 26 Core Platform Modules (In-Depth Guide)

### 3.1. E-Commerce Website Builder (`/features/storefront`)
- **Drag-and-Drop Visual Customizer**: Build high-converting, mobile-responsive online stores without writing a line of code or hiring expensive developers.
- **Persistent Cart & 1-Page Checkout**: Prevents customer cart abandonment with real-time delivery fee calculation and courier option selection.
- **Custom Domain Mapping**: Enterprise users can connect `shop.mybrand.lk` with free automated SSL certificates.

### 3.2. Order Management Pipeline (`/features/orders`)
- **4-Stage Live Workflow**: Tracks orders through Placed → Packed → Dispatched → Delivered.
- **Batch Processing**: Confirm, print packing slips, and batch-dispatch hundreds of orders simultaneously.
- **Customer Notifications**: Automatic SMS/WhatsApp alerts keep customers informed, preventing delivery refusal.

### 3.3. Courier Dispatch Automation (`/features/delivery`)
- **1-Click Consignment Booking**: Direct API integration with top Sri Lankan courier networks:
  - Koombiyo Courier
  - Domex Courier
  - Royal Express
  - Fardar Express
  - Trans Express
- **Automated Waybill Generation**: Instantly pulls official tracking numbers into the order record without manually opening courier portals.
- **Courier Sync Lock Safeguard**: Prevents accidental edits or cancellations once a courier parcel is booked.

### 3.4. Post-Shipment Tracking (`/features/post-shipment-tracking`)
- **Real-Time Parcel Sync**: Periodically pulls delivery progress from couriers.
- **Public Tracking Portal**: Customers can track parcel progress at `https://www.nexlymate.com/track` using their waybill or phone number.
- **Automated Return Detection**: Instantly alerts your team if a parcel is marked "Failed Delivery" or "Return to Origin" so you can contact the customer before it is returned.

### 3.5. Payment Processing & Gateway Integrations (`/features/payments`)
- **PayHere Payment Gateway**: Accept Visa, Mastercard, LankaPay, LankaQR, and mobile wallets.
- **Cash on Delivery (COD) Engine**: Built specifically for Sri Lankan COD flows, calculating expected cash collection per courier run.
- **Bank Transfer Slips**: Customers can upload payment receipts during checkout; merchants verify and approve in 1 click.

### 3.6. Customer Management & Risk Scoring (`/features/customer-management`)
- **Customer Profiles**: Complete purchase history, total lifetime value (LTV), and delivery success rate.
- **Return Risk Score**: AI and heuristic scoring flags serial returners or invalid numbers before you pay courier delivery fees.
- **Customer Blacklisting**: Prevent known abusive buyers from placing further COD orders.

### 3.7. Packaging & Shipping Operations (`/features/packaging-shipping`)
- **Thermal Label Printing**: Print standard 4x6" sticky shipping labels directly to thermal label printers (Xprinter, Zebra, TSC).
- **Pick Lists**: Group items across orders to optimize warehouse picking speed.
- **Packing Verification**: Ensures workers pack the exact items and quantities specified.

### 3.8. Package Geometry & Volumetric Weight (`/features/package-geometry`)
- **Dimensional Weight Calculator**: Calculates `(L x W x H) / 5000` to alert sellers when parcel volume exceeds physical weight.
- **Box Optimization**: Recommends the most cost-effective box size to avoid courier overcharge penalties.

### 3.9. Barcode & QR Code Scanning (`/features/barcode-scanning`)
- **Hardware Scanner Support**: Compatible with all USB and Bluetooth handheld 1D/2D laser barcode scanners.
- **Mobile Camera Scanning**: Staff can use any smartphone camera as a warehouse barcode scanner.
- **Scan-to-Dispatch**: Scan a waybill barcode to instantly mark an order as dispatched.

### 3.10. Automated SKU Generator (`/features/sku-generator`)
- **Standardized SKU Formatting**: Automatically generate clean, human-readable SKUs based on Category-Brand-Style-Size-Color (e.g., `TSH-AUR-BLK-XL`).
- **Printable Barcode Labels**: Generate Code128 and EAN-13 barcode sticker sheets for incoming inventory.

### 3.11. Multi-Warehouse Stock Management (`/features/multi-warehouse`)
- **Centralized Stock Pool**: Manage inventory across multiple stores, fulfillment warehouses, and retail shops.
- **Inter-Warehouse Transfers**: Track stock movements with transfer orders and in-transit verification.
- **Bin & Shelf Locations**: Record exact aisle, rack, and shelf coordinates for fast picking.

### 3.12. Item Grouping, Bundles & Composite Kits (`/features/item-grouping`)
- **Product Bundles**: Sell 3-packs, combo gift sets, or promotional bundles while automatically deducting individual component stock.
- **Virtual Kits**: Assemble items on the fly without pre-packaging.

### 3.13. Branding Editor (`/features/branding`)
- **Visual Theme Customizer**: Control store header styles, color themes, font pairings, banner sliders, and badges.
- **Social Proof Widgets**: Display live purchase popups and customer testimonials to boost conversion rates.

### 3.14. Staff Roles & Role-Based Access Control (RBAC) (`/features/staff`)
- **Granular Permissions**:
  - *Owner*: Unrestricted access to financials, payouts, settings, and developer keys.
  - *Manager*: Day-to-day order operations, customer communications, and catalog management.
  - *Warehouse / Dispatcher*: Restricted strictly to packing and scanning waybills; cannot see store profits or supplier costs.
- **Action Audit Logs**: Complete record of which staff member confirmed, packed, or edited an order.

### 3.15. Multi-Channel Sales Integration (`/features/sales-channels`)
- **Unified Order Pool**: Ingest orders from your website, WhatsApp chats, Facebook Shop, TikTok Shop, and offline phone orders into one place.

### 3.16. Sales Orders Processing (`/features/sales-orders`)
- **B2B & Wholesale Orders**: Handle credit terms, partial payments, and custom quote creation for bulk corporate buyers.

### 3.17. Sales Returns & RTO Management (`/features/sales-returns`)
- **Courier Return Reconciliation**: Audit returned parcels against courier return manifests.
- **Restocking Workflow**: Inspect returned goods and return sellable units back to active inventory with 1 click.

### 3.18. Purchase Orders (PO) (`/features/purchase-orders`)
- **Supplier Ordering**: Generate professional PDF purchase orders with payment terms and delivery dates.
- **Goods Received Notes (GRN)**: Receive shipments and automatically update stock counts upon arrival.

### 3.19. Vendor Payments (`/features/vendor-payments`)
- **Accounts Payable**: Track outstanding dues to factories, suppliers, and courier partners.
- **Payment Remittances**: Record partial settlements, check payments, and bank transfers.

### 3.20. Vendor Price Lists (`/features/vendor-price-lists`)
- **Comparative Cost Tracking**: Record item pricing across multiple vendors to identify the cheapest supplier and maximize gross margins.

### 3.21. Dynamic Reorder Points (`/features/reorder-points`)
- **Safety Stock Triggers**: Set minimum stock levels that trigger automated warning emails when inventory drops below threshold.
- **Lead-Time Calculation**: Recommends when to place new purchase orders before popular items go out of stock.

### 3.22. Back Orders & Pre-Orders (`/features/back-orders`)
- **Sell Before Arrival**: Allow customers to reserve fast-moving stock before the shipment arrives from overseas or the factory.
- **Queue Fulfillment**: Automatically allocate incoming stock to back orders on a first-come, first-served basis.

### 3.23. Serial & Batch Number Tracking (`/features/serial-batch-tracking`)
- **Warranty Tracking**: Track unique electronics serial numbers across sales and returns.
- **Batch Expiration**: First-In, First-Out (FIFO) batch management for cosmetics, supplements, and food products.

### 3.24. Invoicing & Digital Receipts (`/features/invoicing`)
- **Branded Tax Invoices**: Auto-generate clean, printable PDF receipts with merchant VAT/SVAT registration numbers and custom signatures.
- **Digital Receipt Links**: Send instant invoice links to customers via WhatsApp or SMS.

### 3.25. Business Intelligence & Analytics (`/features/business-intelligence`)
- **Executive Dashboard**: Real-time sales revenue, best-selling SKUs, regional courier delivery success rates, and customer acquisition channels.
- **Net Profit Analyzer**: Deduct product cost (COGS), shipping fees, and ad spend to display actual net profit.

### 3.26. Webhooks & Event Automation (`/features/webhooks-automation`)
- **Real-Time Webhooks**: Subscribe external endpoints to events: `order.created`, `order.packed`, `shipment.dispatched`, `shipment.delivered`, `stock.low`.
- **Custom Automations**: Trigger Google Sheets updates, Slack notifications, or ERP synchronization.

---

## 4. Developer REST API v1 Reference

The Nexlymate Developer REST API v1 enables developers, digital agencies, and e-commerce stores to programmatically create orders, book couriers, check waybills, and synchronize warehouse stock.

### 4.1. General Specifications
- **Base Endpoint**: `https://app.nexlymate.com/api/v1`
- **Data Format**: `application/json` (UTF-8)
- **Authentication**:
  - Standard Bearer: `Authorization: Bearer <YOUR_API_KEY>`
  - Custom Header: `X-API-KEY: <YOUR_API_KEY>`
  - Optional Strict Secret: `X-API-SECRET: <YOUR_API_SECRET>`
- **API Keys**: Generated inside the dashboard under **Settings &rarr; Developer Options**.

### 4.2. Courier Sync Protection Rules
> **Critical Logistics Rule**: When an order is booked with a courier partner (such as Koombiyo or Domex) and an official waybill number is generated:
> - Any `PATCH /api/v1/orders/:id` will be rejected with `409 Conflict` (`ORDER_COURIER_SYNCED`).
> - Any `DELETE /api/v1/orders/:id` will be rejected with `409 Conflict` (`ORDER_COURIER_SYNCED`).
> 
> To modify an order after a waybill has been created, the seller must first call `POST /api/v1/orders/:id/unsync` to cancel the courier booking.

### 4.3. API Endpoints

#### Endpoint 1: Health Ping
- **Method**: `GET`
- **Route**: `/ping`
- **Purpose**: Verify API key validity and connectivity.
- **Response `200 OK`**:
```json
{
  "success": true,
  "message": "Nexlymate Developer API v1 is online and operational.",
  "storeId": "store_9941a0",
  "storeName": "Aura Fashion Lanka",
  "timestamp": "2026-10-18T05:00:00.000Z"
}
```

#### Endpoint 2: Push Order (Create)
- **Method**: `POST`
- **Route**: `/orders`
- **Request Body**:
```json
{
  "customerName": "Kasun Wickramasinghe",
  "phone": "0771234567",
  "address": "No 45/2 Galle Road, Bambalapitiya",
  "city": "Colombo",
  "district": "Colombo",
  "items": [
    {
      "name": "Classic Heavyweight Tee - Black (L)",
      "qty": 2,
      "price": 2450.00
    }
  ],
  "shippingFee": 350.00,
  "paymentMethod": "COD",
  "notes": "Call customer before delivery",
  "email": "kasun@example.com"
}
```
- **Response `201 Created`**:
```json
{
  "success": true,
  "message": "Order created successfully.",
  "order": {
    "id": "ord_89f02a",
    "orderId": "STO-10492",
    "customerName": "Kasun Wickramasinghe",
    "phone": "0771234567",
    "totalPayable": 5250,
    "paymentMethod": "COD",
    "deliveryStatus": "Open",
    "syncStatus": "Sync Not Started"
  }
}
```

#### Endpoint 3: List Orders
- **Method**: `GET`
- **Route**: `/orders?page=1&limit=20&deliveryStatus=Open`
- **Query Parameters**:
  - `page`: Page index (default: `1`)
  - `limit`: Items per page (default: `20`, max: `100`)
  - `deliveryStatus`: Filter (`Open`, `Packed`, `Dispatched`, `Delivered`, `Returned`)
  - `search`: Keyword for customer name, phone, or waybill number.

#### Endpoint 4: Get Single Order
- **Method**: `GET`
- **Route**: `/orders/:id`
- **Response `200 OK`**: Returns complete order record including customer contacts, line items, payment status, and waybill numbers.

#### Endpoint 5: Edit Order
- **Method**: `PATCH`
- **Route**: `/orders/:id`
- **Behavior**: Updates customer details, shipping address, or items. Returns `409 Conflict` if order is already synced to a courier partner.

#### Endpoint 6: Delete Order
- **Method**: `DELETE`
- **Route**: `/orders/:id`
- **Behavior**: Archives order and restores reserved stock back to warehouse inventory. Returns `409 Conflict` if courier waybill is active.

#### Endpoint 7: Automated Courier Dispatch
- **Method**: `POST`
- **Route**: `/orders/:id/dispatch`
- **Request Body**:
```json
{
  "courier": "koombiyo",
  "packageWeight": 1.5,
  "remarks": "Handle with care"
}
```
- **Supported Couriers**: `koombiyo`, `domex`, `royal`, `fardar`, `trans_express`
- **Response `200 OK`**:
```json
{
  "success": true,
  "message": "Order dispatched successfully to koombiyo",
  "courier": "koombiyo",
  "waybillNumber": "KMB-COL-8829104",
  "trackingUrl": "https://nexlymate.com/track?wb=KMB-COL-8829104"
}
```

#### Endpoint 8: Unsync Courier Waybill
- **Method**: `POST`
- **Route**: `/orders/:id/unsync`
- **Behavior**: Cancels courier booking, removes tracking number, and unlocks the order.

#### Endpoint 9: Product Stock Query & Adjustment
- **Method**: `GET /products` — List catalog with available stock.
- **Method**: `PUT /products/:id/stock` — Adjust quantity:
```json
{
  "adjustment": -2,
  "warehouseId": "wh_central"
}
```

---

## 5. Frequently Asked Questions (FAQ)

### Q1: What is Nexlymate and who is it for?
**A**: Nexlymate is an all-in-one cloud Order Management System (OMS) and E-Commerce Website Builder specifically engineered for the **Republic of COD Business** — Sri Lankan retail merchants, direct-to-consumer (D2C) brands, and online sellers who manage Cash on Delivery orders, courier deliveries, and warehouse stock.

### Q2: How much does Nexlymate cost?
**A**:
- **Free Forever**: LKR 0 / month (up to 100 orders/mo).
- **Starter**: LKR 5,000 / month (500 orders/mo, Rs. 8/extra order).
- **Business (Most Popular)**: LKR 12,000 / month (2,000 orders/mo, Rs. 5/extra order, includes Website Builder).
- **Premium (Entrepreneur)**: LKR 15,000 / month (5,000 orders/mo, Rs. 2/extra order).
- **Enterprise**: LKR 24,000 / month (Unlimited orders, zero extra fees, custom domain).

### Q3: Which courier companies in Sri Lanka work with Nexlymate?
**A**: Nexlymate natively integrates with:
1. **Koombiyo Courier**
2. **Domex Courier**
3. **Royal Express**
4. **Fardar Express**
5. **Trans Express**
You can book deliveries in 1 click, automatically receive waybill numbers, and print thermal 4x6" shipping labels directly from Nexlymate without logging into individual courier websites.

### Q4: How do my customers track their orders?
**A**: Customers can track their packages directly at **https://www.nexlymate.com/track** by entering their waybill number or registered mobile phone number.

### Q5: How does Nexlymate stop fake Cash on Delivery orders?
**A**: Nexlymate provides:
- **Phone OTP Verification**: Sends a one-time passcode to verify the buyer's phone before confirming the order.
- **Customer Return Risk Scoring**: Warns you if a phone number or address has a history of rejecting COD deliveries.
- **Anti-Ban Social Media Tunnel Links**: Safely routes ad traffic from TikTok, Instagram, and Facebook into WhatsApp without getting your ad account banned.

### Q6: Can I connect my existing WooCommerce or Shopify store?
**A**: Yes! You can use the **Nexlymate REST API v1** (`https://app.nexlymate.com/api/v1`) or Webhooks to automatically push incoming orders from WooCommerce, Shopify, or custom websites directly into Nexlymate for automated courier dispatch and tracking.

### Q7: How can I contact Nexlymate for sales, support, or billing?
**A**:
- **Official WhatsApp**: `+94 72 421 1333` (https://wa.me/94724211333)
- **Website**: https://nexlymate.com/
- **Login / App**: https://app.nexlymate.com/login