Developer Documentation

Nexlymate REST API v1 Reference

Connect your custom storefront, WooCommerce, Shopify, or mobile application to automate incoming order management, courier waybill generation, and stock sync.

Base URL: https://app.nexlymate.com/api/v1 Auth: Authorization: Bearer vs_live_... Payload: application/json

OpenAPI 3.1 Spec (JSON) Raw AI / LLM Context (TXT)

Getting Started

1. Authentication

Every HTTP request to the Nexlymate REST API must include your store's API Key. You can generate and view your API Key and Secret inside the Settings → Developer Options tab in your Nexlymate dashboard.

Method	Header / Parameter	Example
Bearer Token (Recommended)	`Authorization: Bearer <api_key>`	`Authorization: Bearer vs_live_3f9b...`
Custom Header	`X-API-KEY: <api_key>`	`X-API-KEY: vs_live_3f9b...`
Optional Strict Secret	`X-API-SECRET: <api_secret>`	`X-API-SECRET: vss_live_e91a...`

cURL Test Connection

curl -X GET https://app.nexlymate.com/api/v1/ping \
  -H "Authorization: Bearer vs_live_your_api_key_here"

Response 200 OK

{
  "success": true,
  "message": "Nexlymate Developer API v1 is online and operational.",
  "storeId": "store_9941a0",
  "storeName": "Aura Fashion Lanka",
  "timestamp": "2026-10-08T00:15:00.000Z"
}

Logistics Safeguard

2. Courier Sync Protection

Nexlymate OMS prevents accidental parcel mismatches by enforcing a strict immutability rule once an order is booked with a courier partner (such as Koombiyo, Domex, or Royal Express) and a waybill number is issued.

Strict Courier Sync Protection: Once an order has a waybill number or its delivery status is Dispatched, In-Transit, or Delivered:

Editing via PATCH /api/v1/orders/:id will be rejected with 409 Conflict (ORDER_COURIER_SYNCED).
Deleting via DELETE /api/v1/orders/:id will be rejected with 409 Conflict (ORDER_COURIER_SYNCED).

If you need to change customer details or items, cancel the courier waybill first using POST /api/v1/orders/:id/unsync.

External Storefront Ingestion

3. Push Order (Create)

Send incoming checkout orders from your external WooCommerce, Shopify, or custom React/PHP website directly to Nexlymate OMS.

POST /api/v1/orders

Required & Optional Fields

Field	Type	Status	Description & Example
`customerName`	String	Required	Customer's full name. e.g. `"Kasun Wickramasinghe"`
`phone`	String	Required	10-digit Sri Lankan phone number. e.g. `"0771234567"`
`address`	String	Required	Delivery street address. e.g. `"No 45/2 Galle Road"`
`city`	String	Required	Delivery city. e.g. `"Bambalapitiya"`
`district`	String	Required	District for courier routing. e.g. `"Colombo"`
`items`	Array	Required	List of products: `[ { "name": "Classic T-Shirt", "qty": 2, "price": 1500 } ]`
`paymentMethod`	String	Optional	`"COD"`, `"Card"`, or `"Bank"`. Defaults to `"COD"`.
`shippingFee`	Number	Optional	Delivery charge in LKR. e.g. `350`
`notes`	String	Optional	Special delivery instructions for warehouse or courier.
`email`	String	Optional	Customer email for digital invoice delivery.

JSON Request Body

{
  "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"
}

Response 201 Created

{
  "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"
  }
}

Order Management

4. List Orders (Query & Search)

Fetch paginated orders from your store pipeline with filtering by delivery status and search keyword.

GET /api/v1/orders?page=1&limit=20&deliveryStatus=Open

Response 200 OK

{
  "success": true,
  "data": [
    {
      "id": "ord_89f02a",
      "orderId": "STO-10492",
      "customerName": "Kasun Wickramasinghe",
      "phone": "0771234567",
      "totalPayable": 5250,
      "deliveryStatus": "Open",
      "waybillNumber": ""
    }
  ],
  "pagination": {
    "total": 142,
    "page": 1,
    "limit": 20,
    "totalPages": 8
  }
}

Order Details

5. Single Order Retrieval

Inspect an individual order including live courier waybill tracking and customer contacts.

GET /api/v1/orders/:id

Order Updates

6. Edit Order (PATCH)

Update customer details, items, or notes. Blocked if the order is already synced to a courier.

PATCH /api/v1/orders/:id

Courier Lock: If a waybill is already generated, this returns 409 Conflict (ORDER_COURIER_SYNCED).

Order Cancellation

7. Delete Order

Soft-deletes the order, restores allocated stock, and archives it into the order history archive.

DELETE /api/v1/orders/:id

Logistics Automation

8. Automated Courier Dispatch

Book a consignment with Koombiyo, Domex, or Royal Express and immediately receive an official tracking waybill number.

POST /api/v1/orders/:id/dispatch

Response 200 OK — Dispatched

{
  "success": true,
  "message": "Order dispatched successfully to koombiyo",
  "courier": "koombiyo",
  "waybillNumber": "KMB-COL-8829104",
  "trackingUrl": "https://nexlymate.com/track?wb=KMB-COL-8829104"
}

Waybill Cancellation

9. Unsync Waybill

Cancels the courier consignment with the courier partner and unlocks the order so that customer details or items can be modified again.

POST /api/v1/orders/:id/unsync

Warehouse & Stock

10. Products & Inventory Sync

Query live product stock quantities across your warehouses or sync stock changes atomically from your in-store POS system.

GET /api/v1/products

PUT /api/v1/products/:id/stock

PUT /api/v1/products/:id/stock

{
  "adjustment": -2
}

Multi-Language SDKs

11. Integration Code Examples

Copy and paste these battle-tested code snippets into your external store codebase:

Bash / Terminal

curl -X POST https://app.nexlymate.com/api/v1/orders \
  -H "Authorization: Bearer vs_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "customerName": "Kamal Perera",
    "phone": "0771234567",
    "address": "No 45, Galle Road, Colombo 3",
    "city": "Colombo",
    "district": "Colombo",
    "items": [
      { "name": "Blue Polo Shirt (L)", "qty": 2, "price": 1850 }
    ],
    "shippingFee": 350,
    "paymentMethod": "COD"
  }'

JavaScript (Node / Next.js API Route)

const response = await fetch('https://app.nexlymate.com/api/v1/orders', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vs_live_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customerName: 'Kamal Perera',
    phone: '0771234567',
    address: 'No 45, Galle Road, Colombo 3',
    city: 'Colombo',
    district: 'Colombo',
    items: [
      { name: 'Blue Polo Shirt (L)', qty: 2, price: 1850 }
    ],
    shippingFee: 350,
    paymentMethod: 'COD'
  })
});
const result = await response.json();
console.log('Order ID:', result.order.orderId);

PHP (WooCommerce Hook)

<?php
$payload = json_encode([
    'customerName'  => 'Kamal Perera',
    'phone'         => '0771234567',
    'address'       => 'No 45, Galle Road, Colombo 3',
    'city'          => 'Colombo',
    'district'      => 'Colombo',
    'items'         => [
        ['name' => 'Blue Polo Shirt (L)', 'qty' => 2, 'price' => 1850]
    ],
    'shippingFee'   => 350,
    'paymentMethod' => 'COD'
]);

$ch = curl_init('https://app.nexlymate.com/api/v1/orders');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer vs_live_your_api_key_here',
    'Content-Type: application/json'
]);
$response = curl_exec($ch);
curl_close($ch);
?>

Python (requests)

import requests

url = "https://app.nexlymate.com/api/v1/orders"
headers = {
    "Authorization": "Bearer vs_live_your_api_key_here",
    "Content-Type": "application/json"
}
payload = {
    "customerName": "Kamal Perera",
    "phone": "0771234567",
    "address": "No 45, Galle Road, Colombo 3",
    "city": "Colombo",
    "district": "Colombo",
    "items": [{"name": "Blue Polo Shirt (L)", "qty": 2, "price": 1850}],
    "shippingFee": 350,
    "paymentMethod": "COD"
}
res = requests.post(url, json=payload, headers=headers)
print(res.json())

Specifications

12. Error Codes & Rate Limits

Standard HTTP status codes are used to communicate API execution outcomes. Rate limiting is 120 requests/minute per API key.

Status Code	Error Code	Meaning & Guidance
200 OK	—	Request succeeded cleanly.
201 Created	—	Order or resource successfully recorded.
400 Bad Request	`INVALID_PAYLOAD`	Malformed JSON or missing required fields (customerName, phone, etc.).
401 Unauthorized	`AUTH_MISSING_KEY`	Missing or invalid Bearer key. Check your key in Settings → Developer Options.
404 Not Found	`NOT_FOUND`	Requested order or product ID does not exist in your store.
409 Conflict	`ORDER_COURIER_SYNCED`	Order is locked because it is already synced with a courier partner.
429 Too Many Requests	`RATE_LIMITED`	Exceeded 120 req/min limit. Implement exponential backoff retry.
500 Server Error	`SERVER_ERROR`	Internal server error. Contact Nexlymate developer support.

Ready to connect your online store?

Get your API credentials and start pushing orders to Nexlymate OMS in under five minutes.

Open Developer Options Contact Engineering