SysPOS MCP Server — API Docs

Everything AI agents need to use SysPOS MCP tools

Authentication

How to Call Tools

Option 1: Claude.ai custom connector (no code)

In Claude → Settings → Connectors → Add custom connector:

Name:                  SysPOS Product Tools
Remote MCP server URL: https://pos-mcp.syspos.ae/mcp
OAuth Client ID/Secret: (leave blank)

→ Add → Connect → paste your syspos_... key → Authorize

Option 2: REST API (any HTTP client)

Simple HTTP POST — works with curl, fetch, n8n, Make, anything.

POST https://pos-mcp.syspos.ae/api/call
Authorization: Bearer syspos_your_key_here
Content-Type: application/json

{
  "tool": "list_products"
}

Option 3: MCP Protocol — SSE (Claude Desktop, Cursor, custom agents)

Use the remote MCP URL plus a Bearer header — the standard MCP-over-HTTP shape:

# MCP endpoint URL
https://pos-mcp.syspos.ae/sse

# Claude Desktop / Cursor / generic MCP client config
{
  "mcpServers": {
    "syspos": {
      "url": "https://pos-mcp.syspos.ae/sse",
      "headers": { "Authorization": "Bearer syspos_your_key_here" }
    }
  }
}

# Claude Code CLI
claude mcp add syspos --transport sse https://pos-mcp.syspos.ae/sse \
  --header "Authorization: Bearer syspos_your_key_here"

Machine-Readable Docs for Agents

AI agents can fetch full tool schemas as JSON — no HTML parsing needed:

# Full docs with parameters, types, and example responses
curl https://pos-mcp.syspos.ae/api/docs

# Tool list with full parameter schemas
curl https://pos-mcp.syspos.ae/api/tools

Error Handling

Agent Integration Guide

System prompt template

Add this to your agent's instructions:

You have access to SysPOS product tools.

API endpoint:  https://pos-mcp.syspos.ae/api/call
Method:        POST
Content-Type:  application/json
Authorization: Bearer syspos_your_key_here

Rules:
- Use list_products to fetch the catalog. Pass limit if you need a page size other than the full catalog.
- Do not send customer_id. Tenant comes from the MCP API key.
- Create/update bodies match the dashboard product payload (name, prices, location_prices, modifiers, …).

Tool Reference

list_selling_products

GET /api/v2/products. Why: The menu the session branch sells — exactly what web-pos loads: live products of this branch with the branch price (actual_price, VAT incl.), option-group links (modifiers[]), sold-out flag and combo slots. Use it to show a menu or build a cart; use list_products only to manage the catalog. Paginated: loop current_page until you have total_records rows. Pair with list_selling_modifiers (option groups) and list_selling_addons (add-ons). Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_selling_products"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_selling_products"
}'

Example Response

{
  "status": true,
  "message": "Data found ",
  "data": {
    "current_page": 1,
    "records_per_page": 50,
    "total_records": 1066,
    "products": [
      {
        "id": 257509,
        "category_id": 15430,
        "name": "Vanilla Latte",
        "description": "Authentic Flavors",
        "price": 10,
        "stock": 0,
        "type": "Specialty & Flavored Coffees",
        "image": "",
        "customer_id": 437,
        "location_id": 907,
        "is_addon": 0,
        "addons": "[]",
        "bundle_items": "[]",
        "is_disabled": 0,
        "discount_pct": 0,
        "modifiers": [
          {
            "priority": 3,
            "max_allowed": 3,
            "min_allowed": 0,
            "modifier_id": 3687
          },
          {
            "priority": 2,
            "max_allowed": 3,
            "min_allowed": 0,
            "modifier_id": 3703
          },
          {
            "priority": 1,
            "max_allowed": 3,
            "min_allowed": 0,
            "modifier_id": 3710
          },
          {
            "priority": 4,
            "max_allowed": 3,
            "min_allowed": 0,
            "modifier_id": 3986
          },
          {
            "priority": 5,
            "max_allowed": 3,
            "min_allowed": 0,
            "modifier_id": 3987
          },
          {
            "priority": 6,
            "max_allowed": 3,
            "min_allowed": 0,
            "modifier_id": 3988
          },
          {
            "priority": 7,
            "max_allowed": 3,
            "min_allowed": 0,
            "modifier_id": 3989
          },
          {
            "priority": 5,
            "max_allowed": 1,
            "min_allowed": 0,
            "modifier_id": 5622
          }
        ],
        "is_archive": 0,
        "barcode_type": null,
        "barcode_value": null,
        "is_open_price": 0,
        "is_combo": 0,
        "sync_deliverect": 0,
        "sync_otter": 0,
        "new_cost_date": null,
        "product_cost": null,
        "is_weightage_item": 0,
        "unit_id": 0,
        "actual_price": 10,
        "old_price": null,
        "vat": 0.48,
        "localized": null,
        "base_price": null,
        "menu_sort_order": 0,
        "plu": null,
        "calories": null,
        "is_stock_product": 0,
        "is_auto_apply": null,
        "combo_price": 0,
        "localize_name": "Vanilla Latte",
        "localize_description": "Coffee",
        "label_id": 50,
        "recipes": null,
        "sku_no": "prod-437-257509",
        "tax_id": 16,
        "preparation_time": 0,
        "product_recipe_total": 0,
        "product_material_total": 0,
        "is_overridden": 0,
        "is_deleted": 0,
        "category_sort_order": null,
        "is_sold_out": 0,
        "auto_selected_modifier_items": [],
        "price_levels": [],
        "tax_name": "Food Card Tax",
        "tax_value": 5,
        "image_path": "",
        "web_image": ""
      }
    ]
  }
}

list_products

GET /api/products/webProducts. Why: Catalog management view: every product of the tenant with its master price, category, label, branch list and recipe/channel flags — this is the dashboard product list, not the POS selling menu (use list_selling_products to show or sell from a branch menu; it has branch prices, sold-out and modifier links). Use it to search/filter products and get ids for get_product → update_product / archive_product / delete_product. Filters take ids from list_categories (category_id), list_brands (brand_id), list_labels (label_id), list_channels (channel_id), list_locations (loc). `type` is the category name the POS files the product under (list_selling_categories, sync_invoice line type). Add-ons: list_addons. Per-branch prices, modifier links, BOM and recipes are NOT here — call get_product. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_products"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_products"
}'

Example Response

{
  "data": [
    {
      "id": 257508,
      "category_id": 15231,
      "name": "Mocha",
      "description": "Authentic Flavors",
      "price": 10,
      "stock": 0,
      "type": "Espresso-Based Drinks",
      "image": "https://dev1.syspos.ae/api/uploads/1780385109749-apple.png",
      "customer_id": 437,
      "location_id": [
        908,
        907
      ],
      "is_addon": 0,
      "addons": "[]",
      "bundle_items": "[]",
      "is_disabled": 0,
      "discount_pct": 0,
      "modifiers": null,
      "is_archive": 0,
      "barcode_type": "",
      "barcode_value": "",
      "is_open_price": 0,
      "is_combo": 0,
      "sync_deliverect": 0,
      "sync_otter": 0,
      "new_cost_date": null,
      "product_cost": null,
      "is_weightage_item": 0,
      "unit_id": 0,
      "actual_price": 10,
      "old_price": null,
      "vat": 0.48,
      "localized": null,
      "base_price": null,
      "menu_sort_order": 0,
      "plu": 0,
      "calories": null,
      "is_stock_product": 0,
      "is_auto_apply": null,
      "combo_price": 0,
      "localize_name": "Mocha",
      "localize_description": "Coffee",
      "label_id": 50,
      "recipes": null,
      "sku_no": "pd-437-257508",
      "tax_id": 16,
      "preparation_time": 0,
      "product_recipe_total": 50,
      "product_material_total": 0,
      "is_overridden": 0,
      "is_deleted": 0,
      "category_sort_order": null,
      "override_location_id": 908,
      "override_name": "Mocha",
      "override_description": "Authentic Flavors",
      "override_price": 10,
      "override_actual_price": 10,
      "image_path": "1780385109749-apple.png",
      "web_image": "1780385109749-apple.png",
      "channel_price": [],
      "nameChannels": {
        "channels": []
      },
      "total_locations": 2,
      "has_recipe": 1
    }
  ],
  "total": 2745
}

get_product

GET /api/products/:id. Why: Full catalog record of one product — per-branch prices (location_prices), modifier links per branch, channel prices, BOM materials and recipes — which list_products does not return. Always call it before update_product: update is not a patch, so you resend location_prices, modifiers, materials, recipes, channel_price and the columns from this record. For selling/menu display use list_selling_products instead. Ids here link to list_locations (location_prices), list_modifiers / list_selling_modifiers and list_modifier_items (modifiers), list_channels (channel_price), list_materials, list_recipes, list_categories (category_id; type = category name), list_labels (label_id). Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_product"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_product",
  "id": 11
}'

Example Response

[
  {
    "id": 257508,
    "category_id": 15231,
    "name": "Mocha",
    "description": "Authentic Flavors",
    "price": 10,
    "stock": 0,
    "type": "Espresso-Based Drinks",
    "image": "https://dev1.syspos.ae/api/uploads/1780385109749-apple.png",
    "customer_id": 437,
    "location_id": [
      907,
      908
    ],
    "is_addon": 0,
    "addons": [],
    "bundle_items": [],
    "is_disabled": 0,
    "discount_pct": 0,
    "modifiers": [
      {
        "id": 136528,
        "modifier_id": 3687,
        "max_allowed": 3,
        "min_allowed": 0,
        "priority": 4,
        "location_id": 907,
        "customer_id": 437,
        "selection_type": "multiple",
        "auto_selected_modifier_item_ids": [],
        "mandatory_modifier_item_ids": [],
        "unavailable_modifier_item_ids": [],
        "modifier_items_order": [
          18005,
          18052,
          22145,
          22146
        ]
      }
    ],
    "is_archive": 0,
    "barcode_type": "",
    "barcode_value": "",
    "is_open_price": 0,
    "is_combo": 0,
    "sync_deliverect": 0,
    "sync_otter": 0,
    "new_cost_date": null,
    "product_cost": null,
    "is_weightage_item": 0,
    "unit_id": 0,
    "actual_price": 10,
    "old_price": null,
    "vat": 0.48,
    "localized": null,
    "base_price": null,
    "menu_sort_order": 0,
    "plu": 0,
    "calories": null,
    "is_stock_product": 0,
    "is_auto_apply": null,
    "combo_price": 0,
    "localize_name": "Mocha",
    "localize_description": "Coffee",
    "label_id": 50,
    "recipes": [
      {
        "id": 16779,
        "name": "Test",
        "yield_qty": 0.8,
        "mode": "stockable",
        "recipe_id": 16779,
        "product_id": 257508,
        "portion_qty": 0.8,
        "unit": "Kilogram",
        "active_from": null,
        "active_to": null,
        "qty_used": 1
      }
    ],
    "sku_no": "pd-437-257508",
    "tax_id": 16,
    "preparation_time": 0,
    "product_recipe_total": 50,
    "product_material_total": 0,
    "is_overridden": 0,
    "is_deleted": 0,
    "category_sort_order": null,
    "image_path": "1780385109749-apple.png",
    "web_image": "1780385109749-apple.png",
    "channel_price": [],
    "materials": [],
    "location_prices": [
      {
        "location_id": 907,
        "location_name": "Default location",
        "location_price": 10,
        "location_actual_price": 10,
        "is_available": true
      }
    ]
  }
]

list_selling_categories

GET /api/v2/categories. Why: Menu categories of a branch — what web-pos loads for its category rail. Use it to group list_selling_products into a menu. A product belongs to a category when product.type == category.name (web-pos's main link) or product.category_id == category.id. Not paginated. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_selling_categories"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_selling_categories"
}'

Example Response

[
  {
    "id": 17557,
    "name": "Footwear",
    "description": "Shoes",
    "customer_id": 437,
    "location_id": 907,
    "color": null,
    "image": "https://dev1.syspos.ae/api/uploads/1767085134601-shoes.jpg",
    "is_active": 1,
    "sync_otter": 0,
    "sync_deliverect": 0,
    "sync_menu": 1,
    "menu_sort_order": 12,
    "sync_bitebell": 1,
    "localize_name": null,
    "localize_description": null,
    "sku_no": "cat-437-17557",
    "is_deleted": 0,
    "sync_grubtech": 0,
    "web_image": "api/uploads/1767085134601-shoes.jpg"
  }
]

list_categories

GET /api/categories. Why: Dashboard catalog view of categories (the Products → Categories list), not the POS selling rail — use list_selling_categories to see what a branch actually sells. Use it to search by name, filter by branch / group / brand / active flag, get category ids for get_category → update_category / delete_category, and the id + name a product needs (product.category_id = id, product.type = name). Shows each category's branches (categories_locations) and groups (group_categories). Includes inactive categories unless is_active=1. Not paginated. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_categories"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_categories"
}'

Example Response

[
  {
    "id": 17557,
    "name": "Footwear",
    "description": "Shoes",
    "customer_id": 437,
    "sku_no": "cat-437-17557",
    "location_id": [
      909,
      908,
      922,
      910,
      907,
      1131
    ],
    "color": null,
    "image": "1767085134601-shoes.jpg",
    "web_image": "api/uploads/1767085134601-shoes.jpg",
    "is_active": 1,
    "sync_otter": 0,
    "sync_deliverect": 0,
    "sync_menu": 1,
    "sync_bitebell": 1,
    "sync_grubtech": 0,
    "menu_sort_order": 12,
    "total_categories": 39,
    "groups": [
      {
        "id": 1465,
        "group_name": "Accessories",
        "categories_count": 1
      }
    ]
  }
]

get_category

GET /api/categories/:id. Why: Full dashboard record of ONE category (the Edit Category page): every column, its branches, its groups, and the active products filed under it by category_id (linked_products) — list_categories has no product list. Use it (a) as the base body for update_category (image / is_active / sync_* / menu_sort_order reset if omitted), (b) to check linked_products_count and groups before delete_category. For what a branch sells use list_selling_categories / list_selling_products instead. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_category"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_category",
  "id": 11
}'

Example Response

[
  {
    "id": 17557,
    "name": "Footwear",
    "description": "Shoes",
    "customer_id": 437,
    "location_id": [
      909,
      908,
      922,
      910,
      907,
      1131
    ],
    "color": null,
    "image": "https://dev1.syspos.ae/api/uploads/1767085134601-shoes.jpg",
    "is_active": 1,
    "sync_otter": 0,
    "sync_deliverect": 0,
    "sync_menu": 1,
    "menu_sort_order": 12,
    "sync_bitebell": 1,
    "localize_name": null,
    "localize_description": null,
    "sku_no": "cat-437-17557",
    "is_deleted": 0,
    "sync_grubtech": 0,
    "web_image": "api/uploads/1767085134601-shoes.jpg",
    "groups": [
      {
        "id": 1465,
        "group_name": "Accessories",
        "categories_count": 1
      }
    ],
    "linked_products": [
      {
        "id": 266406,
        "name": "Flip-Flop",
        "sku_no": "prod-437-266406",
        "price": 10,
        "is_archive": 0,
        "category_sort_order": 0,
        "image": "",
        "web_image": ""
      }
    ],
    "linked_products_count": 2
  }
]

list_selling_modifiers

POST /api/v2/modifiers. Why: All option groups (Size, Milk, Toppings…) available at a branch, each with its items and item prices — what web-pos loads once, then looks up by product.modifiers[].modifier_id from list_selling_products. Read-only despite POST; no body. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_selling_modifiers"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_selling_modifiers"
}'

Example Response

{
  "status": true,
  "message": "Record Found",
  "data": [
    {
      "id": 3687,
      "name": "Buntie",
      "description": "",
      "selection_allowed": 1,
      "selection_min_allowed": -1,
      "priority": 2,
      "items": [
        {
          "id": 18005,
          "name": "Chocolate buntie",
          "description": "",
          "price": 5,
          "modifier_id": 3687,
          "actual_price": 5,
          "vat": 0,
          "priority": 1,
          "image": "",
          "tax_id": 16,
          "tax_name": "Food Card Tax",
          "tax_value": 5,
          "instructions": [
            {
              "id": 39,
              "instruction": "Modifier 123",
              "priority": 0
            }
          ],
          "web_image": ""
        },
        {
          "id": 18052,
          "name": "Rainbow",
          "description": "",
          "price": 5,
          "modifier_id": 3687,
          "actual_price": 5,
          "vat": 0,
          "priority": 2,
          "image": "",
          "tax_id": null,
          "tax_name": null,
          "tax_value": null,
          "instructions": [
            {
              "id": 40,
              "instruction": "Modifier",
              "priority": 0
            },
            {
              "id": 140,
              "instruction": "Modifier",
              "priority": 0
            },
            {
              "id": 141,
              "instruction": "Modifier are extra",
              "priority": 1
            }
          ],
          "web_image": ""
        },
        {
          "id": 22145,
          "name": "Rainbow Buntie",
          "description": "",
          "price": 5,
          "modifier_id": 3687,
          "actual_price": 5,
          "vat": 0,
          "priority": 3,
          "image": "",
          "tax_id": null,
          "tax_name": null,
          "tax_value": null,
          "instructions": [
            {
              "id": 42,
              "instruction": "Modifier",
              "priority": 0
            },
            {
              "id": 142,
              "instruction": "Modifier",
              "priority": 0
            },
            {
              "id": 143,
              "instruction": "Modifier are extra",
              "priority": 1
            }
          ],
          "web_image": ""
        },
        {
          "id": 22146,
          "name": "Plain Buntie",
          "description": "",
          "price": 5,
          "modifier_id": 3687,
          "actual_price": 5,
          "vat": 0,
          "priority": 4,
          "image": "",
          "tax_id": null,
          "tax_name": null,
          "tax_value": null,
          "instructions": [
            {
              "id": 43,
              "instruction": "Modifier",
              "priority": 0
            },
            {
              "id": 144,
              "instruction": "Modifier",
              "priority": 0
            },
            {
              "id": 145,
              "instruction": "Modifier are extra",
              "priority": 1
            }
          ],
          "web_image": ""
        }
      ]
    }
  ]
}

list_modifiers

GET /api/modifiers. Why: Catalog management (dashboard Products › Modifiers list): every modifier GROUP of the tenant with its branch list and group defaults — no items, no product links. Use it to find a group id for get/update/delete_modifier, list_modifier_items modifier_id=, create/update_modifier_item modifier_ids and update_product modifiers[].modifier_id. To SELL (a group with its options and prices at a branch) use list_selling_modifiers; items of a group: list_modifier_items modifier_id=<id>; which products use a group: get_product / list_selling_products modifiers[]. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_modifiers"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_modifiers"
}'

Example Response

[
  {
    "id": 4865,
    "name": "Basic Accessory",
    "description": "",
    "location_id": [
      922,
      907,
      908,
      909,
      910,
      1131
    ],
    "customer_id": 437,
    "selection_allowed": 0,
    "selection_min_allowed": 0,
    "priority": 0,
    "is_deleted": 0,
    "localize_name": null,
    "localize_description": null,
    "sku_no": null,
    "is_mandatory": 0
  }
]

get_modifier

GET /api/modifiers/:id. Why: Catalog management: load ONE modifier group (name, group min/max defaults, priority, translations, branch list) before update_modifier — update is a full overwrite, so read first and resend every field. No items (list_modifier_items modifier_id=<id>) and no linked products (get_product modifiers[]). For selling use list_selling_modifiers. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_modifier"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_modifier",
  "id": 11
}'

Example Response

[
  {
    "id": 3687,
    "name": "Buntie",
    "description": "",
    "location_id": [
      907,
      908,
      909,
      910,
      922,
      1131
    ],
    "customer_id": 437,
    "selection_allowed": 1,
    "selection_min_allowed": -1,
    "priority": 2,
    "is_deleted": 0,
    "localize_name": null,
    "localize_description": null,
    "sku_no": "mod-437-3687",
    "is_mandatory": 0
  }
]

list_modifier_items

GET /api/modifierItems. Why: Catalog management (dashboard Products › Modifier Items list): options flat, with their groups, branches and price — to find an item id for get/update/delete_modifier_item or for update_product default / mandatory / unavailable item ids. Filter one group with modifier_id (also returns items linked to it as a second group). To SELL (groups with nested options + kitchen instructions at a branch) use list_selling_modifiers, which nests each option only under its primary modifier_id. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_modifier_items"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_modifier_items"
}'

Example Response

[
  {
    "id": 18005,
    "name": "Chocolate buntie",
    "description": "",
    "price": 5,
    "customer_id": 437,
    "location_id": [
      1131,
      922,
      910,
      909,
      908,
      907
    ],
    "modifier_id": 3687,
    "actual_price": 5,
    "old_price": null,
    "vat": 0,
    "base_price": null,
    "localize_name": "Chocolate bunties",
    "localize_description": null,
    "sku_no": "moditem-437-18005",
    "tax_id": 16,
    "priority": 1,
    "is_deleted": 0,
    "image": "",
    "modifier_name": "Buntie",
    "mapped_location_ids": "1131,922,910,909,908,907",
    "tax_name": "Food Card Tax",
    "tax_value": 5,
    "modifier_ids": [
      3687
    ],
    "web_image": ""
  }
]

get_modifier_item

GET /api/modifierItems/:id. Why: Load ONE option before update_modifier_item (dashboard Modifier Items › Edit loads exactly this) — update resets price / priority / tax and replaces groups and branches, so read first and resend actual_price, priority, modifier_ids, location_ids and tax_id. No kitchen instructions (see list_selling_modifiers items[].instructions) and no recipes. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_modifier_item"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_modifier_item",
  "id": 11
}'

Example Response

[
  {
    "id": 18005,
    "name": "Chocolate buntie",
    "description": "",
    "price": 5,
    "customer_id": 437,
    "location_id": [
      907,
      908,
      909,
      910,
      922,
      1131
    ],
    "modifier_id": 3687,
    "actual_price": 5,
    "old_price": null,
    "vat": 0,
    "base_price": null,
    "localize_name": "Chocolate bunties",
    "localize_description": null,
    "sku_no": "moditem-437-18005",
    "tax_id": 16,
    "priority": 1,
    "is_deleted": 0,
    "image": "",
    "modifier_name": "Buntie",
    "modifier": "3687",
    "modifier_ids": [
      3687
    ],
    "web_image": ""
  }
]

list_selling_brands

GET /api/v2/brands. Why: Brands of a branch WITH their groups nested (there is no separate groups route) — what web-pos loads to choose the brand, show the group rail and scope the menu. Each group lists the category ids it contains. Step 1 of building a menu: pick a brand, pick a group, then filter list_selling_categories / list_selling_products by the group's category ids. The chosen brand_id goes on every cart line and on the invoice. Not paginated. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_selling_brands"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_selling_brands"
}'

Example Response

{
  "status": true,
  "message": "brands found",
  "data": [
    {
      "brand_id": 459,
      "brand_name": "Zara",
      "brand_thumbnail": "",
      "location_id": 907,
      "brand_color": "#000",
      "brand_address": "Pakistan",
      "brand_email": "Zara@gmail.com",
      "brand_phone": "12345678",
      "brand_vat_no": "",
      "groups": [
        {
          "group_id": 1462,
          "group_name": "Clothing Brand",
          "group_thumbnail": "",
          "group_description": "",
          "brand_id": 459,
          "categories": [
            17539
          ]
        },
        {
          "group_id": 1465,
          "group_name": "Accessories",
          "group_thumbnail": "",
          "group_description": "",
          "brand_id": 459,
          "categories": [
            15481,
            17556,
            17557,
            15230
          ]
        }
      ]
    }
  ]
}

list_brands

GET /api/brands. Why: Dashboard catalog view of brands (brand management), not the POS selling view — use list_selling_brands to build a branch's menu (it nests each group's category ids). Use this to find brand ids for get_brand / update_brand / delete_brand, and to see each brand's branches (brands_locations) and group names (brands_groups_relation). A brand reaches categories only through its groups: brand → groups (get_brand groups[].id) → categories (list_categories group_id=… or brand_id=…&loc=…) → products. Not paginated. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_brands"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_brands"
}'

Example Response

{
  "status": true,
  "message": "Brand found here",
  "data": [
    {
      "id": 459,
      "brand_name": "Zara",
      "brand_thumbnail": "",
      "description": "Clothing Brand",
      "brand_groups": [
        "Clothing Brand",
        "Accessories"
      ],
      "location_id": [
        922,
        907,
        908,
        909,
        910,
        1131
      ],
      "brand_color": "#000",
      "brand_address": "Pakistan",
      "brand_email": "Zara@gmail.com",
      "brand_phone": "12345678",
      "brand_vat_no": ""
    }
  ]
}

get_brand

GET /api/brands/:id. Why: Full dashboard record of ONE brand: every column, branch ids and its groups with ids. Required before update_brand (which overwrites every field, group link and branch link) and to get the brand's group ids for list_categories group_id / get_group. For the POS menu use list_selling_brands. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_brand"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_brand",
  "id": 11
}'

Example Response

[
  {
    "id": 459,
    "brand_name": "Zara",
    "brand_thumbnail": "",
    "location_id": [
      922,
      907,
      908,
      909,
      910,
      1131
    ],
    "customer_id": 437,
    "description": "Clothing Brand",
    "brand_groups": "1462,1465",
    "brand_color": "#000",
    "user_id": 4734,
    "brand_address": "Pakistan",
    "brand_email": "Zara@gmail.com",
    "brand_phone": "12345678",
    "brand_vat_no": "",
    "sku_no": "brd-437-459",
    "groups": [
      {
        "id": 1462,
        "group_name": "Clothing Brand"
      }
    ]
  }
]

list_groups

GET /api/groups. Why: List the tenant's groups with their linked categories, brands and branches — use it to see how a brand maps to categories, to find the group id to edit, or to check which categories a brand's menu will show. Produces group ids (get_group / update_group / delete_group); categories[].id feed list_categories/list_products filters; brand[].id are list_brands ids. Catalog management (dashboard) tool. For menu scoping on the POS use list_selling_brands, which already returns each brand's groups with their category ids. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_groups"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_groups"
}'

Example Response

{
  "status": true,
  "message": "Groups found",
  "data": [
    {
      "id": 1341,
      "group_name": "Flavor you need",
      "customer_id": 437,
      "location_id": [
        907,
        908,
        909,
        910,
        922,
        907,
        908,
        909,
        910,
        922,
        1131
      ],
      "menu_sort_order": 0,
      "categories": [
        {
          "id": 15481,
          "name": "Alternate Options"
        },
        {
          "id": 15230,
          "name": "Brewed Coffee"
        },
        {
          "id": 15231,
          "name": "Espresso-Based Drinks"
        },
        {
          "id": 15266,
          "name": "Iced & Cold Coffees"
        },
        {
          "id": 16686,
          "name": "Sandwiches"
        },
        {
          "id": 15430,
          "name": "Specialty & Flavored Coffees"
        },
        {
          "id": 16707,
          "name": "Coffee"
        }
      ],
      "brand": [
        {
          "id": 412,
          "brand_name": "Nexus Cafe"
        }
      ]
    }
  ]
}

get_group

GET /api/groups/:id. Why: Load one group with every column plus its categories, brands and branches — required before update_group (which replaces everything). Consumes a group id from list_groups or list_selling_brands. Catalog management (dashboard) tool. For menu scoping on the POS use list_selling_brands, which already returns each brand's groups with their category ids. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_group"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_group",
  "id": 11
}'

Example Response

[
  {
    "id": 1341,
    "group_name": "Flavor you need",
    "group_thumbnail": "1759910641566-coffee.jpg",
    "group_description": "Flavor you need",
    "categories": [
      {
        "id": 15481,
        "name": "Alternate Options"
      },
      {
        "id": 15230,
        "name": "Brewed Coffee"
      },
      {
        "id": 15231,
        "name": "Espresso-Based Drinks"
      },
      {
        "id": 15266,
        "name": "Iced & Cold Coffees"
      },
      {
        "id": 16686,
        "name": "Sandwiches"
      },
      {
        "id": 15430,
        "name": "Specialty & Flavored Coffees"
      },
      {
        "id": 16707,
        "name": "Coffee"
      }
    ],
    "location_id": [
      907,
      908,
      909,
      910,
      922,
      907,
      908,
      909,
      910,
      922,
      1131
    ],
    "customer_id": 437,
    "brand": [
      {
        "id": 412,
        "brand_name": "Nexus Cafe"
      }
    ],
    "user_id": 4734,
    "sku_no": "grp-437-1341",
    "menu_sort_order": 0
  }
]

list_selling_addons

GET /api/v2/products. Why: Add-ons of the session branch (web-pos: GET /api/v2/products?addon=1). An add-on is a small product added ON TOP of a cart line (e.g. extra sandwich with a coffee). Show an add-on for a line only when the add-on's `type` (comma-separated category names) contains the parent product's category name (`type`). Each chosen add-on is charged actual_price × qty and becomes its own invoice line with is_addon = 1 linked to the parent. Same row shape and paging as list_selling_products. web-pos offers NO add-ons when a product is added from search or favourites (no category selected). Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_selling_addons"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_selling_addons"
}'

Example Response

{
  "status": true,
  "message": "Data found ",
  "data": {
    "current_page": 1,
    "records_per_page": 50,
    "total_records": 7,
    "products": [
      {
        "id": 257559,
        "category_id": null,
        "name": "Classic Sandwich",
        "description": "",
        "price": 95,
        "stock": 0,
        "type": "Alternate Options,Brewed Coffee,Espresso-Based Drinks,Iced & Cold Coffees,Specialty & Flavored Coffees",
        "image": "",
        "customer_id": 437,
        "location_id": 907,
        "is_addon": 1,
        "addons": "[]",
        "bundle_items": "[]",
        "is_disabled": 0,
        "discount_pct": 0,
        "modifiers": [],
        "is_archive": 0,
        "barcode_type": "",
        "barcode_value": "",
        "is_open_price": 0,
        "is_combo": 0,
        "sync_deliverect": 0,
        "sync_otter": 0,
        "new_cost_date": null,
        "product_cost": 0,
        "is_weightage_item": 0,
        "unit_id": null,
        "actual_price": 100,
        "old_price": null,
        "vat": 5,
        "localized": null,
        "base_price": null,
        "menu_sort_order": 0,
        "plu": 0,
        "calories": null,
        "is_stock_product": null,
        "is_auto_apply": null,
        "combo_price": 0,
        "localize_name": "",
        "localize_description": "",
        "label_id": null,
        "recipes": null,
        "sku_no": "prod-437-257559",
        "tax_id": null,
        "preparation_time": 0,
        "product_recipe_total": 0,
        "product_material_total": 0,
        "is_overridden": 0,
        "is_deleted": 0,
        "category_sort_order": null,
        "is_sold_out": 0,
        "auto_selected_modifier_items": [],
        "price_levels": [],
        "tax_name": null,
        "tax_value": null,
        "image_path": "",
        "web_image": ""
      }
    ]
  }
}

list_addons

GET /api/products/webProducts. Why: Dashboard view of the tenant's add-ons (products with is_addon = 1): ids, master and branch prices, offer list (type), branch count, channel prices. Use it to find add-on ids for get_addon → update_addon / archive_product / delete_addon. Catalog management tool — what the POS offers on a cart line is list_selling_addons. Parent products: list_products / list_selling_products; `type` holds category names from list_categories / list_selling_categories; loc takes list_locations ids; channel_id takes list_channels ids. Per-branch availability and modifier/recipe links are NOT here — call get_addon. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_addons"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_addons"
}'

Example Response

{
  "data": [
    {
      "id": 257559,
      "category_id": null,
      "name": "Classic Sandwich",
      "description": "",
      "price": 100,
      "stock": 0,
      "type": "Alternate Options,Brewed Coffee,Espresso-Based Drinks,Iced & Cold Coffees,Specialty & Flavored Coffees",
      "image": "",
      "customer_id": 437,
      "location_id": 907,
      "is_addon": 1,
      "addons": "[]",
      "bundle_items": "[]",
      "is_disabled": 0,
      "discount_pct": 0,
      "modifiers": null,
      "is_archive": 0,
      "barcode_type": "",
      "barcode_value": "",
      "is_open_price": 0,
      "is_combo": 0,
      "sync_deliverect": 0,
      "sync_otter": 0,
      "new_cost_date": null,
      "product_cost": 0,
      "is_weightage_item": 0,
      "unit_id": null,
      "actual_price": 100,
      "old_price": null,
      "vat": 5,
      "localized": null,
      "base_price": null,
      "menu_sort_order": 0,
      "plu": 0,
      "calories": null,
      "is_stock_product": null,
      "is_auto_apply": null,
      "combo_price": 0,
      "localize_name": "",
      "localize_description": "",
      "label_id": null,
      "recipes": null,
      "sku_no": "prod-437-257559",
      "tax_id": null,
      "preparation_time": 0,
      "product_recipe_total": 0,
      "product_material_total": 0,
      "is_overridden": 0,
      "is_deleted": 0,
      "category_sort_order": null,
      "override_location_id": 907,
      "override_name": "Classic Sandwich",
      "override_description": "",
      "override_price": 95,
      "override_actual_price": 100,
      "image_path": "",
      "web_image": "",
      "channel_price": [],
      "nameChannels": {
        "channels": []
      },
      "total_locations": 4,
      "has_recipe": 0
    }
  ],
  "total": 7
}

get_addon

GET /api/products/:id. Why: Load one add-on with everything update_addon needs: master prices, offer list (type), image path, per-branch price and availability (location_prices) and modifier/recipe/channel links. Call it before every update_addon (update rewrites the whole record). Takes an id from list_addons. Catalog management tool — what a branch's POS offers is list_selling_addons; branch ids/names come from list_locations, channel ids from list_channels. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_addon"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_addon",
  "id": 11
}'

Example Response

[
  {
    "id": 257559,
    "category_id": null,
    "name": "Classic Sandwich",
    "description": "",
    "price": 95,
    "stock": 0,
    "type": "Alternate Options,Brewed Coffee,Espresso-Based Drinks,Iced & Cold Coffees,Specialty & Flavored Coffees",
    "image": "",
    "customer_id": 437,
    "location_id": [
      908,
      907,
      910,
      1131
    ],
    "is_addon": 1,
    "addons": [],
    "bundle_items": [],
    "is_disabled": 0,
    "discount_pct": 0,
    "modifiers": [],
    "is_archive": 0,
    "barcode_type": "",
    "barcode_value": "",
    "is_open_price": 0,
    "is_combo": 0,
    "sync_deliverect": 0,
    "sync_otter": 0,
    "new_cost_date": null,
    "product_cost": 0,
    "is_weightage_item": 0,
    "unit_id": null,
    "actual_price": 100,
    "old_price": null,
    "vat": 5,
    "localized": null,
    "base_price": null,
    "menu_sort_order": 0,
    "plu": 0,
    "calories": null,
    "is_stock_product": null,
    "is_auto_apply": null,
    "combo_price": 0,
    "localize_name": "",
    "localize_description": "",
    "label_id": null,
    "recipes": [],
    "sku_no": "prod-437-257559",
    "tax_id": null,
    "preparation_time": 0,
    "product_recipe_total": 0,
    "product_material_total": 0,
    "is_overridden": 0,
    "is_deleted": 0,
    "category_sort_order": null,
    "image_path": "",
    "web_image": "",
    "channel_price": [],
    "materials": [],
    "location_prices": [
      {
        "location_id": 908,
        "location_name": "Johar Town",
        "location_price": null,
        "location_actual_price": 100,
        "is_available": true
      },
      {
        "location_id": 907,
        "location_name": "Default location",
        "location_price": 95,
        "location_actual_price": 100,
        "is_available": true
      },
      {
        "location_id": 910,
        "location_name": "Bahira Town",
        "location_price": 95,
        "location_actual_price": 100,
        "is_available": true
      },
      {
        "location_id": 1131,
        "location_name": "Test",
        "location_price": 95,
        "location_actual_price": 100,
        "is_available": true
      }
    ]
  }
]

list_labels

GET /api/label. Why: Every product label of the tenant with its branch list — the dashboard Products → Labels page and the source of label_id for create_product / update_product, the list_products label_id filter and the labels shown on sold lines (sync_invoice / list_orders_history items[].label_id). Search by name with k, filter by branch with loc (ids from list_locations). Get ids here for get_label / update_label / delete_label. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_labels"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_labels"
}'

Example Response

{
  "data": [
    {
      "id": 50,
      "name": "Coffee Seeds",
      "description": "",
      "customer_id": 437,
      "location_id": [
        907,
        908,
        909,
        910,
        922,
        1131
      ]
    },
    {
      "id": 51,
      "name": "Coffee beans",
      "description": "",
      "customer_id": 437,
      "location_id": [
        907,
        909,
        908,
        910,
        922,
        1131
      ]
    },
    {
      "id": 53,
      "name": "Chai seeds",
      "description": "",
      "customer_id": 437,
      "location_id": [
        907,
        908,
        909,
        922,
        910,
        1131
      ]
    },
    {
      "id": 60,
      "name": "Garments",
      "description": "",
      "customer_id": 437,
      "location_id": [
        922,
        907,
        908,
        909,
        910,
        1131
      ]
    }
  ]
}

get_label

GET /api/label/:id. Why: One label with its branch list, to confirm a create_label / update_label or read the full record (name, description, location_id) that update_label must resend. Get the id from list_labels (or a product's label_id from list_products / get_product). The products using it: list_products label_id=<id>. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_label"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_label",
  "id": 11
}'

Example Response

{
  "label": {
    "id": 50,
    "name": "Coffee Seeds",
    "description": "",
    "customer_id": 437,
    "location_id": [
      907,
      908,
      909,
      910,
      922,
      1131
    ]
  },
  "message": "Label retrieved successfully"
}

list_deals

GET /api/deals. Why: Dashboard deal list: the tenant's live combos (is_combo 1, not archived/disabled/add-on) with price, branch list, channel prices and BOM cost — the catalog-management view, not the POS menu (list_selling_products shows what a branch sells, with is_combo / categories[] slots / combo_price). Get ids here for get_deal → update_deal / delete_deal. loc takes branch ids from list_locations. Slot ids + max_allowed are only in get_deal. Paginated with _page/_limit (default 10 per page). Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_deals"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_deals"
}'

Example Response

{
  "items": [],
  "total": 0,
  "page": 1,
  "perPage": 10
}

get_deal

GET /api/deals/:id. Why: Full deal record for an edit: branch list, choice slots (categories[] with category_id + max_allowed — the same slots list_selling_products gives the POS), channel prices and image. Always call it before update_deal and resend its values (update_deal overwrites every column). Slot category ids resolve with list_categories / list_selling_categories; channel ids with list_channels; branch ids with list_locations. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_deal"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_deal",
  "id": 11
}'

Example Response

"No records found"

list_channels

GET /api/channels. Why: Dashboard list of the tenant's sales channels with their branch assignments (location_id), description and sku_no. Use it to find a channel id before get/update/delete, or to see which branches a channel is sold on. For what the POS offers at one branch use list_selling_channels. Linkage: a channel id is referenced by list_selling_products data.products[].price_levels[].channel_id (per-channel price, product_channel_price), by orders (channel_id + channel_name, stored verbatim by sync_invoice — web-pos sends 0/""), and by discount codes channel_ids (list_discounts / get_user_extras data.discount_code[]). Branch availability lives in channels_locations (location_id in these tools); master channels have channels.location_id NULL. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_channels"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_channels"
}'

Example Response

[
  {
    "id": 463,
    "name": "Coffee Bar",
    "description": "",
    "customer_id": 437,
    "sku_no": "chn-437-463",
    "location_id": [
      1131,
      910,
      922,
      907,
      908,
      909
    ]
  },
  {
    "id": 509,
    "name": "Express",
    "description": "",
    "customer_id": 437,
    "sku_no": "chn-437-509",
    "location_id": 907
  }
]

get_channel

GET /api/channels/:id. Why: Load one channel (name, description, branches) — call it before update_channel, which fully replaces name, description and branch list. Linkage: a channel id is referenced by list_selling_products data.products[].price_levels[].channel_id (per-channel price, product_channel_price), by orders (channel_id + channel_name, stored verbatim by sync_invoice — web-pos sends 0/""), and by discount codes channel_ids (list_discounts / get_user_extras data.discount_code[]). Branch availability lives in channels_locations (location_id in these tools); master channels have channels.location_id NULL. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_channel"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_channel",
  "id": 11
}'

Example Response

{
  "id": 463,
  "name": "Coffee Bar",
  "description": "",
  "customer_id": 437,
  "sku_no": "chn-437-463",
  "location_id": [
    909,
    908,
    907,
    922,
    910,
    1131
  ]
}

list_menus

GET /api/menus. Why: List the tenant's named menus (dashboard Products → Menus) with their branches, brand, routing label and Active status, to get ids for get_menu / update_menu / delete_menu. Menus are dashboard records only: nothing else in SysPOS reads them today. The POS (web-pos) never calls /menus, list_selling_products / list_selling_categories do not look at menus, and the aggregator syncs (Deliverect, Grubtech, Otter, LimeTray) build their menus from categories (sync_* flags, list_categories) and products, not from these menus. Adding or removing a product here does not change what a branch sells; for that use update_product (location_prices) or the category tools. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_menus"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_menus"
}'

Example Response

{
  "success": true,
  "data": [
    {
      "id": 4,
      "name": "classic menu",
      "description": "",
      "currency": "AED",
      "customer_id": 437,
      "location_id": [
        907,
        910,
        922,
        909,
        908
      ],
      "is_active": 1,
      "brand_id": 414,
      "label_id": 51,
      "tax_id": 16,
      "brand_name": null,
      "label_name": "Coffee beans",
      "tax_name": "Food Card Tax",
      "tax_rate": 5
    }
  ]
}

get_menu

GET /api/menus/:id. Why: Load one menu with its categories, branches and products — the dashboard View and Edit pages. Call it before update_menu (the update overwrites every field) and to see which products/categories a menu contains. Menus are dashboard records only: nothing else in SysPOS reads them today. The POS (web-pos) never calls /menus, list_selling_products / list_selling_categories do not look at menus, and the aggregator syncs (Deliverect, Grubtech, Otter, LimeTray) build their menus from categories (sync_* flags, list_categories) and products, not from these menus. Adding or removing a product here does not change what a branch sells; for that use update_product (location_prices) or the category tools. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_menu"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_menu",
  "id": 11
}'

Example Response

{
  "success": true,
  "data": {
    "id": 4,
    "name": "classic menu",
    "description": "",
    "currency": "AED",
    "customer_id": 437,
    "location_id": [
      907,
      910,
      922,
      909,
      908
    ],
    "is_active": 1,
    "brand_id": 414,
    "label_id": 51,
    "tax_id": 16,
    "brand_name": null,
    "label_name": "Coffee beans",
    "tax_name": "Food Card Tax",
    "tax_rate": 5,
    "categories": [
      {
        "id": 4,
        "menu_id": 4,
        "category_id": 15481,
        "category_name": "Alternate Options",
        "category_description": null
      }
    ],
    "products": [
      {
        "id": 8,
        "name": "Chai",
        "actual_price": 13,
        "product_id": 247653,
        "customer_id": 437,
        "location_id": null,
        "menu_id": 4,
        "category_id": 15481,
        "product_name": null,
        "product_description": null,
        "product_image": null,
        "category_name": "Alternate Options"
      }
    ],
    "locations": [
      {
        "id": 34,
        "menu_id": 4,
        "location_id": 907,
        "customer_id": 437,
        "location_name": "Default location"
      },
      {
        "id": 51,
        "menu_id": 4,
        "location_id": 910,
        "customer_id": 437,
        "location_name": "Bahira Town"
      },
      {
        "id": 52,
        "menu_id": 4,
        "location_id": 922,
        "customer_id": 437,
        "location_name": "Park View City"
      },
      {
        "id": 53,
        "menu_id": 4,
        "location_id": 909,
        "customer_id": 437,
        "location_name": "Iqbal Town"
      },
      {
        "id": 54,
        "menu_id": 4,
        "location_id": 908,
        "customer_id": 437,
        "location_name": "Johar Town"
      }
    ]
  }
}

list_selling_coupons

GET /api/v2/coupons. Why: Coupon list exactly as web-pos loads it into its local coupon cache when the Coupon dialog opens. Look the typed/scanned code up here FIRST (case-insensitive exact match on code): it tells you whether the coupon is product-scoped (product_ids non-empty → send product_ids to validate_coupon) or basket-wide (send order_total), and gives discount_type / discount_value to compute the discount — validate_coupon does not return an amount. Then ALWAYS call validate_coupon before applying. Not paginated. Product ids = list_selling_products data.products[].id; customer = list_pos_crm_users. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_selling_coupons"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_selling_coupons"
}'

Example Response

{
  "status": true,
  "message": "All coupons retrieved successfully.",
  "data": [
    {
      "id": 987,
      "customer_id": 437,
      "location_id": null,
      "code": "MASTER50",
      "description": "MASTER50",
      "discount_type": "value",
      "discount_value": 10,
      "min_order_value": 10,
      "start_date": "2026-04-01T00:00:00.000Z",
      "end_date": "2026-04-30T00:00:00.000Z",
      "usage_limit": 10,
      "per_user_limit": 2,
      "is_active": 1,
      "created_at": "2026-04-01T06:56:40.000Z",
      "updated_at": "2026-04-01T06:56:40.000Z",
      "current_usage": 0,
      "location_ids": [],
      "product_ids": [],
      "category_ids": []
    }
  ]
}

list_coupons

GET /api/coupons. Why: Dashboard coupon list with branch, product and category links — ids for get_coupon / update_coupon / delete_coupon. Same handler and same response as list_selling_coupons. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_coupons"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_coupons"
}'

Example Response

{
  "status": true,
  "message": "All coupons retrieved successfully.",
  "data": [
    {
      "id": 987,
      "customer_id": 437,
      "location_id": null,
      "code": "MASTER50",
      "description": "MASTER50",
      "discount_type": "value",
      "discount_value": 10,
      "min_order_value": 10,
      "start_date": "2026-04-01T00:00:00.000Z",
      "end_date": "2026-04-30T00:00:00.000Z",
      "usage_limit": 10,
      "per_user_limit": 2,
      "is_active": 1,
      "created_at": "2026-04-01T06:56:40.000Z",
      "updated_at": "2026-04-01T06:56:40.000Z",
      "current_usage": 0,
      "location_ids": [],
      "product_ids": [],
      "category_ids": []
    }
  ]
}

get_coupon

GET /api/coupons/:id. Why: Load one coupon with its branch, product and category links — read it before update_coupon (update replaces links). Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_coupon"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_coupon",
  "id": 11
}'

Example Response

{
  "status": true,
  "message": "Coupon by id retrieved successfully.",
  "data": {
    "id": 987,
    "customer_id": 437,
    "location_id": null,
    "code": "MASTER50",
    "description": "MASTER50",
    "discount_type": "value",
    "discount_value": 10,
    "min_order_value": 10,
    "start_date": "2026-04-01T00:00:00.000Z",
    "end_date": "2026-04-30T00:00:00.000Z",
    "usage_limit": 10,
    "per_user_limit": 2,
    "is_active": 1,
    "created_at": "2026-04-01T06:56:40.000Z",
    "updated_at": "2026-04-01T06:56:40.000Z",
    "current_usage": 0,
    "product_ids": [],
    "category_ids": [],
    "location_ids": []
  }
}

list_coupon_products_by_locations

GET /api/coupons/products-by-locations. Why: Product picker for create_coupon / update_coupon product_ids: live (not archived, not disabled) products linked to ANY of the given branches, sorted by name. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_coupon_products_by_locations"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_coupon_products_by_locations"
}'

Example Response

{
  "success": true,
  "data": [
    {
      "id": 270965,
      "name": "(1) Cold Brew"
    },
    {
      "id": 270946,
      "name": "(A) RADAR EV PATH REPL LENS CLEAR"
    },
    {
      "id": 270966,
      "name": "*Ice Cola"
    }
  ],
  "total": 1075,
  "page": 1,
  "limit": 3
}

list_coupon_categories_by_locations

GET /api/coupons/categories-by-locations. Why: Category picker for create_coupon / update_coupon category_ids: active categories linked to ANY of the given branches, sorted by name. Note category links are not enforced at checkout. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_coupon_categories_by_locations"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_coupon_categories_by_locations"
}'

Example Response

{
  "success": true,
  "data": [
    {
      "id": 15481,
      "name": "Alternate Options"
    },
    {
      "id": 17556,
      "name": "Bag Accessory"
    },
    {
      "id": 15230,
      "name": "Brewed Coffee"
    }
  ],
  "total": 24,
  "page": 1,
  "limit": 3
}

list_discounts

GET /api/discounts/web. Why: Every discount (discount code) of the tenant linked to the given branches — the dashboard Discounts page. These are the rows web-pos gets as get_user_extras data.discount_code[] (active and in date only) and offers in its discount dialog; they are NOT coupons (list_selling_coupons / validate_coupon). Use it to find a discount id for update_discount / delete_discount — also instead of get_discount, which is broken. Scope ids: products list_selling_products, categories list_selling_categories, channels list_selling_channels, payment methods list_selling_payment_methods, order types list_order_types, branches list_locations. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_discounts"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_discounts"
}'

Example Response

{
  "status": true,
  "message": "All discounts retrieved successfully.",
  "data": [
    {
      "id": 2376,
      "name": "Method Test",
      "discount_percent": 50,
      "max_cap_amount": 100,
      "min_basket_value": 20,
      "location_id": [
        907,
        908,
        909,
        922
      ],
      "is_active": 1,
      "start_date": "2026-03-01T00:00:00.000Z",
      "end_date": "2026-03-31T00:00:00.000Z",
      "discount_type": 0,
      "category_ids": "15481,15230",
      "apply_discount_to": "category",
      "product_ids": null,
      "start_time": "00:00:00",
      "end_time": "23:59:00",
      "is_available_on": "monday,tuesday,wednesday,thursday,friday,saturday,sunday",
      "is_auto_apply": 1,
      "is_promotion": 0,
      "payment_methods": null,
      "channel_ids": "463,509,482,515",
      "customer_id": 437,
      "order_type_ids": "1139,1174,1129,1127",
      "discount_method": "percentage",
      "discount_value": 50,
      "linked_location_id": 907,
      "location_name": "Default location"
    }
  ]
}

get_discount

GET /api/discounts/:id. Why: Meant to load one discount by id, but the server handler is broken: it reads the id from a route param that does not exist and ALWAYS answers 400 "Please enter valid discount id". Use list_discounts (loc="All") and pick the row by id instead — that is also what the dashboard does before an edit. BROKEN on the server: always returns 400 "Please enter valid discount id" — use list_discounts (loc="All") and pick the row by id. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_discount"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_discount",
  "id": 11
}'

Example Response

{
  "status": false,
  "message": "Please enter valid discount id",
  "data": null
}

list_selling_payment_methods

GET /api/v2/payment-methods. Why: Tenders the branch can take (Cash, Card, Wallet…) — what web-pos loads for checkout, change-payment and refund. The method NAME is the identity: it is the key in the order's payment_method list, e.g. [{ "CASH": 30 }]. Not paginated. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_selling_payment_methods"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_selling_payment_methods"
}'

Example Response

[
  {
    "id": 1632,
    "name": "card",
    "is_enable": 1,
    "priority": 0,
    "type": "cash",
    "customer_id": 437,
    "location_id": 907,
    "sync_locations": 1
  },
  {
    "id": 2135,
    "name": "Wallet",
    "is_enable": 1,
    "priority": 0,
    "type": "wallet",
    "customer_id": 437,
    "location_id": 907,
    "sync_locations": 1
  }
]

list_payment_methods

GET /api/payment-methods. Why: Dashboard management list of tender types (Cash, Card, Wallet …) with the branches each is linked to — use it for ids (get/update/delete_payment_method), to audit which branches accept which methods, and to find methods linked to no branch. Not the POS selling view: web-pos reads GET /api/v2/payment-methods (list_selling_payment_methods), which defaults to the cashier's branch. Linkage: the payment method NAME is the key in an invoice's payment_method[] (e.g. [{"cash": 30}]) and is matched case-insensitively against the methods linked to the invoice's branch — so renaming or deleting a method changes what the POS can settle with. Branch availability lives in payment_methods_locations (location_id[] in these tools); on master tenants payment_methods.location_id is NULL. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_payment_methods"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_payment_methods"
}'

Example Response

[
  {
    "id": 1632,
    "name": "card",
    "is_enable": 1,
    "priority": 0,
    "type": "cash",
    "customer_id": 437,
    "location_id": 907,
    "sync_locations": 1
  },
  {
    "id": 2135,
    "name": "Wallet",
    "is_enable": 1,
    "priority": 0,
    "type": "wallet",
    "customer_id": 437,
    "location_id": 907,
    "sync_locations": 1
  }
]

get_payment_method

GET /api/payment-methods/:id. Why: Load one payment method with its full branch list before update_payment_method (update is a full replace — resend is_enable, priority, type, sync_locations and the complete location_id list). Linkage: the payment method NAME is the key in an invoice's payment_method[] (e.g. [{"cash": 30}]) and is matched case-insensitively against the methods linked to the invoice's branch — so renaming or deleting a method changes what the POS can settle with. Branch availability lives in payment_methods_locations (location_id[] in these tools); on master tenants payment_methods.location_id is NULL. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_payment_method"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_payment_method",
  "id": 11
}'

Example Response

[
  {
    "id": 2135,
    "name": "Wallet",
    "customer_id": 437,
    "location_id": [
      907,
      908,
      909,
      910,
      922,
      1100,
      1101,
      1102,
      1117,
      1131
    ],
    "is_enable": 1,
    "priority": 0,
    "type": "wallet",
    "sync_locations": 1
  }
]

list_selling_order_types

GET /api/v2/order-types. Why: Order types (Dine-in, Takeaway, Delivery, Drive-thru…) the POS offers — what web-pos loads for the order-type chips and checkout step 1. The chosen type's TITLE (a free-text string) is what goes on the order as order_type; nothing uses the id or code. Tenant-wide list (not per branch). Not paginated. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_selling_order_types"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_selling_order_types"
}'

Example Response

{
  "status": true,
  "message": "data found",
  "data": [
    {
      "id": 1139,
      "title": "delivery",
      "icon_key": "carbon:delivery",
      "icon_url": "https://images.weserv.nl/?url=https%3A%2F%2Fapi.iconify.design%2Fcarbon%2Fdelivery.svg%3Fwidth%3D128%26height%3D128&output=png",
      "order_type_code": "DELIVERY",
      "is_system_default": 1
    },
    {
      "id": 1174,
      "title": "dine-in",
      "icon_key": "boxicons:fork-knife",
      "icon_url": "https://images.weserv.nl/?url=https%3A%2F%2Fapi.iconify.design%2Fboxicons%2Ffork-knife.svg%3Fwidth%3D128%26height%3D128&output=png",
      "order_type_code": "DINE_IN",
      "is_system_default": 1
    },
    {
      "id": 1129,
      "title": "drive-thru",
      "icon_key": "ic:baseline-drive-eta",
      "icon_url": "https://images.weserv.nl/?url=https%3A%2F%2Fapi.iconify.design%2Fic%2Fbaseline-drive-eta.svg%3Fwidth%3D128%26height%3D128&output=png",
      "order_type_code": "DRIVE_THRU",
      "is_system_default": 1
    },
    {
      "id": 1127,
      "title": "takeaway",
      "icon_key": "boxicons:takeaway",
      "icon_url": "https://images.weserv.nl/?url=https%3A%2F%2Fapi.iconify.design%2Fboxicons%2Ftakeaway.svg%3Fwidth%3D128%26height%3D128&output=png",
      "order_type_code": "TAKEAWAY",
      "is_system_default": 1
    }
  ]
}

list_order_types

GET /api/order-type. Why: Dashboard management list of the tenant's order types (dine-in, takeaway, delivery, drive-thru and custom ones) — use it to get ids for update_order_type / delete_order_type, check whether a name exists before create_order_type, and see which rows are protected system defaults. Not the POS selling view: web-pos reads GET /api/v2/order-types (list_selling_order_types), which returns the same rows as `title` plus a rendered icon_url. Order types are tenant-wide (order_type.customer_id) — NOT per branch; every branch sees the same list and there is no loc filter. The order type NAME (order_type here, `title` in GET /api/v2/order-types) is the string stored in an invoice's order_type; order_type_code is the fixed behaviour (DINE_IN / TAKEAWAY / DELIVERY / DRIVE_THRU) the POS uses to decide table/driver/address flow. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_order_types"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

No additional parameters — only the Authorization: Bearer header is required.

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_order_types"
}'

Example Response

{
  "success": true,
  "data": [
    {
      "id": 1139,
      "order_type": "delivery",
      "order_type_code": "DELIVERY",
      "is_system_default": 1,
      "customer_id": 437,
      "icon_key": "carbon:delivery"
    },
    {
      "id": 1174,
      "order_type": "dine-in",
      "order_type_code": "DINE_IN",
      "is_system_default": 1,
      "customer_id": 437,
      "icon_key": "boxicons:fork-knife"
    }
  ]
}

list_order_type_codes

GET /api/order-type/codes. Why: The fixed set of behaviour codes accepted by create_order_type.order_type_code (DINE_IN, DRIVE_THRU, TAKEAWAY, DELIVERY). Call before creating a custom order type (e.g. "Talabat" with code DELIVERY) to pick its behaviour. Static list — same for every tenant. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_order_type_codes"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

No additional parameters — only the Authorization: Bearer header is required.

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_order_type_codes"
}'

Example Response

{
  "success": true,
  "data": [
    {
      "code": "DINE_IN",
      "default_label": "Dine-in"
    },
    {
      "code": "DRIVE_THRU",
      "default_label": "Drive-thru"
    },
    {
      "code": "TAKEAWAY",
      "default_label": "Takeaway"
    },
    {
      "code": "DELIVERY",
      "default_label": "Delivery"
    }
  ]
}

list_kds_orders

GET /api/v2/kds-orders. Why: The kitchen board — what web-pos's KDS screen polls every 4 s: today's orders of the session branch that are not bumped and not cancelled, each with its lines (is_prepared = ticked) and accept state (is_accepted). Use it to see what the kitchen still has to make, per station (c = category name), and to get uuid / order_items[].id for the three KDS write tools. is_order_rebump=1 returns the bumped orders instead (recall list). Not paginated. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_kds_orders"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_kds_orders"
}'

Example Response

[
  {
    "id": "a0b1c2d3e4f5",
    "oid": 57,
    "order_no": 57,
    "customer_invoice_id": 10433,
    "token_number": null,
    "is_accepted": 1,
    "external_order_ready": 0,
    "exchange_rate": null,
    "is_wastage": 0,
    "paid_in_usd": null,
    "is_discount_on_total": 0,
    "items_number": 2,
    "aggregator_order_id": null,
    "subtotal": 48,
    "vat": 0,
    "channel_id": 0,
    "payable": 48,
    "discountamount": 0,
    "items_discount_amount": 0,
    "is_ticket_available": 0,
    "is_wallet_used": 0,
    "discountpct": 0,
    "paid": 0,
    "change": 0,
    "note": "Guest allergic to sesame",
    "uuid": "c1d2e3f4-5a6b-4c7d-8e9f-a0b1c2d3e4f5",
    "created_at": 1790227800,
    "updated_at": 1790227890,
    "customer_id": 437,
    "location_id": 907,
    "row_discount": 0,
    "order_notes": null,
    "info_name": null,
    "info_address": null,
    "info_phone": null,
    "info_email": null,
    "status": "open",
    "by": "web-pos",
    "external_order_id": null,
    "burn_points": 0,
    "earn_points": 0,
    "burn_points_amount": 0,
    "available_points": 0,
    "available_points_amount": 0,
    "charges_fee": 0,
    "delivery_charges": 0,
    "phone_number": "",
    "loyalty_mobile_number": "",
    "loyalty_mobile_code": "",
    "crm_delivery_area": null,
    "user": "cashier@example.com",
    "table_id": 1204,
    "plate_number": null,
    "is_vat_on_discount_exclude": 0,
    "created_by_user_id": 3101,
    "close_by_user_id": null,
    "modified_by_user_ids": [],
    "crm_user_id": 0,
    "crm_user_name": "",
    "order_type": "Dine In",
    "tip_amount": 0,
    "brand_id": null,
    "dining_guests": 2,
    "channel_name": "",
    "discount_reason": null,
    "paid_at": null,
    "coupon_amount": 0,
    "coupon_id": 0,
    "coupon_code": null,
    "printed_invoice_receipts": 0,
    "printed_kds_receipts": 0,
    "app_version": null,
    "app_os_version": null,
    "build_number": null,
    "os_type": null,
    "round": 1,
    "rider_pickup_at": null,
    "rider_arrived_at": null,
    "order_type_icon_key": "mdi:silverware-fork-knife",
    "notes": [],
    "payment_method": null,
    "payment_methods": null,
    "payments": null,
    "order_items": [
      {
        "id": 1583204,
        "identifier": "8f7c2a10-3b1e-4c55-9a7e-0d4b6f1e2a31",
        "name": "Chicken Shawarma",
        "name_localize": null,
        "actual_price": 18,
        "base_price": 18,
        "price": 18,
        "is_weightage_item": 0,
        "unit_id": null,
        "qty": 2,
        "subtotal": 36,
        "line_total": null,
        "line_vat": null,
        "line_total_without_vat": null,
        "invoice_uuid": "c1d2e3f4-5a6b-4c7d-8e9f-a0b1c2d3e4f5",
        "product_id": 52110,
        "extras": null,
        "vat": 0,
        "is_updated": 0,
        "updated_qty": 0,
        "is_addon": 0,
        "is_refunded": 0,
        "refund_quantity": 0,
        "refund_reason": null,
        "note": "no pickles",
        "addon_linked_with": null,
        "discount_pct": 0,
        "discount_amount": 0,
        "modifier": [
          {
            "id": 881,
            "name": "Spicy",
            "price": 0,
            "qty": 1
          }
        ],
        "transferred_to": 0,
        "transferred_to_uuid": null,
        "transferred_to_uuid_list": [],
        "transferred_quantities": [],
        "transfer_recipients": [],
        "created_at": 1790227800,
        "updated_at": 1790227800,
        "is_prepared": null,
        "preparation_time": 0,
        "type": "Hot Kitchen",
        "label_id": null,
        "is_combo": 0,
        "is_deleted": 0,
        "deleted_at": null,
        "deleted_qty": null,
        "coupon_amount": 0,
        "coupon_id": 0,
        "coupon_code": null,
        "updated_by_user_ids": [],
        "re": null,
        "ri": null,
        "is_wastage": null,
        "discount_id": null,
        "discount_name": null,
        "round": 1,
        "combo_items": null
      },
      {
        "id": 1583205,
        "identifier": "2b9e5d71-6c0a-4f18-b3d2-7e1a9c4f8d02",
        "name": "Mint Lemonade",
        "name_localize": null,
        "actual_price": 12,
        "base_price": 12,
        "price": 12,
        "is_weightage_item": 0,
        "unit_id": null,
        "qty": 1,
        "subtotal": 12,
        "line_total": null,
        "line_vat": null,
        "line_total_without_vat": null,
        "invoice_uuid": "c1d2e3f4-5a6b-4c7d-8e9f-a0b1c2d3e4f5",
        "product_id": 52187,
        "extras": null,
        "vat": 0,
        "is_updated": 0,
        "updated_qty": 0,
        "is_addon": 0,
        "is_refunded": 0,
        "refund_quantity": 0,
        "refund_reason": null,
        "note": null,
        "addon_linked_with": null,
        "discount_pct": 0,
        "discount_amount": 0,
        "modifier": [],
        "transferred_to": 0,
        "transferred_to_uuid": null,
        "transferred_to_uuid_list": [],
        "transferred_quantities": [],
        "transfer_recipients": [],
        "created_at": 1790227800,
        "updated_at": 1790227890,
        "is_prepared": 1,
        "preparation_time": 0,
        "type": "Beverages",
        "label_id": null,
        "is_combo": 0,
        "is_deleted": 0,
        "deleted_at": null,
        "deleted_qty": null,
        "coupon_amount": 0,
        "coupon_id": 0,
        "coupon_code": null,
        "updated_by_user_ids": [],
        "re": null,
        "ri": null,
        "is_wastage": null,
        "discount_id": null,
        "discount_name": null,
        "round": 1,
        "combo_items": null
      }
    ],
    "order_type_icon": null
  }
]

list_sold_out_products

GET /api/v2/products/sold-out. Why: Ids of the products switched to sold out at the branch (products_locations.is_sold_out = 1, set by update_product_availability). web-pos polls it every 60 s (and listens on Firestore) to grey out tiles. It is the same flag as is_sold_out on list_selling_products, but cheaper to refresh. It does NOT include products whose quota is used up (see list_product_quota). Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_sold_out_products"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_sold_out_products"
}'

Example Response

{
  "status": true,
  "message": "Sold out products fetched",
  "data": []
}

list_product_quota

GET /api/v2/user-product-quota. Why: Product quotas of the branch: for each product with a quota, how many units may be sold (total_quota), how many were sold (sold_count) and what is left (remaining_stock). web-pos loads it to show 'N left' on tiles, to block adding more than remaining_stock to a cart, and on the Product Sold Counter page. A quota is per product per branch (not per user, despite the route name). Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_product_quota"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_product_quota"
}'

Example Response

{
  "status": true,
  "message": "All product quotas retrieved successfully",
  "data": [
    {
      "counter_id": null,
      "assignment_id": 4,
      "product_id": 257497,
      "product_name": "Espresso",
      "total_quota": 10,
      "sold_count": 0,
      "remaining_stock": 10,
      "history": []
    },
    {
      "counter_id": null,
      "assignment_id": 5,
      "product_id": 257499,
      "product_name": "Caramel Latte",
      "total_quota": 10,
      "sold_count": 0,
      "remaining_stock": 10,
      "history": []
    },
    {
      "counter_id": 15848,
      "assignment_id": 25,
      "product_id": 257508,
      "product_name": "Mocha",
      "total_quota": 20,
      "sold_count": 7,
      "remaining_stock": 13,
      "history": [
        {
          "id": 27,
          "quantity": -1,
          "invoice_id": 0,
          "counter_id": 15848,
          "identifier": "58556941-8651-4fbe-a683-8bf32143dfe7",
          "order_uuid": "b7b056e0-3c5f-437d-9258-968b6cc34a6e",
          "product_id": 257508,
          "created_at": 1787738590
        }
      ]
    }
  ]
}

get_active_shift

GET /api/v2/shifts/active. Why: Get the active shift for this device/user. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_active_shift"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

No additional parameters — only the Authorization: Bearer header is required.

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_active_shift"
}'

Example Response

{
  "id": 1,
  "status": "open"
}

list_shifts

GET /api/v2/shifts. Why: List shifts. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_shifts"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_shifts"
}'

Example Response

[
  {
    "id": 1
  }
]

list_drawer_categories

GET /api/v2/shifts/drawer-categories. Why: Cash in/out category list. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_drawer_categories"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

No additional parameters — only the Authorization: Bearer header is required.

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_drawer_categories"
}'

Example Response

[
  {
    "id": 1,
    "name": "Petty cash"
  }
]

list_drawer_transactions

GET /api/v2/shifts/drawer-transactions. Why: List cash drawer transactions for the shift. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_drawer_transactions"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_drawer_transactions"
}'

Example Response

[
  {
    "id": 1,
    "amount": 10
  }
]

get_tills_summary

GET /api/v2/shifts/tills-summary. Why: Per-user tills summary for a shift. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_tills_summary"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_tills_summary"
}'

Example Response

[
  {
    "user_id": 1,
    "total": 100
  }
]

get_ol_info

GET /api/v2/ol-info. Why: Last order of the branch's CURRENT business day (its daily order_no and running receipt number customer_invoice_id) plus that day's UTC window. web-pos caches it at boot but reads nothing from it. Use it to see the last numbers before/after sync_invoice (the server assigns both) or the UTC bounds of 'today'. Hours/time zone come from get_pos_configs. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_ol_info"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_ol_info"
}'

Example Response

{
  "id": 0,
  "invoice_id": 0,
  "order_id": 0,
  "username": "cashier@example.com",
  "customer_id": 437,
  "location_id": 907,
  "fromDate": "2026-09-24 05:00:00",
  "toDate": "2026-09-25 05:00:00"
}

get_user_extras

GET /api/v2/user-extras-v3. Why: Branch + user configuration web-pos loads at boot: receipt header (name, address, VAT no.), flat VAT %, currency, money decimals, business-day hours, the user's max manual discount %, active discount codes, the void PIN and the ios_modules feature flags (is_loyalty_enable, is_branding_enable, is_activities_enabled). Read it before pricing an order for sync_invoice (VAT fallback, decimal_points) or offering discounts. The per-user POS switches (is_channels_enable, is_soldout, discount_codes, is_change_payment_method_enabled, tip_amount, dining_guest_count, combo_options) are NOT here: they are list_pos_users data[].setting. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_user_extras"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

No additional parameters — only the Authorization: Bearer header is required.

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_user_extras"
}'

Example Response

{
  "status": true,
  "message": "Data found",
  "data": {
    "today_guests": 0,
    "can_preview_invoice": 0,
    "max_discount_permit": 50,
    "discount_code": [
      {
        "id": 101,
        "name": "Happy Hour 10",
        "discount_percent": null,
        "discount_method": "percentage",
        "discount_value": 10,
        "max_cap_amount": 20,
        "min_basket_value": 30,
        "location_id": null,
        "is_active": 1,
        "start_date": "2026-09-01T00:00:00.000Z",
        "end_date": "2026-12-31T00:00:00.000Z",
        "discount_type": 0,
        "category_ids": "",
        "apply_discount_to": "entire_basket",
        "product_ids": "",
        "start_time": "15:00:00",
        "end_time": "18:00:00",
        "is_available_on": "monday,tuesday,wednesday,thursday,friday",
        "is_auto_apply": 0,
        "is_promotion": 0,
        "payment_methods": "",
        "channel_ids": "",
        "customer_id": 437,
        "order_type_ids": ""
      }
    ],
    "opening_hour": "10:00 AM",
    "closing_hour": "08:00 AM",
    "business_logo": "https://dev1.syspos.ae/api/uploads/example-logo.png",
    "business_config": {
      "vat": "5",
      "info_name": "Example Cafe",
      "info_address": "Shop 1, Example Street",
      "info_email": "info@example-cafe.test",
      "vat_no": "100000000000003",
      "info_phone": "+971500000000",
      "legal_name": null,
      "exchange_rate": 12,
      "pincode": 1234,
      "currency": {
        "id": 10103,
        "name": "currency",
        "value": "",
        "customer_id": 437,
        "location_id": 907
      }
    },
    "decimal_points": 0,
    "ios_modules": {
      "is_kds_enable": 1,
      "is_daily_sale_report_enable": 1,
      "is_order_hisotry_screen_enable": 1,
      "is_sms_enable": 1,
      "is_cloud_print_enable": 1,
      "is_user_blocked": 0,
      "is_branding_enable": 1,
      "is_actual_price": 1,
      "is_usd_base": 0,
      "is_dine_in_enable": 1,
      "is_wastage_enable": 1,
      "is_material_stock_enable": 1,
      "is_balance_enable": 1,
      "is_product_scanner_enable": 1,
      "is_bar_scanner_enable": 1,
      "is_devices_enable": 1,
      "is_peer_enable": 1,
      "is_setting_enable": 1,
      "is_loyalty_enable": 1,
      "is_ticket_enabled": 0,
      "is_wallet_enabled": 1,
      "is_location_service_enabled": 1,
      "is_crm_mobile_mandatory": 0,
      "reload_dine_order": 1,
      "order_dispatch_feature": 0,
      "is_activities_enabled": 0
    },
    "tos": "<ul><li>Optional note</li></ul>",
    "tos_links": {},
    "receipt_header": "",
    "receipt_header_links": {},
    "is_shift_enabled": 1,
    "business_day_start": "10:00"
  }
}

get_user_location

GET /api/v2/user-location. Why: The session user's home branch row (locations table): id, name and integration ids. web-pos caches it at boot for the N-Genius card terminal ids. Use it to learn which branch the session sells in (the branch sync_invoice and every list_selling_* tool use). For all branches in the key's scope use list_locations. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_user_location"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

No additional parameters — only the Authorization: Bearer header is required.

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_user_location"
}'

Example Response

[
  {
    "id": 907,
    "name": "Default location",
    "customer_id": 437,
    "is_ware_house": "1",
    "is_primary": null,
    "otter_location_id": null,
    "deliverect_location_id": null,
    "enable_menu_checkout": null,
    "invoice_service_version": "v1",
    "payment_provider": null,
    "ngenius_terminal_id": null,
    "ngenius_merchant_id": null,
    "enable_grubtech": 0,
    "allow_grubtech_status_updates": 0
  }
]

list_pos_users

GET /api/v2/users-list. Why: POS users of the session branch with their POS switches (data[].setting). Use it to pick the cashier ids for sync_invoice (created_by_user_id / close_by_user_id / user email), for get_today_sales close_by_user_id and log_invoice_activities, and to read the per-user feature switches web-pos obeys: is_channels_enable + channel_id (list_selling_channels), is_soldout (update_product_availability), discount_codes (discount codes + list_selling_coupons / validate_coupon), is_change_payment_method_enabled (update_invoice_payment_methods), tip_amount, dining_guest_count, combo_options, pay_zero_amount. The session user's own row = the switches that apply to MCP orders. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_pos_users"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

No additional parameters — only the Authorization: Bearer header is required.

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_pos_users"
}'

Example Response

{
  "status": true,
  "message": "users list",
  "data": [
    {
      "id": 4734,
      "username": "Cashier One",
      "email": "cashier@example.com",
      "pin": "1234",
      "role": "admin",
      "role_id": 31,
      "location_id": 907,
      "thumbnail": "",
      "is_multi_location_allowed": 0,
      "is_master_locations_enabled": 1,
      "shift_z_report": 0,
      "view_estimated_cash": 0,
      "external_order_ready": 0,
      "ios_modules": {
        "is_kds_enable": 1,
        "is_daily_sale_report_enable": 1,
        "is_order_hisotry_screen_enable": 1,
        "is_sms_enable": 1,
        "is_cloud_print_enable": 1,
        "is_user_blocked": 0,
        "is_branding_enable": 1,
        "is_actual_price": 1,
        "is_usd_base": 0,
        "is_dine_in_enable": 1,
        "is_wastage_enable": 1,
        "is_material_stock_enable": 1,
        "is_balance_enable": 1,
        "is_product_scanner_enable": 1,
        "is_bar_scanner_enable": 1,
        "is_devices_enable": 1,
        "is_peer_enable": 1,
        "is_setting_enable": 1,
        "is_loyalty_enable": 1,
        "is_ticket_enabled": 0,
        "is_wallet_enabled": 1,
        "is_location_service_enabled": 1,
        "is_crm_mobile_mandatory": 0,
        "reload_dine_order": 1,
        "order_dispatch_feature": 0
      },
      "device_info": [
        {
          "id": 123,
          "device_id": "device-0001",
          "device_name": "Front iPad",
          "app_os_version": null,
          "app_version": null,
          "build_number": null,
          "user_id": 4734,
          "username": "Cashier One",
          "customer_id": 437,
          "location_id": 907,
          "last_online": "2026-09-18T13:19:53.000Z"
        }
      ],
      "token": "<jwt>",
      "setting": {
        "is_multi_location_allowed": 0,
        "is_master_locations_enabled": 1,
        "print_receipt": 1,
        "print_no_of_times": 1,
        "is_ingredient_disabled": 0,
        "kds_auto_receipt": 1,
        "invoice_auto_receipt": 1,
        "cart_options": 1,
        "print_and_save": 1,
        "cloud_print": 1,
        "quit_printers_with_cloud_enabled": 1,
        "invoice_printer_act_as_kds": 1,
        "cart_note": 1,
        "cart_car_plate": 1,
        "token_number": 1,
        "discount_codes": 1,
        "transfer_order_pincode": 1,
        "daily_sale_input_check": 1,
        "daily_sale_media_check": 1,
        "active_pincode": 1,
        "label_printing": 1,
        "qrcode_on_label_print": 1,
        "is_kds_device": 1,
        "open_drawer": 1,
        "user_card_digits": 1,
        "invoice_qrcode": 1,
        "force_adons": 1,
        "combo_options": 1,
        "ensure_combo_minimum_item_requirement": 1,
        "row_discount": 0,
        "sms_invoice": 0,
        "language": "",
        "zebra_ip": "",
        "zebra_port": 0,
        "offline_order_sync": 0,
        "orderhistory_print_receipt": 0,
        "fraction_digits": 2,
        "brand_id": 0,
        "dining_guest_count": 1,
        "is_brand_groups": 0,
        "is_extras_enble": 0,
        "display_modifier_titles": 0,
        "modifier_sort_min_required_desc": 1,
        "print_only_save_kds_orders": 0,
        "print_note_on_receipt": 0,
        "show_receipt_screen": 0,
        "order_type": 0,
        "open_dine_in": 0,
        "hide_cart_pay_button": 0,
        "delivery_detail_enable": 0,
        "is_attributed_receipt": 0,
        "is_cds_enable": 0,
        "external_order_print_receipt": 0,
        "text_receipt": 0,
        "each_category_kds_print": 0,
        "exchange_format": 0,
        "has_void_order_permission": 0,
        "hide_clear_checkout": 1,
        "kds_instruction": 1,
        "pay_default_usd": 0,
        "rpt_business_logo": 0,
        "rpt_order_type": 0,
        "rpt_is_modified": 0,
        "rpt_biller_info": 0,
        "rpt_total_before_vat": 0,
        "rpt_vat_info": 0,
        "rpt_net_total": 0,
        "rpt_exchange_rate": 0,
        "rpt_dine_guest_count": 0,
        "rpt_paid_at": 0,
        "esc_command": 0,
        "tip_amount": 0,
        "print_void_orders": 0,
        "qr_code_on_print_receipt": 0,
        "is_channels_enable": 0,
        "channel_id": 463,
        "unify_brands": 0,
        "ingredient_stay_standalone": 0,
        "allegy_item": 0,
        "dinein_serving_role": 0,
        "draft_order": 0,
        "is_kds_expeditor": 0,
        "is_qr_payment": 0,
        "pay_zero_amount": 0,
        "print_deleted_item_on_receipt": 0,
        "receipt_format": 0,
        "receipt_translation": 0,
        "product_translation": 0,
        "category_translation": 0,
        "print_invoice_translation": 0,
        "print_kds_translation": 0,
        "reservation_with_dine_in": 0,
        "splitefire": 0,
        "station_id": 0,
        "cloud_target_user_id": 0,
        "cloud_target_device_id": null,
        "one_table_one_order": 0,
        "is_socket_server": 0,
        "is_client": 0,
        "exchange_rate": 12,
        "currency": {
          "id": 10103,
          "name": "currency",
          "value": "",
          "customer_id": 437,
          "location_id": 907
        },
        "web_local_network_printer": 0,
        "open_price_pincode": 0,
        "is_transfer_enabled": 0,
        "block_print_until_order_open": 0,
        "user_product_sales_counter": 0,
        "is_change_payment_method_enabled": 0,
        "skip_zero_quantity_items": 0,
        "skip_zero_amount_items": 0,
        "settle_wallet_topup": 1,
        "is_shift_management": 0,
        "acknowledge_dine_table_edit": 0,
        "lock_screen": 0,
        "is_soldout": 0,
        "force_crm_user": 0,
        "shift_transactions": 0,
        "eod_shift_report": 0,
        "override_shift": 0
      }
    }
  ]
}

list_selling_channels

GET /api/v2/get-channels. Why: Sales channels offered at the cashier's branch — what web-pos loads at boot and shows in Settings → Channel. The channel_id is the key for per-channel product prices (list_selling_products data.products[].price_levels[].channel_id), for discount-code channel scope (channel_ids) and for an order's channel_id/channel_name. Not paginated. Management (description, branches, create/update/delete): list_channels / get_channel in the channels catalog. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_selling_channels"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_selling_channels"
}'

Example Response

{
  "status": true,
  "message": "Channels data found",
  "data": [
    {
      "channel_id": 463,
      "channel_name": "Coffee Bar"
    },
    {
      "channel_id": 509,
      "channel_name": "Express"
    },
    {
      "channel_id": 482,
      "channel_name": "Food Panda"
    }
  ]
}

get_master_data

GET /api/v2/master-data. Why: Raw table dump used by the POS apps for offline sync. Useful rows: table=locations (id + name + integration ids of the branches the session USER may open — web-pos branch picker) and table=user (the session user's discount limit). table=product_materials / materials are for NON-master (inventory-per-branch) tenants and out of scope; table=products is a multi-MB raw dump (use list_selling_products); table=categories is broken. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_master_data"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_master_data",
  "table": "example"
}'

Example Response

[
  {
    "id": 907,
    "name": "Default location",
    "customer_id": 437,
    "is_ware_house": "1",
    "is_primary": null,
    "otter_location_id": null,
    "deliverect_location_id": null,
    "enable_menu_checkout": null,
    "invoice_service_version": "v1",
    "payment_provider": null,
    "ngenius_terminal_id": null,
    "ngenius_merchant_id": null,
    "enable_grubtech": 0,
    "allow_grubtech_status_updates": 0
  },
  {
    "id": 908,
    "name": "Johar Town",
    "customer_id": 437,
    "is_ware_house": "1",
    "is_primary": null,
    "otter_location_id": null,
    "deliverect_location_id": null,
    "enable_menu_checkout": null,
    "invoice_service_version": "v1",
    "payment_provider": null,
    "ngenius_terminal_id": null,
    "ngenius_merchant_id": null,
    "enable_grubtech": 0,
    "allow_grubtech_status_updates": 0
  }
]

get_today_sales

GET /api/v2/today-sales-v3. Why: The web-pos Daily Sales (Z-style) report of one branch and business day: net sales, orders, VAT, tenders, order types, items, discounts, voids, open orders and per-user totals. Business day = opening_hour → next opening_hour in the branch time_zone (get_pos_configs). Filter by cashier with close_by_user_id (list_pos_users). Order-level drill-down: list_orders_history; audit trail: get_invoice_activities. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_today_sales"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_today_sales"
}'

Example Response

{
  "order_type": {
    "Delivery": 2,
    "Takeaway": 1,
    "void_orders": 5,
    "refunded_items": 0
  },
  "dining_guests": 2,
  "item_transferred": 0,
  "items": [
    {
      "type": "Espresso-Based Drinks",
      "name": "Flat White",
      "unit_id": 0,
      "extras": null,
      "is_addon": 0,
      "is_refunded": 0,
      "total": 33,
      "qty": 3,
      "period": "2026-09-24T13:37:06.484Z",
      "list": [],
      "extra": []
    }
  ],
  "addons": [],
  "refund_items": [],
  "modifiers": [],
  "itemsCat": [
    {
      "type": "Espresso-Based Drinks",
      "total": 33
    }
  ],
  "itemsPayment": [
    {
      "payment_method": "cash",
      "total": 22,
      "transactions": 2,
      "tip_amount": 0
    }
  ],
  "totalAmount": 33,
  "total_sales": 33,
  "total_orders": 3,
  "hourly": [
    {
      "hour": 15,
      "value": 11,
      "order_count": 1
    }
  ],
  "time_distribution": [
    {
      "hour": 15,
      "value": 11,
      "order_count": 1
    }
  ],
  "opening_hour": "10:00",
  "time_zone": "+05:00",
  "location_id": 907,
  "wallet_orders": {
    "total_amount": 0,
    "total_count": 0
  },
  "wallet_topups": {
    "transaction_type": "debit",
    "amount": 0,
    "count": 0
  },
  "avg_invoice_bill": 11,
  "avg_per_order": 11,
  "avg_per_guest": 11,
  "total_vat": 1.04,
  "void_orders": {
    "title": "Void orders",
    "no_of_cancelled_order": 5,
    "no_of_canceled_order": 5,
    "no_of_items_refund": 0,
    "total": 424,
    "transaction": [
      {
        "payment_method": "cash",
        "total": 424,
        "transactions": 4
      }
    ]
  },
  "ts": 1790257026487,
  "time": "06:37:06 PM",
  "withdraw_amount": 0,
  "credit_amount": 0,
  "active_shift_id": null,
  "active_shift": null,
  "shift_filter_applied": false,
  "discount_summary": [],
  "invoice_begin": 16,
  "invoice_end": 24,
  "invoices_count": 9,
  "order_types": [
    {
      "name": "Delivery",
      "count": 2,
      "amount": 22
    }
  ],
  "user_statistics": {
    "open_orders": {
      "users": [
        {
          "user": "cashier@example.com",
          "total_amount": 31,
          "order_count": 1,
          "orders": [
            {
              "id": 8085857,
              "uuid": "b7b056e0-3c5f-437d-9258-968b6cc34a6e",
              "payable": 31,
              "created_at": "2026-08-26T10:03:08.000Z",
              "order_type": "Dine In",
              "dining_guests": 2
            }
          ]
        }
      ],
      "total_amount": 31,
      "total_orders": 1
    },
    "completed_orders": {
      "users": [
        {
          "user": "cashier@example.com",
          "total_amount": 33,
          "order_count": 3,
          "orders": [
            {
              "id": 8085852,
              "uuid": "f5bd46f3-377a-477d-b748-876e9aab0063",
              "payable": 11,
              "created_at": "2026-08-20T11:07:42.000Z",
              "order_type": "Delivery",
              "dining_guests": 1
            }
          ]
        }
      ],
      "total_amount": 33,
      "total_orders": 3
    },
    "created_by_users": {
      "users": [
        {
          "user": "cashier@example.com",
          "user_id": "4734",
          "total_amount": 499,
          "order_count": 9,
          "orders": [
            {
              "id": 8085848,
              "uuid": "fdf751c3-f3f8-4cbe-9af0-76fd0d8482c8",
              "payable": 106,
              "created_at": "2026-08-17T06:25:20.000Z",
              "order_type": "takeaway",
              "dining_guests": null
            }
          ]
        }
      ],
      "total_amount": 499,
      "total_orders": 9
    },
    "closed_by_users": {
      "users": [
        {
          "user": "cashier@example.com",
          "user_id": "4734",
          "total_amount": 33,
          "order_count": 3,
          "orders": [
            {
              "id": 8085852,
              "uuid": "f5bd46f3-377a-477d-b748-876e9aab0063",
              "payable": 11,
              "created_at": "2026-08-20T11:07:42.000Z",
              "order_type": "Delivery",
              "dining_guests": 1
            }
          ]
        }
      ],
      "total_amount": 33,
      "total_orders": 3
    }
  },
  "tip_amount": {
    "title": "Tip Amount",
    "total": 0,
    "transactions": 0
  },
  "points": {
    "title": "Points",
    "total": 0,
    "transactions": 0
  },
  "discount_amount": {
    "title": "Discounts",
    "total": 0,
    "transactions": 0
  },
  "unpaid_order": {
    "title": "Unpaid Order",
    "total": 31,
    "transactions": 1
  },
  "pending_orders": [
    {
      "invoice_number": 23,
      "order_type": "Dine In",
      "amount": 31,
      "currency": "AED",
      "created_date": "Aug 26",
      "user": "cashier@example.com"
    }
  ],
  "late_closure": [],
  "total_without_vat": 31.96,
  "total_payable": 33,
  "gross_sales": 33,
  "order_charges": {
    "charges_fee": 0,
    "delivery_charges": 0
  },
  "date_range": {
    "from": "2026-08-01",
    "to": "2026-09-24"
  },
  "total_customers": {
    "count": 1
  },
  "total_discounts": {
    "total_amount": 0,
    "total_applications": 0,
    "references": []
  },
  "complete_order_summary": {
    "rows": [],
    "total_discount_amount": 0
  },
  "order_type_summary": {
    "rows": [
      {
        "type_name": "Delivery",
        "orders": 2,
        "share_percent": 66.67,
        "amount": 22
      }
    ],
    "totals": {
      "orders": 3,
      "share_percent": 100,
      "amount": 33
    }
  },
  "order_discount_summary": {
    "rows": [],
    "totals": {
      "applied_times": 0,
      "avg_discount": 0,
      "total_amount": 0
    },
    "footer": {
      "discount_percent_of_gross_sales": 0,
      "gross_sales_amount": 31.96,
      "gross_sales_currency": "AED",
      "message": "Discounts represent 0% of gross sales (31.96 AED) · Deducted from net collected"
    }
  },
  "item_discount_summary": {
    "rows": [],
    "totals": {
      "qty": 0,
      "original": 0,
      "discount": 0,
      "net": 0
    }
  }
}

get_invoice_activities

GET /api/v2/activities/:uuid. Why: Audit trail of one order by uuid — what web-pos shows in the order's "Activity" section: who did what and when (created, items added/removed, paid, voided, payment method changed…). uuid comes from list_orders_history or list_dine_orders. Rows are written by the POS apps; cancel_invoice / refund_invoice done by an agent do NOT add rows. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_invoice_activities"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_invoice_activities",
  "uuid": "example"
}'

Example Response

{
  "status": true,
  "message": "No activities found against the order.",
  "data": []
}

get_maintenance_status

GET /api/v2/maintenance/status. Why: Global (all tenants) maintenance switch. web-pos polls it every 2 minutes and blocks the whole POS with a maintenance screen while is_maintenance = 1 or the server answers 500/502/503. Check it before a batch of writes (sync_invoice etc.) or when calls start failing. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_maintenance_status"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

No additional parameters — only the Authorization: Bearer header is required.

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_maintenance_status"
}'

Example Response

{
  "status": true,
  "data": {
    "is_maintenance": 0,
    "message": "All systems are up and running smoothly."
  }
}

get_loyalty_card

GET /api/v2/loyalty-program/card/:crmUserId. Why: A customer's loyalty card — what web-pos loads for the cart balance banner and before any redemption at payment. The tenant has ONE loyalty program (type point, stamp or membership) shared by every branch; a customer joins it only by enrolling (the card is NOT created by the POS, by create_pos_crm_user or by a sale). point: current_points and their money value (available_points_amount). stamp: current_stamps / stamps_required and the reward. membership: expiry and active flag. Read-only. Use it only when get_user_extras data.ios_modules.is_loyalty_enable = 1 and a customer is on the order (crm_user_id > 0 from list_pos_crm_users / create_pos_crm_user). Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_loyalty_card"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_loyalty_card",
  "crmUserId": "example"
}'

Example Response

{
  "status": true,
  "message": "Loyalty card retrieved successfully.",
  "data": {
    "card_id": 57,
    "crm_user_id": 63821,
    "loyalty_program_id": 16,
    "loyalty_type": "point",
    "customer_name": "Sara Ahmed",
    "email": "sara.ahmed@example.com",
    "phone_number": "+971500000001",
    "is_active": 1,
    "total_redeemed": 0,
    "last_redeemed_date": null,
    "current_points": 3,
    "available_points": 3,
    "available_points_amount": 0.3,
    "program": {
      "id": 16,
      "name": "Loyalty 1",
      "description": null,
      "reward_description": null,
      "is_active": 1
    },
    "pass_info": {
      "serial_number": "00000000-0000-4000-8000-000000000057",
      "type_identifier": "pass.com.syspos.pos"
    },
    "card_created_at": "2026-06-29T10:27:28.000Z",
    "card_updated_at": "2026-08-20T11:07:43.000Z"
  }
}

validate_loyalty_burn

POST /api/v2/loyalty-program/burn-validation. Why: Server check of a loyalty redemption before you apply it at payment — what web-pos calls from the Redeem points dialog (point program) and the Redeem stamps button (stamp program). Uses the tenant's program and the customer's card (from get_loyalty_card). point: checks burn_points <= current_points and returns burn_amount = burn_points × redeem_amount / redeem_points. stamp / membership: checks the card is full / not expired, the minimum order and returns discount_amount. Does NOT reserve or deduct anything: it only reads (no OTP is sent, nothing is stored); the points are burned when the PAID order is saved (sync_invoice). No side effects. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"validate_loyalty_burn"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "validate_loyalty_burn",
  "crm_user_id": 11,
  "order_total": 1
}'

Example Response

{
  "status": true,
  "message": "Burn validation successful",
  "data": {
    "status": "Success",
    "available_points": 30,
    "burn_points": 20,
    "burn_amount": 2,
    "points_after_burn": 10,
    "conversion_rate": 0.1,
    "loyalty_program_id": 16,
    "loyalty_card_id": 57,
    "crm_user_id": 63821,
    "order_total": 45.5,
    "discount_reason": "Loyalty discount"
  }
}

list_locations

GET /api/locations. Why: Every branch (location) of the tenant this key may use, with its id and name — the id is the loc / location_id that every other tool takes (get_pos_configs, get_location_config, get_business_info, get_business_hours, get_location_days_hours, list_* catalog tools, create_* location_id lists). Call it first whenever the user names a branch, to turn the name into an id. Also shows the warehouse flag and the per-branch payment settings. This is the unpaginated list every dashboard picker uses; the dashboard Locations page uses the paginated /api/locations/v2 (same rows, fewer columns, newest first) — not exposed because this tool returns the same data in one call and MCP filters it to the key's branches. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_locations"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

No additional parameters — only the Authorization: Bearer header is required.

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_locations"
}'

Example Response

[
  {
    "id": 907,
    "name": "Default location",
    "is_ware_house": "1",
    "enable_menu_checkout": null,
    "payment_provider": null,
    "ngenius_terminal_id": null,
    "ngenius_merchant_id": null,
    "invoice_service_version": "v1"
  },
  {
    "id": 908,
    "name": "Johar Town",
    "is_ware_house": "1",
    "enable_menu_checkout": null,
    "payment_provider": null,
    "ngenius_terminal_id": null,
    "ngenius_merchant_id": null,
    "invoice_service_version": "v1"
  },
  {
    "id": 909,
    "name": "Iqbal Town",
    "is_ware_house": "1",
    "enable_menu_checkout": null,
    "payment_provider": null,
    "ngenius_terminal_id": null,
    "ngenius_merchant_id": null,
    "invoice_service_version": "v1"
  },
  {
    "id": 910,
    "name": "Bahira Town",
    "is_ware_house": "0",
    "enable_menu_checkout": null,
    "payment_provider": null,
    "ngenius_terminal_id": null,
    "ngenius_merchant_id": null,
    "invoice_service_version": "v1"
  }
]

get_location

GET /api/locations/:id. Why: The full row of ONE branch — every column list_locations shows plus the integration ids (otter, deliverect, grubtech flags). Read it before update_location: that tool overwrites name, isWareHouse, enable_menu_checkout, payment_provider and both N-Genius ids, so you must send the current values of the ones you are not changing. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_location"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_location",
  "id": 11
}'

Example Response

[
  {
    "id": 907,
    "name": "Default location",
    "customer_id": 437,
    "is_ware_house": "1",
    "is_primary": null,
    "otter_location_id": null,
    "deliverect_location_id": null,
    "enable_menu_checkout": null,
    "invoice_service_version": "v1",
    "payment_provider": null,
    "ngenius_terminal_id": null,
    "ngenius_merchant_id": null,
    "enable_grubtech": 0,
    "allow_grubtech_status_updates": 0
  }
]

get_business_info

GET /api/config/business-info. Why: The branch's business profile — what the receipt header prints (name, address, VAT No, logo) plus contact, legal name, delivery area and T&C. Read it before create_business_info / update_business_info and to check what a receipt will show. Pass strict="1": without it an EMPTY branch silently returns ANOTHER branch's profile. Returns rows { id, name, value }; name is one of: info_name, legal_name, info_address, info_phone, info_email, info_vat_no, logo_image, license_image, location_latitude, location_longitude, polygon_coordinates, area_coordinates, receipt_footer_text, reciept_header_text (sic), currency, terms_and_conditions. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_business_info"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_business_info"
}'

Example Response

[
  {
    "id": 9993,
    "value": "Example Cafe",
    "name": "info_name"
  },
  {
    "id": 9994,
    "value": "Shop 1, Example Street",
    "name": "info_address"
  },
  {
    "id": 9995,
    "value": "info@example-cafe.test",
    "name": "info_email"
  },
  {
    "id": 9996,
    "value": "100000000000003",
    "name": "info_vat_no"
  },
  {
    "id": 9997,
    "value": "1762167059218-example-logo.png",
    "name": "logo_image"
  },
  {
    "id": 10103,
    "value": "",
    "name": "currency"
  },
  {
    "id": 10237,
    "value": "+971500000000",
    "name": "info_phone"
  },
  {
    "id": 11174,
    "value": "<ul><li>Optional note</li></ul>",
    "name": "receipt_footer_text"
  }
]

get_location_config

GET /api/config/all. Why: Read a branch's settings exactly as the dashboard Settings page shows them: VAT %, currency, decimals, time zone, business hours, exchange rate, receipt texts, POS flags, plus the main business-info keys. Use it to check a branch before selling (sync_invoice needs vat, decimal_points, time_zone) and before save_config. Branch rows only — no fallback. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_location_config"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_location_config"
}'

Example Response

[
  {
    "id": 9905,
    "value": "+05:00",
    "name": "time_zone"
  },
  {
    "id": 9943,
    "value": "5",
    "name": "vat"
  },
  {
    "id": 9993,
    "value": "Example Cafe",
    "name": "info_name"
  },
  {
    "id": 9994,
    "value": "Shop 1, Example Street",
    "name": "info_address"
  },
  {
    "id": 9995,
    "value": "info@example-cafe.test",
    "name": "info_email"
  },
  {
    "id": 9996,
    "value": "100000000000003",
    "name": "info_vat_no"
  },
  {
    "id": 9997,
    "value": "1762167059218-example-logo.png",
    "name": "logo_image"
  },
  {
    "id": 10101,
    "value": "10:00",
    "name": "opening_hour"
  },
  {
    "id": 10102,
    "value": "08:00",
    "name": "closing_hour"
  },
  {
    "id": 10103,
    "value": "",
    "name": "currency"
  },
  {
    "id": 10237,
    "value": "+971500000000",
    "name": "info_phone"
  },
  {
    "id": 10977,
    "value": "Asia/Karachi",
    "name": "time_zone_code"
  },
  {
    "id": 11174,
    "value": "<ul><li>Optional note</li></ul>",
    "name": "receipt_footer_text"
  },
  {
    "id": 11578,
    "value": "12",
    "name": "exchange_rate"
  },
  {
    "id": 11583,
    "value": "20",
    "name": "max_order_time"
  }
]

get_currency

GET /api/config/currency. Why: Currency code of one branch (display only). Same route as get_config_value with name=currency. Pass loc — without a branch the server returns the first currency row of ANY branch. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_currency"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_currency"
}'

Example Response

{
  "name": "currency",
  "value": ""
}

get_config_value

GET /api/config/:name. Why: Read ONE config key of one branch (any key, including ones get_location_config does not list). Use before save_config to see the current value. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_config_value"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_config_value",
  "name": "Iced Latte"
}'

Example Response

{
  "name": "vat",
  "value": "5"
}

get_business_hours

GET /api/config/business-hours. Why: The branch's BUSINESS DAY as a UTC window — the same opening_hour + time_zone config rule the POS uses for 'today' (get_today_sales, get_ol_info, list_kds_orders, daily reports). Use start_utc / end_utc to bound order or invoice queries for a date range in the branch's local business days. It says nothing about per-weekday open/closed times — that is get_location_days_hours. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_business_hours"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_business_hours"
}'

Example Response

{
  "success": true,
  "data": {
    "start_utc": "2026-09-25 05:00:00",
    "end_utc": "2026-09-26 05:00:00",
    "time_zone": "+00:00",
    "opening_hour": "10:00",
    "closing_hour": "08:00"
  }
}

get_location_days_hours

GET /api/location-days-hours-config. Why: The branch's weekly OPERATING HOURS as set on the dashboard Business Info > Operating Hours tab: one row per weekday with open / close time or 'closed all day'. Use it to answer 'when is branch X open on Sunday' or before upsert_location_days_hours. It is independent from the business-day hours (opening_hour config → get_business_hours), which drive POS 'today' and reports. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_location_days_hours"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_location_days_hours"
}'

Example Response

[
  {
    "id": 29,
    "customer_id": 437,
    "location_id": 909,
    "day": "monday",
    "open": "12:00",
    "close": "00:00",
    "is_off": 0,
    "created_at": "2025-10-03T05:50:48.000Z",
    "updated_at": "2025-10-03T05:50:48.000Z"
  },
  {
    "id": 30,
    "customer_id": 437,
    "location_id": 909,
    "day": "tuesday",
    "open": "12:00",
    "close": "00:00",
    "is_off": 0,
    "created_at": "2025-10-03T05:50:48.000Z",
    "updated_at": "2025-10-03T05:50:48.000Z"
  },
  {
    "id": 31,
    "customer_id": 437,
    "location_id": 909,
    "day": "wednesday",
    "open": "12:00",
    "close": "00:00",
    "is_off": 0,
    "created_at": "2025-10-03T05:50:48.000Z",
    "updated_at": "2025-10-03T05:50:48.000Z"
  },
  {
    "id": 32,
    "customer_id": 437,
    "location_id": 909,
    "day": "thursday",
    "open": "12:00",
    "close": "00:00",
    "is_off": 0,
    "created_at": "2025-10-03T05:50:48.000Z",
    "updated_at": "2025-10-03T05:50:48.000Z"
  },
  {
    "id": 33,
    "customer_id": 437,
    "location_id": 909,
    "day": "friday",
    "open": "12:00",
    "close": "00:00",
    "is_off": 0,
    "created_at": "2025-10-03T05:50:48.000Z",
    "updated_at": "2025-10-03T05:50:48.000Z"
  },
  {
    "id": 34,
    "customer_id": 437,
    "location_id": 909,
    "day": "saturday",
    "open": "12:00",
    "close": "00:00",
    "is_off": 0,
    "created_at": "2025-10-03T05:50:48.000Z",
    "updated_at": "2025-10-03T05:50:48.000Z"
  },
  {
    "id": 35,
    "customer_id": 437,
    "location_id": 909,
    "day": "sunday",
    "open": null,
    "close": null,
    "is_off": 1,
    "created_at": "2025-10-03T05:50:48.000Z",
    "updated_at": "2025-10-03T05:50:48.000Z"
  }
]

get_pos_configs

GET /api/v2/config/get-all-configs. Why: Every config row (name/value) of ONE branch — the source web-pos uses at boot for the flat VAT % (key vat), currency (currency) and time zone (time_zone, else time_zone_code). Read it before building a sync_invoice order: vat → line/order vat and vat_pct, time_zone → seconds_from_gmt. Also holds business hours (opening_hour / closing_hour → get_today_sales, get_ol_info), receipt header keys and exchange_rate. Tax groups are out of scope. For a named subset use get_location_config / get_business_info. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_pos_configs"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_pos_configs"
}'

Example Response

{
  "status": true,
  "message": "Configs retrieved successfully",
  "data": [
    {
      "id": 9905,
      "name": "time_zone",
      "value": "+05:00",
      "customer_id": 437,
      "location_id": 907
    },
    {
      "id": 9943,
      "name": "vat",
      "value": "5",
      "customer_id": 437,
      "location_id": 907
    },
    {
      "id": 9993,
      "name": "info_name",
      "value": "Example Cafe",
      "customer_id": 437,
      "location_id": 907
    },
    {
      "id": 9994,
      "name": "info_address",
      "value": "Shop 1, Example Street",
      "customer_id": 437,
      "location_id": 907
    },
    {
      "id": 9995,
      "name": "info_email",
      "value": "info@example-cafe.test",
      "customer_id": 437,
      "location_id": 907
    },
    {
      "id": 9996,
      "name": "info_vat_no",
      "value": "100000000000003",
      "customer_id": 437,
      "location_id": 907
    },
    {
      "id": 9997,
      "name": "logo_image",
      "value": "example-logo.png",
      "customer_id": 437,
      "location_id": 907
    },
    {
      "id": 10101,
      "name": "opening_hour",
      "value": "10:00",
      "customer_id": 437,
      "location_id": 907
    },
    {
      "id": 10102,
      "name": "closing_hour",
      "value": "08:00",
      "customer_id": 437,
      "location_id": 907
    },
    {
      "id": 10103,
      "name": "currency",
      "value": "",
      "customer_id": 437,
      "location_id": 907
    },
    {
      "id": 10237,
      "name": "info_phone",
      "value": "+971500000000",
      "customer_id": 437,
      "location_id": 907
    },
    {
      "id": 10977,
      "name": "time_zone_code",
      "value": "Asia/Karachi",
      "customer_id": 437,
      "location_id": 907
    },
    {
      "id": 11174,
      "name": "receipt_footer_text",
      "value": "<ul><li>Optional note</li></ul>",
      "customer_id": 437,
      "location_id": 907
    },
    {
      "id": 11578,
      "name": "exchange_rate",
      "value": "12",
      "customer_id": 437,
      "location_id": 907
    },
    {
      "id": 11583,
      "name": "max_order_time",
      "value": "20",
      "customer_id": 437,
      "location_id": 907
    }
  ]
}

list_selling_floors

GET /api/v2/floors. Why: Floors (dining areas) of the cashier's session branch — what web-pos loads at boot for the floor tabs on the Dine screen and in the "Select table" dialog of a dine-in order. A floor only groups tables: tables point to it with floor_id (list_selling_tables), and the live occupancy per table comes from list_dine_orders. Session branch only (no params); for another branch use list_floors_by_location. Not paginated. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_selling_floors"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

No additional parameters — only the Authorization: Bearer header is required.

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_selling_floors"
}'

Example Response

{
  "status": true,
  "message": "Record Found",
  "data": [
    {
      "id": 606,
      "name": "Ground Floor",
      "customer_id": 437,
      "location_id": 907,
      "image": "",
      "width": 0,
      "length": 0,
      "floor_design": "",
      "web_image": ""
    },
    {
      "id": 615,
      "name": "1st Floor",
      "customer_id": 437,
      "location_id": 907,
      "image": "",
      "width": 0,
      "length": 0,
      "floor_design": "false",
      "web_image": ""
    },
    {
      "id": 619,
      "name": "Second Floor",
      "customer_id": 437,
      "location_id": 907,
      "image": "",
      "width": 0,
      "length": 0,
      "floor_design": "",
      "web_image": ""
    }
  ]
}

list_selling_tables

GET /api/v2/tables. Why: Tables of the cashier's session branch — what web-pos loads at boot to resolve table names (tickets, order list, bill header) and each table's floor. The table id is what a dine-in order carries as table_id. Occupancy is NOT here: list_dine_orders returns the same tables with their open tickets (dinerOrderDetail) and is what the Dine screen actually draws; get_table_order gives the latest ticket of one table. Tables have no brand_id. Session branch only (no params); for another branch use list_tables_by_location. Not paginated. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_selling_tables"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

No additional parameters — only the Authorization: Bearer header is required.

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_selling_tables"
}'

Example Response

[
  {
    "id": 5935,
    "name": "Table A5",
    "customer_id": 437,
    "location_id": 907,
    "x_pos": null,
    "y_pos": null,
    "people_size": 0,
    "attended_by": null,
    "unavailable": 1,
    "plate_number": null,
    "is_plate": 1,
    "guest_name": null,
    "floor_id": 606,
    "width": 30,
    "height": 30,
    "rotation": 0,
    "is_rounded": 0,
    "x": 72,
    "y": 49,
    "pgo_restaurant_short_name": null,
    "pgo_table_short_id": null,
    "is_active": 1,
    "capacity": 4,
    "current_status": "available",
    "qr_code_link": null,
    "today_activity_percentage": 0,
    "last_activity_at": null,
    "table_number": null,
    "created_at": "2026-02-24T11:13:55.000Z",
    "updated_at": "2026-02-24T11:13:55.000Z"
  },
  {
    "id": 6194,
    "name": "Table 1",
    "customer_id": 437,
    "location_id": 907,
    "x_pos": null,
    "y_pos": null,
    "people_size": 0,
    "attended_by": null,
    "unavailable": 0,
    "plate_number": null,
    "is_plate": 0,
    "guest_name": null,
    "floor_id": 606,
    "width": 30,
    "height": 30,
    "rotation": 0,
    "is_rounded": 0,
    "x": 42,
    "y": 29,
    "pgo_restaurant_short_name": null,
    "pgo_table_short_id": null,
    "is_active": 1,
    "capacity": 4,
    "current_status": "available",
    "qr_code_link": null,
    "today_activity_percentage": 0,
    "last_activity_at": null,
    "table_number": null,
    "created_at": "2026-06-24T08:03:09.000Z",
    "updated_at": "2026-06-24T08:03:09.000Z"
  }
]

list_floors_by_location

GET /api/floors-location/:location_id. Why: Floors of one branch (dashboard route; any branch of the tenant, not only the session branch). Tables link to a floor with floor_id (list_tables_by_floor / list_tables_by_location); live occupancy per table is in list_dine_orders. POS view of the session branch: list_selling_floors. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_floors_by_location"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_floors_by_location",
  "location_id": 11
}'

Example Response

[
  {
    "id": 606,
    "name": "Ground Floor",
    "customer_id": 437,
    "location_id": 907,
    "image": "",
    "width": 0,
    "length": 0,
    "floor_design": "",
    "web_image": ""
  },
  {
    "id": 615,
    "name": "1st Floor",
    "customer_id": 437,
    "location_id": 907,
    "image": "",
    "width": 0,
    "length": 0,
    "floor_design": "false",
    "web_image": ""
  },
  {
    "id": 619,
    "name": "Second Floor",
    "customer_id": 437,
    "location_id": 907,
    "image": "",
    "width": 0,
    "length": 0,
    "floor_design": "",
    "web_image": ""
  }
]

get_floor

GET /api/floors/:id. Why: One floor by id (dashboard route). Scoped to your tenant; any branch. Its tables: list_tables_by_floor with floor_id = id. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_floor"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_floor",
  "id": 11
}'

Example Response

{
  "status": true,
  "message": "Record Found",
  "data": [
    {
      "id": 606,
      "name": "Ground Floor",
      "customer_id": 437,
      "location_id": 907,
      "image": "",
      "width": 0,
      "length": 0,
      "floor_design": "",
      "web_image": ""
    }
  ]
}

list_tables_by_location

GET /api/tables-location/:location_id. Why: Tables of one branch (dashboard route; any branch of the tenant). Same rows as list_selling_tables but for a chosen branch. Each table's floor is floor_id (get_floor); its open tickets are in list_dine_orders (session branch only) / get_table_order. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_tables_by_location"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_tables_by_location",
  "location_id": 11
}'

Example Response

[
  {
    "id": 5935,
    "name": "Table A5",
    "customer_id": 437,
    "location_id": 907,
    "x_pos": null,
    "y_pos": null,
    "people_size": 0,
    "attended_by": null,
    "unavailable": 1,
    "plate_number": null,
    "is_plate": 1,
    "guest_name": null,
    "floor_id": 606,
    "width": 30,
    "height": 30,
    "rotation": 0,
    "is_rounded": 0,
    "x": 72,
    "y": 49,
    "pgo_restaurant_short_name": null,
    "pgo_table_short_id": null,
    "is_active": 1,
    "capacity": 4,
    "current_status": "available",
    "qr_code_link": null,
    "today_activity_percentage": 0,
    "last_activity_at": null,
    "table_number": null,
    "created_at": "2026-02-24T11:13:55.000Z",
    "updated_at": "2026-02-24T11:13:55.000Z"
  },
  {
    "id": 6194,
    "name": "Table 1",
    "customer_id": 437,
    "location_id": 907,
    "x_pos": null,
    "y_pos": null,
    "people_size": 0,
    "attended_by": null,
    "unavailable": 0,
    "plate_number": null,
    "is_plate": 0,
    "guest_name": null,
    "floor_id": 606,
    "width": 30,
    "height": 30,
    "rotation": 0,
    "is_rounded": 0,
    "x": 42,
    "y": 29,
    "pgo_restaurant_short_name": null,
    "pgo_table_short_id": null,
    "is_active": 1,
    "capacity": 4,
    "current_status": "available",
    "qr_code_link": null,
    "today_activity_percentage": 0,
    "last_activity_at": null,
    "table_number": null,
    "created_at": "2026-06-24T08:03:09.000Z",
    "updated_at": "2026-06-24T08:03:09.000Z"
  }
]

list_tables_by_floor

GET /api/tables-floor/:floor_id. Why: Tables on one floor (dashboard route). Scoped to your tenant but NOT to a branch: floor_id 0 returns every table of the tenant across all branches, and the API key allow_locations is not applied to this tool — filter on location_id yourself. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_tables_by_floor"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_tables_by_floor",
  "floor_id": 11
}'

Example Response

[
  {
    "id": 5935,
    "name": "Table A5",
    "customer_id": 437,
    "location_id": 907,
    "x_pos": null,
    "y_pos": null,
    "people_size": 0,
    "attended_by": null,
    "unavailable": 1,
    "plate_number": null,
    "is_plate": 1,
    "guest_name": null,
    "floor_id": 606,
    "width": 30,
    "height": 30,
    "rotation": 0,
    "is_rounded": 0,
    "x": 72,
    "y": 49,
    "pgo_restaurant_short_name": null,
    "pgo_table_short_id": null,
    "is_active": 1,
    "capacity": 4,
    "current_status": "available",
    "qr_code_link": null,
    "today_activity_percentage": 0,
    "last_activity_at": null,
    "table_number": null,
    "created_at": "2026-02-24T11:13:55.000Z",
    "updated_at": "2026-02-24T11:13:55.000Z"
  }
]

get_table

GET /api/tables/:id. Why: BROKEN on the server — do not rely on it: the handler never binds the id, so the SQL fails and the response is HTTP 200 with an EMPTY body for every id. To read one table use list_selling_tables (session branch) or list_tables_by_location and match id. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_table"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_table",
  "id": 11
}'

Example Response

"<empty body: HTTP 200, no JSON>"

list_dine_orders

GET /api/v2/dine-orders-v3. Why: The live dine board of the JWT session branch — exactly what web-pos draws on the Dine screen: EVERY table of the branch (id = table id, floor_id, name, people_size, x, y …) with its open/done tickets in dinerOrderDetail. A table is OCCUPIED when dinerOrderDetail has at least one ticket, FREE when it is null or []. Group rows by floor_id (list_selling_floors). Optional table_id filter (list_selling_tables). The location cannot be changed via query. For one table's latest ticket use get_table_order; for a ticket's lines use get_invoice_items with its uuid. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_dine_orders"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_dine_orders"
}'

Example Response

[
  {
    "floor_id": 606,
    "id": 6194,
    "name": "Table 1",
    "customer_id": 437,
    "location_id": 907,
    "x": 42,
    "y": 29,
    "is_rounded": 0,
    "rotation": 0,
    "height": 30,
    "width": 30,
    "people_size": 0,
    "attended_by": null,
    "unavailable": 0,
    "is_plate": 0,
    "plate_number": null,
    "uuid": [
      "b7b056e0-3c5f-437d-9258-968b6cc34a6e"
    ],
    "dinerOrderDetail": [
      {
        "id": 23,
        "customer_invoice_id": 23,
        "uuid": "b7b056e0-3c5f-437d-9258-968b6cc34a6e",
        "status": "open",
        "order_no": 1,
        "table_id": 6194,
        "floor_id": 606,
        "order_type": "Dine In",
        "is_paid": null,
        "payable": 31,
        "payment_method": null,
        "created_at": 1787738588,
        "order_items": [
          {
            "id": 25504110,
            "identifier": "5f1c0c66-2efb-4335-ab40-99ce6ceaa433",
            "name": "Flat White",
            "name_localize": null,
            "actual_price": 11,
            "price": 11,
            "qty": 1,
            "subtotal": 11,
            "line_total": null,
            "line_vat": null,
            "line_total_without_vat": null,
            "invoice_uuid": "b7b056e0-3c5f-437d-9258-968b6cc34a6e",
            "product_id": 257506,
            "extras": null,
            "vat": 0,
            "is_updated": 0,
            "updated_qty": 0,
            "is_addon": 0,
            "is_refunded": 0,
            "refund_quantity": 0,
            "refund_reason": null,
            "note": null,
            "addon_linked_with": "5f1c0c66-2efb-4335-ab40-99ce6ceaa433",
            "discount_pct": 0,
            "discount_amount": 0,
            "modifier": [],
            "transferred_to": 0,
            "transferred_to_uuid": null,
            "transferred_to_uuid_list": [
              "3ccd598a-f022-4939-931f-eedd132e79b6",
              "f2ab957f-2cba-4b48-a534-8681b8934a1a",
              "0ea2c766-fd6d-418d-9e04-70aa6a60fa1a"
            ],
            "transferred_quantities": [
              2,
              4,
              1.5
            ],
            "transfer_recipients": [
              12,
              43,
              60
            ],
            "created_at": 1787738588,
            "updated_at": 1787738588,
            "is_prepared": 0,
            "preparation_time": null,
            "is_weightage_item": 0,
            "unit_id": 0,
            "type": "Espresso-Based Drinks",
            "label_id": 50,
            "item_status": "active",
            "linked_uuid": null,
            "original_linked_uuid": null,
            "disposition_type": null,
            "image": null,
            "is_combo": 0,
            "is_deleted": 0,
            "deleted_at": null,
            "deleted_qty": 0,
            "coupon_amount": 0,
            "coupon_id": 0,
            "coupon_code": "",
            "updated_by_user_ids": [],
            "re": null,
            "ri": 0,
            "is_wastage": 0,
            "discount_id": null,
            "discount_name": null,
            "round": null,
            "combo_items": null
          }
        ]
      }
    ]
  },
  {
    "floor_id": 606,
    "id": 6195,
    "name": "Table 2",
    "customer_id": 437,
    "location_id": 907,
    "x": 29,
    "y": 46,
    "is_rounded": 0,
    "rotation": 0,
    "height": 30,
    "width": 30,
    "people_size": 0,
    "attended_by": null,
    "unavailable": 0,
    "is_plate": 0,
    "plate_number": null,
    "uuid": [],
    "dinerOrderDetail": null
  }
]

get_table_order

GET /api/dine-table-order/:table. Why: The latest open (or done) ticket of ONE table at the JWT session branch, with its lines — what to reopen when adding items to an occupied table. Table id comes from list_selling_tables / list_dine_orders. Only the newest ticket is returned; when a table has several open tickets use list_dine_orders (dinerOrderDetail lists them all). Session branch only (a table of another branch returns []). Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_table_order"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_table_order",
  "table": 1
}'

Example Response

[
  {
    "token_number": null,
    "id": 23,
    "items_number": 3,
    "aggregator_order_id": null,
    "is_accepted": 0,
    "exchange_rate": 0,
    "subtotal": 31,
    "vat": 0,
    "payable": 31,
    "discountamount": 0,
    "discountpct": 0,
    "paid": 0,
    "channel_id": 0,
    "change": 0,
    "note": "dev1 transfer-fields e2e dine",
    "uuid": "b7b056e0-3c5f-437d-9258-968b6cc34a6e",
    "created_at": "2026-08-26T10:03:08.000Z",
    "customer_id": 437,
    "location_id": 907,
    "info_name": "",
    "info_address": "",
    "info_phone": "",
    "info_email": "",
    "status": "open",
    "user": "admin@devnexus.co",
    "user_id": 4734,
    "table_id": 6194,
    "payment_method": null,
    "order_id": null,
    "invoice_id": null,
    "done_at": null,
    "period": null,
    "is_kds_printed": 0,
    "is_invoice_printed": 0,
    "plate_number": null,
    "order_no": 1,
    "is_paid": "0",
    "is_refunded": 0,
    "guest_name": "Transfer E2E Dine",
    "is_updated": 0,
    "card_digits": "",
    "mac_addresses": "",
    "crm_user_id": 0,
    "updated_at": "2026-08-26T10:03:10.000Z",
    "crm_user_name": "",
    "created_by_user_id": 4734,
    "close_by_user_id": null,
    "modified_by_user_ids": [],
    "discount_id": null,
    "order_type": "Dine In",
    "is_vat_on_discount_exclude": 0,
    "dining_guests": 2,
    "channel_name": "",
    "order_items": [
      {
        "id": 25504110,
        "identifier": "5f1c0c66-2efb-4335-ab40-99ce6ceaa433",
        "name": "Flat White",
        "name_localize": null,
        "actual_price": 11,
        "base_price": null,
        "price": 11,
        "is_weightage_item": 0,
        "unit_id": 0,
        "qty": 1,
        "subtotal": 11,
        "line_total": null,
        "line_vat": null,
        "line_total_without_vat": null,
        "invoice_uuid": "b7b056e0-3c5f-437d-9258-968b6cc34a6e",
        "product_id": 257506,
        "extras": null,
        "vat": 0,
        "is_updated": 0,
        "updated_qty": 0,
        "is_addon": 0,
        "is_refunded": 0,
        "refund_quantity": 0,
        "refund_reason": null,
        "note": null,
        "addon_linked_with": "5f1c0c66-2efb-4335-ab40-99ce6ceaa433",
        "discount_pct": 0,
        "discount_amount": 0,
        "modifier": [],
        "transferred_to": 0,
        "transferred_to_uuid": null,
        "transferred_to_uuid_list": [
          "3ccd598a-f022-4939-931f-eedd132e79b6",
          "f2ab957f-2cba-4b48-a534-8681b8934a1a",
          "0ea2c766-fd6d-418d-9e04-70aa6a60fa1a"
        ],
        "transferred_quantities": [
          2,
          4,
          1.5
        ],
        "transfer_recipients": [
          12,
          43,
          60
        ],
        "created_at": 1787738588,
        "updated_at": 1787738588,
        "is_prepared": 0,
        "preparation_time": null,
        "type": "Espresso-Based Drinks",
        "label_id": 50,
        "is_combo": 0,
        "is_deleted": 0,
        "deleted_at": null,
        "deleted_qty": 0,
        "coupon_amount": 0,
        "coupon_id": 0,
        "coupon_code": "",
        "updated_by_user_ids": [],
        "re": null,
        "ri": 0,
        "is_wastage": 0,
        "discount_id": null,
        "discount_name": null,
        "round": null,
        "combo_items": null
      }
    ],
    "items_discount_amount": 0
  }
]

list_orders_history

GET /api/v2/orders-history. Why: The order list of the session branch — exactly what the web-pos Invoices screen loads: every order (open, completed, cancelled) newest first, 30 per page, with lines, payments, customer and a summary. Use it to find an order (by status, invoice number, customer, phone, plate, shift, brand or business day) and read it in full; then act on its uuid with cancel_invoice, refund_invoice, update_invoice_payment_methods or get_invoice_activities. Paginated with current_page / page_limit. order_type cannot be filtered on the server — filter the rows yourself by list_selling_order_types title. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_orders_history"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_orders_history"
}'

Example Response

{
  "status": true,
  "message": "Orders history",
  "data": {
    "current_page": "1",
    "records_per_page": 10,
    "total_records": 5,
    "force_location_ids": [
      907
    ],
    "summary": {
      "total_orders": 5,
      "total_revenue": 461,
      "completed_orders": 0,
      "completed_revenue": 0,
      "open_orders": 0,
      "open_revenue": 0,
      "void_orders": 5,
      "void_revenue": 461
    },
    "orders": [
      {
        "id": "3609c849e2e4",
        "oid": 19,
        "customer_invoice_id": 19,
        "brand_id": null,
        "exchange_rate": null,
        "token_number": null,
        "is_wastage": 0,
        "paid_in_usd": null,
        "is_accepted": null,
        "external_order_ready": 0,
        "is_discount_on_total": null,
        "items_number": 2,
        "aggregator_order_id": null,
        "subtotal": 106,
        "vat": 0,
        "payable": 106,
        "discountamount": 0,
        "items_discount_amount": 1.1,
        "is_ticket_available": 1,
        "is_wallet_used": 0,
        "discountpct": 0,
        "paid": 106,
        "change": 0,
        "note": "qa cancel **canceled by: Nexus Cafe",
        "uuid": "3a00fb3a-0c78-444a-abef-3609c849e2e4",
        "deliverect_id": null,
        "created_at": 1786948030,
        "updated_at": 1786948031,
        "customer_id": 437,
        "location_id": 907,
        "guest_name": "QA rd 0",
        "info_name": "QA",
        "info_address": "",
        "info_phone": "",
        "info_email": "cashier@example.com",
        "status": "cancelled",
        "by": null,
        "external_order_id": null,
        "user": "cashier@example.com",
        "table_id": 0,
        "order_id": null,
        "payment_method": [
          {
            "cash": 106
          }
        ],
        "burn_points": 0,
        "earn_points": 0,
        "burn_points_amount": 0,
        "available_points": 0,
        "available_points_amount": 0,
        "charges_fee": 0,
        "delivery_charges": 0,
        "phone_number": "",
        "loyalty_mobile_number": "",
        "loyalty_mobile_code": "",
        "crm_delivery_area": null,
        "invoice_id": null,
        "done_at": null,
        "period": null,
        "is_kds_printed": 0,
        "is_invoice_printed": 0,
        "plate_number": null,
        "order_no": 4,
        "created_by_user_id": 4734,
        "close_by_user_id": 4734,
        "modified_by_user_ids": [],
        "is_vat_on_discount_exclude": 0,
        "order_type": "takeaway",
        "channel_id": 0,
        "tip_amount": 0,
        "dining_guests": null,
        "channel_name": "",
        "is_paid": 1,
        "card_digits": "",
        "crm_user_id": 0,
        "crm_user_name": "",
        "discount_reason": null,
        "row_discount": 0,
        "paid_at": null,
        "coupon_amount": 0,
        "coupon_id": 0,
        "coupon_code": null,
        "printed_invoice_receipts": 0,
        "printed_kds_receipts": 0,
        "app_version": "qa-rd",
        "app_os_version": "qa",
        "build_number": "1",
        "os_type": "qa",
        "round": null,
        "rider_pickup_at": null,
        "rider_arrived_at": null,
        "shift_id": null,
        "cashier_user_id": null,
        "cashier_name": null,
        "shift_clock_in_at": null,
        "is_order_rebump": 1,
        "order_type_icon_key": "boxicons:takeaway",
        "notes": [],
        "grand_total": 106,
        "payment_methods": [
          {
            "cash": {
              "amount": 106,
              "tip_amount": null
            }
          }
        ],
        "payments": [
          {
            "payment_method": "cash",
            "amount": 106,
            "tip_amount": 0
          }
        ],
        "items": [
          {
            "id": 25504102,
            "identifier": "7c53c3c5-569d-47ae-84b4-7f2e28cbcee6",
            "name": "QA rd 0 Flat White",
            "name_localize": null,
            "base_price": null,
            "actual_price": 11,
            "preparation_time": null,
            "price": 11,
            "qty": 1,
            "is_weightage_item": 0,
            "unit_id": 0,
            "subtotal": 11,
            "line_total": null,
            "line_vat": null,
            "line_total_without_vat": null,
            "invoice_uuid": "3a00fb3a-0c78-444a-abef-3609c849e2e4",
            "product_id": 257506,
            "extras": [
              {
                "name": "QA Extra",
                "actual_price": 5,
                "price": 5,
                "quantity": 1,
                "discount_pct": 0
              }
            ],
            "vat": 0,
            "is_updated": 0,
            "updated_qty": 0,
            "is_addon": 0,
            "is_refunded": 0,
            "refund_quantity": 0,
            "refund_reason": null,
            "note": null,
            "addon_linked_with": "7c53c3c5-569d-47ae-84b4-7f2e28cbcee6",
            "discount_pct": 10,
            "discount_amount": 1.1,
            "modifier": [
              {
                "name": "QA Modifier",
                "actual_price": 3,
                "price": 3,
                "quantity": 1,
                "discount_pct": 0
              }
            ],
            "transferred_to": 0,
            "transferred_to_uuid": null,
            "transferred_quantity": 0,
            "transferred_to_uuid_list": [],
            "transferred_quantities": [],
            "transfer_recipients": [],
            "created_at": 1786948030,
            "updated_at": 1786948030,
            "is_prepared": 0,
            "type": "Espresso-Based Drinks",
            "label_id": 50,
            "item_status": "active",
            "linked_uuid": null,
            "original_linked_uuid": null,
            "disposition_type": null,
            "image": null,
            "is_combo": 0,
            "is_deleted": null,
            "deleted_at": null,
            "deleted_qty": null,
            "coupon_amount": 0,
            "coupon_id": 0,
            "coupon_code": "",
            "updated_by_user_ids": [],
            "re": null,
            "ri": 0,
            "is_wastage": 0,
            "discount_id": null,
            "discount_name": null,
            "round": null,
            "combo_items": null
          },
          {
            "id": 25504103,
            "identifier": "cba24a8b-6e50-4798-a047-05834e9d9d6a",
            "name": "QA addon Classic Sandwich",
            "name_localize": null,
            "base_price": null,
            "actual_price": 100,
            "preparation_time": null,
            "price": 95,
            "qty": 1,
            "is_weightage_item": 0,
            "unit_id": null,
            "subtotal": 95,
            "line_total": null,
            "line_vat": null,
            "line_total_without_vat": null,
            "invoice_uuid": "3a00fb3a-0c78-444a-abef-3609c849e2e4",
            "product_id": 257559,
            "extras": null,
            "vat": 0,
            "is_updated": 0,
            "updated_qty": 0,
            "is_addon": 1,
            "is_refunded": 0,
            "refund_quantity": 0,
            "refund_reason": null,
            "note": null,
            "addon_linked_with": "7c53c3c5-569d-47ae-84b4-7f2e28cbcee6",
            "discount_pct": 0,
            "discount_amount": 0,
            "modifier": [],
            "transferred_to": 0,
            "transferred_to_uuid": null,
            "transferred_quantity": 0,
            "transferred_to_uuid_list": [],
            "transferred_quantities": [],
            "transfer_recipients": [],
            "created_at": 1786948030,
            "updated_at": 1786948030,
            "is_prepared": 0,
            "type": "Alternate Options,Brewed Coffee,Espresso-Based Drinks,Iced & Cold Coffees,Specialty & Flavored Coffees",
            "label_id": null,
            "item_status": "active",
            "linked_uuid": null,
            "original_linked_uuid": null,
            "disposition_type": null,
            "image": "https://dev1.syspos.ae/api/uploads/",
            "is_combo": 0,
            "is_deleted": null,
            "deleted_at": null,
            "deleted_qty": null,
            "coupon_amount": 0,
            "coupon_id": 0,
            "coupon_code": "",
            "updated_by_user_ids": [],
            "re": null,
            "ri": 0,
            "is_wastage": 0,
            "discount_id": null,
            "discount_name": null,
            "round": null,
            "combo_items": null
          }
        ],
        "order_type_icon": "https://images.weserv.nl/?url=https%3A%2F%2Fapi.iconify.design%2Fboxicons%2Ftakeaway.svg%3Fwidth%3D128%26height%3D128&output=png"
      }
    ]
  }
}

get_invoice

GET /api/invoice-v2/:uuid. Why: One order header by uuid: status, totals, payments, customer_invoice_id and the branch's receipt header (business_info). web-pos never calls it (it backs the public receipt page). Use it when you only hold a uuid; for the full order (lines, customer, is_paid, order_type) call list_orders_history with invoice_no = customer_invoice_id. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_invoice"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_invoice",
  "uuid": "example"
}'

Example Response

[
  {
    "logo_image": "1762167059218-Nexus_logo_2015.svg.png",
    "id": 8085851,
    "items_number": 2,
    "subtotal": 106,
    "vat": 0,
    "payable": 106,
    "discountamount": 0,
    "discountpct": 0,
    "paid": 106,
    "change": 0,
    "note": "qa cancel **canceled by: Nexus Cafe",
    "uuid": "3a00fb3a-0c78-444a-abef-3609c849e2e4",
    "created_at": "2026-08-17T06:27:10.000Z",
    "customer_id": 437,
    "location_id": 907,
    "info_name": "QA",
    "info_address": "",
    "info_phone": "",
    "info_email": "cashier@example.com",
    "status": "cancelled",
    "user": "cashier@example.com",
    "table_id": 0,
    "plate_number": null,
    "customer_invoice_id": 19,
    "business_info": {
      "time_zone": "+05:00",
      "vat": "5",
      "info_name": "Nexus",
      "info_address": "Nexus located at Dev",
      "info_email": "info@example.com",
      "info_vat_no": "1423",
      "logo_image": "1762167059218-Nexus_logo_2015.svg.png",
      "opening_hour": "10:00",
      "closing_hour": "08:00",
      "currency": "",
      "info_phone": "500000000",
      "receipt_footer_text": "<ul><li>Optional note</li></ul>",
      "exchange_rate": "12",
      "max_order_time": "20"
    },
    "payments": [
      {
        "payment_method": "cash",
        "amount": 106
      }
    ]
  }
]

get_invoice_items

GET /api/invoice-v2/:uuid/items. Why: Raw database lines of one order by uuid (every invoice_items column). web-pos never calls it. Prefer list_orders_history items[] (parsed, correct extras, nested combos); use this only for database-only columns such as refund_pm_type, refund_amount, item_price_after_discount or cost snapshots. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_invoice_items"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_invoice_items",
  "uuid": "example"
}'

Example Response

[
  {
    "id": 25504102,
    "name": "QA rd 0 Flat White",
    "price": 11,
    "qty": 1,
    "subtotal": 11,
    "invoice_uuid": "3a00fb3a-0c78-444a-abef-3609c849e2e4",
    "customer_id": 437,
    "location_id": 907,
    "product_id": 257506,
    "extras": [],
    "vat": 0,
    "vat_pct": null,
    "vat_name": null,
    "is_addon": 0,
    "note": null,
    "is_refunded": 0,
    "refund_quantity": 0,
    "refund_reason": null,
    "is_updated": 0,
    "updated_qty": 0,
    "addon_linked_with": [
      {
        "id": 25504103,
        "name": "QA addon Classic Sandwich",
        "actual_price": 100,
        "vat": 0,
        "price": 95,
        "subtotal": 95,
        "qty": 1
      }
    ],
    "discount_pct": 10,
    "refund_pm_type": "cash",
    "modifier": "[{\"name\":\"QA Modifier\",\"actual_price\":3,\"price\":3,\"quantity\":1,\"discount_pct\":0}]",
    "transferred_to": 0,
    "transferred_to_uuid": null,
    "created_at": "2026-08-17T06:27:10.000Z",
    "updated_at": "2026-08-17T06:27:10.000Z",
    "combo_item_id": null,
    "is_combo": 0,
    "product_type": null,
    "is_internal": null,
    "sort_order": null,
    "plu": null,
    "otter_account_id": null,
    "delivery_cost": null,
    "tip": null,
    "by": null,
    "otter_id": null,
    "transferred_quantity": 0,
    "actual_price": 11,
    "is_prepared": 0,
    "discount_amount": 1.1,
    "base_price": null,
    "brand_id": 0,
    "is_deleted": null,
    "deleted_qty": null,
    "deleted_at": null,
    "label_id": 50,
    "preparation_time": null,
    "linked_uuid": null,
    "item_type": null,
    "item_price_after_discount": 9.9,
    "line_vat": null,
    "line_total": null,
    "line_total_without_vat": null,
    "identifier": "7c53c3c5-569d-47ae-84b4-7f2e28cbcee6",
    "coupon_amount": 0,
    "coupon_id": 0,
    "coupon_code": "",
    "product_recipe_cost": 0,
    "total_cost": 0,
    "updated_by_user_ids": "",
    "re": null,
    "ri": 0,
    "is_wastage": 0,
    "discount_id": null,
    "discount_name": null,
    "round": null,
    "name_localize": null,
    "original_linked_uuid": null,
    "item_status": "active",
    "disposition_type": null,
    "disposition_reason": null,
    "refund_amount": null,
    "modifiers_cost_amount": 0,
    "cost_snapshot_at": "2026-08-17T06:27:10.000Z",
    "transferred_to_uuid_list": null,
    "transferred_quantities": null,
    "transfer_recipients": null
  }
]

list_materials

GET /api/materials. Why: Material (inventory SKU) catalog of the master inventory: raw materials (material_type mat) and recipe-output materials (rm) with branch stock, branch unit cost (avg_price), storage/ingredient units, category, suppliers and brands — the dashboard Inventory → Materials list. Use it to find material ids for get_material / update_material / delete_material, recipe ingredients (list_recipes / get_recipe), supplier catalogs and draft purchase orders (list_supplier_materials, create_draft_purchase_order), wastage, counts, transfers and work orders. Stock here is the branch on-hand qty; the movements behind it are in get_material_movements / list_inventory_movements, the ledger sum in get_material_stock. Filter by category with `cat` (id from list_material_categories), branch with `loc` (list_locations). Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_materials"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_materials"
}'

Example Response

{
  "data": [
    {
      "id": 119158,
      "name": "Cherry Blosom",
      "description": "Cherry",
      "price": 0,
      "stock": -12762188.785166,
      "unit": "Kilogram",
      "customer_id": 437,
      "location_id": [
        907,
        908,
        909,
        910,
        922
      ],
      "low_stock": 0,
      "physical_stock": null,
      "is_active": 1,
      "barcode": "",
      "ingredientunit": "Gram",
      "storageunit": "Kilogram",
      "is_prepared": 0,
      "conversionrate": "1000",
      "minimum_level": "0",
      "maximum_level": "0",
      "par_level": "0",
      "costingmethod": "average",
      "actual_stock": 0,
      "type": "raw",
      "avg_price": 1.6474,
      "materials": null,
      "sale_price": 0,
      "selling_price": 0,
      "created_at": "2026-02-09T07:05:18.000Z",
      "updated_at": "2026-08-05T07:03:56.000Z",
      "wholesale_price": 0,
      "tax_id": null,
      "material_type": "mat",
      "linked_recipe": null,
      "linked_sku": null,
      "mode": "stockable",
      "unit_id": 2,
      "ingredient_unit_id": 1,
      "custom_unit_id": null,
      "category_id": 2,
      "yield_percentage": 100,
      "sku_no": null,
      "tax_name": null,
      "tax_value": null,
      "suppliers": [
        970
      ],
      "suppliers_prices": [
        {
          "supplier_id": 970,
          "purchase_price": 1.1092
        }
      ],
      "brand_ids": [
        412,
        473
      ]
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

get_material

GET /api/materials/:id. Why: One material with its stock, reservations and unit cost at one branch (`loc`), units, costing method, suppliers with purchase prices, brands and branch list — the dashboard material edit/detail page. Load it before update_material (the update overwrites every field, so you pass this record back) and to read reserved/available stock before a transfer, wastage or count. Per-branch stock/cost: call once per branch (loc). Recipe outputs (material_type rm) link to their recipe via linked_recipe (get_recipe). Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_material"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_material",
  "id": 11
}'

Example Response

[
  {
    "id": 119158,
    "name": "Cherry Blosom",
    "description": "Cherry",
    "price": 0,
    "selling_price": 0,
    "wholesale_price": 0,
    "stock": -12762188.785166,
    "unit": "Kilogram",
    "unit_id": 2,
    "custom_unit_id": null,
    "ingredient_unit_id": 1,
    "avg_price": 1.6474,
    "customer_id": 437,
    "location_id": [
      907,
      908,
      909,
      910,
      922
    ],
    "low_stock": 0,
    "physical_stock": null,
    "actual_stock": 0,
    "is_active": 1,
    "barcode": "",
    "sku_no": "",
    "conversionrate": "1000",
    "ingredientunit": "Gram",
    "storageunit": "Kilogram",
    "costingmethod": "average",
    "minimum_level": "0",
    "maximum_level": "0",
    "par_level": "0",
    "type": "raw",
    "category_id": 2,
    "material_type": "mat",
    "mode": "stockable",
    "linked_recipe": null,
    "tax_id": null,
    "tax_name": null,
    "tax_value": null,
    "suppliers": [
      970
    ],
    "suppliers_prices": [
      {
        "supplier_id": 970,
        "purchase_price": 1.1092
      }
    ],
    "reserved_stock": 0,
    "committed_stock": 0,
    "available_for_sale": -12762188.785166,
    "brands": [
      {
        "id": 412,
        "name": "Nexus Cafe"
      },
      {
        "id": 473,
        "name": "Test "
      }
    ]
  }
]

get_material_stock

GET /api/inventory/:material_id/stock. Why: Ledger check: the sum of every inventory movement qty of one material at one branch (storage unit). Use it to cross-check the branch stock shown by get_material / list_materials (materials_locations) — they can drift — or when only the movement ledger counts. For history use get_material_movements; for all materials list_inventory / list_materials. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_material_stock"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_material_stock",
  "material_id": 11,
  "location": 1
}'

Example Response

[
  {
    "stock": 67.1985
  }
]

list_inventory

GET /api/inventory. Why: Legacy stock board of one branch: active materials linked to the branch with ledger stock, tenant average cost, unit, low-stock level and stock value. CURRENTLY RETURNS 500 FOR MASTER TENANTS (server count query bug) — for branch stock use list_inventory_movements (current_stock, avg_cost, total_value per material × branch), get_material_stock (one material) or list_materials. No page of the dashboard menu uses it any more. Master tenants: always HTTP 500 "Unknown column 'm.is_active'" (backend bug) — use list_inventory_movements or get_material_stock instead. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_inventory"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_inventory",
  "loc": "example"
}'

Example Response

{
  "data": [
    {
      "id": 120802,
      "name": "Gotcha Recipe",
      "description": null,
      "stock": 9689,
      "physical_stock": 0,
      "price": 2.4616,
      "unit": "Kilogram",
      "low_stock": 0,
      "diff": 9689,
      "total": 23850.44
    }
  ],
  "total": 1
}

get_materials_stats

GET /api/materials/stats. Why: The four header numbers of the dashboard Materials page for a branch scope: total materials, active, recipe materials (rm) and low-stock count (branch stock below low_stock). Quick context before list_materials; for the items themselves use list_materials (and get_material for one). Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_materials_stats"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_materials_stats"
}'

Example Response

{
  "total": 2250,
  "active": 2247,
  "recipes": 902,
  "low_stock": 0
}

list_material_categories

GET /api/inventory/categories. Why: Material category tree of the tenant (top-level categories and their subcategories, max 2 levels; separate from product categories). Use the ids as category_id on create_material / update_material and as `cat` to filter list_materials; pick parents for create_material_category. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_material_categories"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_material_categories"
}'

Example Response

{
  "success": true,
  "data": [
    {
      "id": 2,
      "name": "Farm",
      "description": "",
      "parent_id": null,
      "customer_id": 437,
      "color": "",
      "image": "",
      "is_deleted": 0
    },
    {
      "id": 4,
      "name": "Frozen",
      "description": "",
      "parent_id": null,
      "customer_id": 437,
      "color": "",
      "image": "",
      "is_deleted": 0
    },
    {
      "id": 6,
      "name": "Meat",
      "description": "",
      "parent_id": null,
      "customer_id": 437,
      "color": "",
      "image": "",
      "is_deleted": 0
    },
    {
      "id": 3,
      "name": "Dairy",
      "description": "",
      "parent_id": 2,
      "customer_id": 437,
      "color": "",
      "image": "",
      "is_deleted": 0
    },
    {
      "id": 1,
      "name": "Meat",
      "description": "",
      "parent_id": 2,
      "customer_id": 437,
      "color": "",
      "image": "",
      "is_deleted": 0
    },
    {
      "id": 5,
      "name": "Meat",
      "description": "",
      "parent_id": 4,
      "customer_id": 437,
      "color": "",
      "image": "",
      "is_deleted": 0
    }
  ]
}

get_material_used_in_recipes

GET /api/materials/:id/used-in-recipes. Why: Where-used for one material: every recipe that has it as an ingredient, with the quantity and unit per recipe batch, and the recipe's own output material. Run it before changing units/conversion/yield/cost, deactivating (delete_material) or advising substitutions; then get_recipe for the full recipe and list_products / get_product to see which products and modifier items sell through those recipes (sync_invoice deducts along them). Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_material_used_in_recipes"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_material_used_in_recipes",
  "id": 11
}'

Example Response

{
  "message": "Used-in recipes fetched successfully",
  "data": [
    {
      "recipe_id": 17224,
      "recipe_name": "Gotcha Recipe",
      "yield_qty": 0.782,
      "recipe_unit": "Kilogram",
      "recipe_mode": "stockable",
      "qty": 1000,
      "qty_unit": "Gram",
      "wastage_pct": 0,
      "item_type": "mat",
      "material_id": 120802,
      "material_name": "Gotcha Recipe",
      "material_sku": "mat-437-120802",
      "material_mode": "stockable",
      "material_type": "rm"
    },
    {
      "recipe_id": 16779,
      "recipe_name": "Test",
      "yield_qty": 0.8,
      "recipe_unit": "Kilogram",
      "recipe_mode": "stockable",
      "qty": 500,
      "qty_unit": "Gram",
      "wastage_pct": 0,
      "item_type": "mat",
      "material_id": 119197,
      "material_name": "Test",
      "material_sku": "mat-437-119197",
      "material_mode": "stockable",
      "material_type": "rm"
    }
  ]
}

list_inventory_movements

GET /api/inventory/movements-v3. Why: Stock movement summary (dashboard Inventory → Movement page): one row per material × branch that moved in the date range, with opening stock, totals per movement type (purchased in, transferred in/out, produced, sold, consumed, wasted, adjusted …), closing stock, live current stock, branch average cost and stock value, plus variance between ledger closing and live stock. Use it to answer "how much X came in / went out / is on hand at branch Y" and for stock valuation. Drill into single transactions with get_material_movements (one material) or get_inventory_movements_ledger (all materials). Read only — it never changes stock. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_inventory_movements"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_inventory_movements"
}'

Example Response

{
  "success": true,
  "data": [
    {
      "material_id": 120802,
      "material_name": "Gotcha Recipe",
      "material_unit": "Kilogram",
      "location_id": 907,
      "location_name": "Default location",
      "opening_stock": -111,
      "stock_in": 0,
      "stock_out": 0,
      "transferred_in": 0,
      "transferred_out": 200,
      "transfer_return": 0,
      "consumed": 0,
      "produced": 10000,
      "waste": 0,
      "sold": 0,
      "purchase_return": 0,
      "adjustment_type_in": 0,
      "adjustment_type_out": 0,
      "closing_stock": 9689,
      "current_stock": 9700,
      "avg_cost": 2.4616,
      "total_value": 23877.52,
      "expected_closing_stock": "9689.000",
      "variance": "-11.000",
      "variance_percentage": -0.11
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 3,
    "total": 3,
    "totalPages": 1
  }
}

get_inventory_movements_ledger

GET /api/inventory/movements-ledger. Why: Transaction ledger across materials (dashboard Reports → Movement Report): every stock movement row — sale deductions, purchase receipts, transfers, wastage, count adjustments, work-order consumption/production, returns — with signed quantity, unit cost, value, reference document, user and a running balance per material × branch. Use it to audit what changed stock, by whom and why (filter by branch, materials, movement types, dates). For per-period totals per material use list_inventory_movements; for one material's history get_material_movements. Read only. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_inventory_movements_ledger"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_inventory_movements_ledger"
}'

Example Response

{
  "success": true,
  "data": [
    {
      "id": 12472803,
      "timestamp": "2026-08-12T10:48:20.000Z",
      "material_id": 120802,
      "material_name": "Gotcha Recipe",
      "material_unit": "Kilogram",
      "location_id": 907,
      "location_name": "Default location",
      "movement_type": "transferred_out",
      "quantity_delta": -200,
      "unit_cost": "18.1956",
      "total_value": -3639.12,
      "reference_id": "Stock transfer fe1ecd13-f615-4326-b6a1-482b5353a3c6 - Approved quantity",
      "expiry_date": null,
      "user_id": 4734,
      "recorded_by": "Nexus Cafe",
      "running_balance": 9689
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3290,
    "totalPages": 165
  }
}

get_material_movements

GET /api/inventory/:id/movs. Why: Stock history of ONE material at a branch (dashboard material page History tab and the Movement page drawer): every ledger movement newest first with signed qty, unit cost, reference document, user and brand, plus the material's current stock at that branch on the first row. Use it to explain why a material's stock is what it is. Material id from list_materials; for all materials use get_inventory_movements_ledger, for period totals list_inventory_movements. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_material_movements"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_material_movements",
  "id": 11,
  "location": "example"
}'

Example Response

{
  "data": [
    {
      "id": 12472802,
      "mov_type": "transferred_out",
      "material_id": 119196,
      "qty": -200,
      "price": "11.0136",
      "reference": "Stock transfer fe1ecd13-f615-4326-b6a1-482b5353a3c6 - Approved quantity",
      "created_at": "2026-08-12 10:48:20",
      "expiry_date": null,
      "user_id": 4734,
      "brand_id": null,
      "location_id": 907,
      "location_name": "Default location",
      "brand_name": null,
      "username": "Nexus Cafe",
      "stock": -21387897.14439
    },
    {
      "id": 12472793,
      "mov_type": "in",
      "material_id": 119196,
      "qty": 1000.921387,
      "price": "0.1256",
      "reference": "Supplier Order d39ca7ba-1468-4f0b-855e-94d042731c3f",
      "created_at": "2026-08-04 16:49:29",
      "expiry_date": null,
      "user_id": 4734,
      "brand_id": null,
      "location_id": 907,
      "location_name": "Default location",
      "brand_name": null,
      "username": "Nexus Cafe"
    }
  ],
  "total": 41
}

list_suppliers

GET /api/suppliers. Why: Supplier (vendor) directory of the tenant with per-supplier counters: how many active materials are linked to it (items_in_catalog), how many purchase orders it has (total_orders) and how many are still pending delivery. Use it to find a supplier id before get_supplier / update_supplier / delete_supplier, before reading its price list (list_supplier_materials sup=<id>) or its purchase orders (list_supplier_invoices sid=<id>). Supplier ↔ material links and purchase prices live in list_supplier_materials; material master data in list_materials / get_material. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_suppliers"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_suppliers"
}'

Example Response

[
  {
    "id": 825,
    "name": "Grocery Supplier",
    "description": "Grocery items",
    "customer_id": 437,
    "location_id": 907,
    "address": "Warehouse 4, Al Quoz, Dubai",
    "logo": "",
    "tax_pct": 5,
    "payments": "{\"is_cash\":true,\"is_credit\":false,\"is_cheque\":false}",
    "trade_license": "",
    "contact_name": "Sample Contact",
    "contact_email": "orders@supplier.example",
    "contact_phone": "+971500000001",
    "trn_certificate": "",
    "can_recieve_email": 1,
    "items_in_catalog": 5,
    "total_orders": 7,
    "pending_deliveries": 1
  }
]

list_supplier_materials

GET /api/supplier-materials. Why: A supplier's price list: the materials linked to a supplier at a branch with the supplier's last purchase price (purchase_price) and the material's average cost. Use it to pick material ids and unit prices for draft PO lines (create_draft_purchase_order / update_draft_purchase_order_lines) — the dashboard PO pickers show exactly this list. Supplier ids from list_suppliers, branch ids from list_locations; material details and units via get_material, stock via list_inventory. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_supplier_materials"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_supplier_materials",
  "sup": 1
}'

Example Response

[
  {
    "id": 112157,
    "name": "\t SRC-BT-86CBPR-SG3 BB86-BB92 INTERLOCK SHIMANO CERAMIC COATED BLACK",
    "unit": "Pieces",
    "type": "CEMA BEARINGS",
    "material_type": "mat",
    "mode": "stockable",
    "avg_price": 1.2343,
    "sku": "mat-437-112157",
    "supplier_id": 825,
    "material_id": 112157,
    "purchase_price": 2,
    "brand_ids": []
  },
  {
    "id": 112295,
    "name": " Atx 27.5 In Vibrant Blue",
    "unit": "Pieces",
    "type": "SUN AND SAND SPORTS LLC",
    "material_type": "mat",
    "mode": "stockable",
    "avg_price": 3,
    "sku": "mat-437-112295",
    "supplier_id": 825,
    "material_id": 112295,
    "purchase_price": 3,
    "brand_ids": []
  }
]

list_supplier_invoices

GET /api/supplier-invoices. Why: Purchase-order board of the tenant (the dashboard "Purchase Orders" list): confirmed POs, drafts, partially received and received ones, with supplier snapshot, totals, PO status and supplier response. Use it to find a PO/draft uuid for get_purchase_order and the draft tools, to see a supplier's orders (sid from list_suppliers) or what is still pending delivery. Read-only: approving, sending, receiving and cancelling POs happen only in the dashboard. Stock arrives only when the dashboard receives a PO (then visible in list_inventory / list_inventory_movements). Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_supplier_invoices"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_supplier_invoices"
}'

Example Response

[
  {
    "id": "aa9412cc3eb9",
    "oid": 6187,
    "items_number": 1,
    "subtotal": 12,
    "vat": 0.6,
    "payable": 12.6,
    "discountamount": 0,
    "discountpct": 0,
    "paid": 0,
    "change": 0,
    "note": "",
    "published_date": null,
    "uuid": "52e14591-f11f-430c-8672-aa9412cc3eb9",
    "created_at": "2026-05-19T16:16:14.000Z",
    "customer_id": 437,
    "location_id": 907,
    "info_name": "Faisal Suppliers",
    "info_address": "Industrial Area 2, Sharjah",
    "info_phone": "+971500000003",
    "info_email": "sales@faisal.example",
    "status": "draft",
    "user": "Nexus Cafe",
    "table_id": 881,
    "payment_method": null,
    "your_order_ref": "",
    "supplier_order_ref": "",
    "is_draft": 1,
    "parent_purchase_uuid": "6f6db90f-2a7d-4910-82e9-3a0dae7e6e70",
    "is_archive": 0
  },
  {
    "id": "3a0dae7e6e70",
    "oid": 6180,
    "items_number": 2,
    "subtotal": 10,
    "vat": 0.5,
    "payable": 10.5,
    "discountamount": 0,
    "discountpct": null,
    "paid": null,
    "change": 2,
    "note": "",
    "published_date": "2026-05-19T00:00:00.000Z",
    "uuid": "6f6db90f-2a7d-4910-82e9-3a0dae7e6e70",
    "created_at": "2026-05-19T14:41:09.000Z",
    "customer_id": 437,
    "location_id": 907,
    "info_name": "Grocery Supplier",
    "info_address": "Warehouse 4, Al Quoz, Dubai",
    "info_phone": "+971500000001",
    "info_email": "orders@supplier.example",
    "status": "partially_received",
    "user": "Nexus Cafe",
    "table_id": 825,
    "payment_method": null,
    "your_order_ref": "",
    "supplier_order_ref": null,
    "is_draft": 0,
    "parent_purchase_uuid": null,
    "is_archive": 0
  }
]

list_stock_transfers

GET /api/stock-transfer-invoices. Why: Inter-branch stock transfer board (Inventory → Transfer Request): every transfer between the tenant's branches with status, source/destination branch, transfer_no, value and who requested/approved/dispatched/received it. Use it to find a transfer id for get_stock_transfer (lines, on-hand, history) → update_stock_transfer / update_stock_transfer_items (pending only), to find the transfer you just created with create_stock_transfer (its response has no id), and to answer 'what is in transit / waiting for approval'. Branch ids come from list_locations. Server-side scope: only transfers whose source or destination is in the calling user's allowed branches. Read only — approve/dispatch/receive/complete/reject are dashboard actions. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_stock_transfers"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_stock_transfers"
}'

Example Response

{
  "success": true,
  "message": "Stock transfers fetched successfully",
  "data": {
    "data": [
      {
        "id": 7777,
        "items_number": 2,
        "subtotal": 5841.84,
        "vat": 292.092,
        "payable": 6133.932,
        "discountamount": 0,
        "discountpct": 0,
        "paid": 0,
        "change": 0,
        "note": "",
        "uuid": "fe1ecd13-f615-4326-b6a1-482b5353a3c6",
        "created_at": "2026-08-12T10:48:07.000Z",
        "customer_id": 437,
        "from_location_id": 907,
        "info_name": "Nexus Cafe",
        "info_address": null,
        "info_email": "admin@devnexus.co",
        "info_phone": null,
        "status": "dispatched",
        "user": "Nexus Cafe",
        "table_id": null,
        "payment_method": null,
        "order_id": null,
        "invoice_id": 44,
        "to_location_id": 909,
        "customer_location_id": 907,
        "email": null,
        "delivery_date": null,
        "user_id": 4734,
        "is_edit": null,
        "username": "Nexus Cafe",
        "transfer_no": "STR-2026-01628",
        "requested_by": 4734,
        "approved_by": 4734,
        "dispatched_by": 4734,
        "received_by": null,
        "requested_at": "2026-08-12T10:48:07.000Z",
        "approved_at": "2026-08-12T10:48:16.000Z",
        "dispatched_at": "2026-08-12T10:48:21.000Z",
        "received_at": null,
        "notes": null,
        "priority": null,
        "expected_delivery_date": null,
        "updated_at": "2026-08-12T10:48:20.000Z",
        "rejected_by": null,
        "rejected_at": null,
        "parent_transfer_id": null,
        "from_location": "Default location",
        "to_location": "Iqbal Town",
        "requested_by_username": "Nexus Cafe",
        "approved_by_username": "Nexus Cafe",
        "dispatched_by_username": "Nexus Cafe",
        "received_by_username": null
      }
    ],
    "total": 47,
    "page": 1,
    "limit": "5"
  }
}

list_stock_order_requests

GET /api/stock-order-request. Why: Branch material order requests (Inventory → Order Requests): what a branch asked to buy, per request number REQ-<oid>, with status (Pending / Draft PO Created / Declined), total, item count and the draft PO it became (po_number). Use it to find a request uuid for get_stock_order_request → update_stock_order_request (Pending only), to check a request you created, or to see which requests already have POs (then get_purchase_order). Branch ids from list_locations. Read only — decline / create draft PO are dashboard actions. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_stock_order_requests"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_stock_order_requests"
}'

Example Response

[
  {
    "id": "4338bd97b70a",
    "oid": 13,
    "subtotal": 6000,
    "vat": 300,
    "payable": 6300,
    "change": 0,
    "note": "",
    "uuid": "59c4fb6e-fb85-4ab1-ac0b-4338bd97b70a",
    "delivery_date": "2026-08-06T12:52:39.000Z",
    "created_at": "2026-08-06T12:52:49.000Z",
    "customer_id": 437,
    "to_location_id": 907,
    "to_location": "Default location",
    "customer_location_id": 907,
    "from_location_id": 907,
    "from_location": "Default location",
    "location_name": "Default location",
    "info_name": "Nexus Cafe",
    "info_email": "admin@devnexus.co",
    "status": "Pending",
    "user": "Nexus Cafe",
    "username": "Nexus Cafe",
    "table_id": 0,
    "payment_method": "1",
    "items_count": 1,
    "purchase_uuid": null,
    "po_number": null
  },
  {
    "id": "8cbb626a9d44",
    "oid": 12,
    "subtotal": 125.72,
    "vat": 6.29,
    "payable": 132,
    "change": 0,
    "note": "",
    "uuid": "d5bc4cdc-f6b6-4d04-bdcf-8cbb626a9d44",
    "delivery_date": "2026-08-04T21:48:06.000Z",
    "created_at": "2026-08-04T21:48:44.000Z",
    "customer_id": 437,
    "to_location_id": 907,
    "to_location": "Default location",
    "customer_location_id": 907,
    "from_location_id": 907,
    "from_location": "Default location",
    "location_name": "Default location",
    "info_name": "Nexus Cafe",
    "info_email": "admin@devnexus.co",
    "status": "Draft PO Created",
    "user": "Nexus Cafe",
    "username": "Nexus Cafe",
    "table_id": 0,
    "payment_method": "1",
    "items_count": 1,
    "purchase_uuid": "d39ca7ba-1468-4f0b-855e-94d042731c3f",
    "po_number": "PO-55"
  }
]

list_wastage

GET /api/wastage. Why: Wastage batches (spoiled / expired / damaged stock write-offs) of the tenant with status, reason, cost and creator — the dashboard Wastage page. Use it to find batch ids for get_wastage / update_wastage_draft / delete_wastage_draft and to report waste cost. Read only; the stock-out happens when a batch is approved in the dashboard. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_wastage"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_wastage"
}'

Example Response

{
  "success": true,
  "message": "Wastage batches fetched successfully",
  "data": {
    "data": [
      {
        "id": 29,
        "batch_number": "WB-2026-00029",
        "wastage_reason": "invoice_cancellation",
        "items_count": 1,
        "total_cost": 1.1624,
        "approval_status": "pending",
        "requires_approval": 1,
        "created_by": 4734,
        "approved_by": null,
        "batch_notes": "Auto-created from invoice cancellation — 6CAC39F5-C142-4FF2-8970-DF090FEA68EE",
        "approval_notes": null,
        "location_id": 907,
        "customer_id": 437,
        "submitted_at": "2026-07-01T12:12:18.000Z",
        "approved_at": null,
        "created_at": "2026-07-01T12:12:18.000Z",
        "updated_at": "2026-07-01T12:12:18.000Z",
        "reference_type": "invoice_cancellation",
        "reference_id": "6CAC39F5-C142-4FF2-8970-DF090FEA68EE",
        "brand_id": null,
        "location_name": "Default location",
        "created_by_name": "Nexus Cafe",
        "approved_by_name": null,
        "item_brand_names_csv": null
      },
      {
        "id": 14,
        "batch_number": "WB-2026-00014",
        "wastage_reason": "expired",
        "items_count": 1,
        "total_cost": 5.4144,
        "approval_status": "approved",
        "requires_approval": 1,
        "created_by": 4734,
        "approved_by": 4734,
        "batch_notes": null,
        "approval_notes": null,
        "location_id": 907,
        "customer_id": 437,
        "submitted_at": "2026-04-30T09:16:16.000Z",
        "approved_at": "2026-04-30T14:16:46.000Z",
        "created_at": "2026-04-30T09:16:15.000Z",
        "updated_at": "2026-04-30T09:16:45.000Z",
        "reference_type": "manual",
        "reference_id": null,
        "brand_id": 473,
        "location_name": "Default location",
        "created_by_name": "Nexus Cafe",
        "approved_by_name": "Nexus Cafe",
        "item_brand_names_csv": "Test "
      }
    ],
    "pagination": {
      "total": 4,
      "limit": "5"
    }
  }
}

list_inventory_counts

GET /api/inventory-counts/list. Why: Physical inventory counts (stock-take sessions) of a branch with every line (expected vs counted). Use it to find a count id and its status before get_inventory_count / update_inventory_count_materials / add_inventory_count_item, or to report variances. Read only — approval (which adjusts stock) happens in the dashboard. Count-sheet templates are list_inventory_count_sheets. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_inventory_counts"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_inventory_counts"
}'

Example Response

{
  "status": true,
  "message": "Inventory count list found",
  "data": [
    {
      "id": 477,
      "start_date": "Apr 25, 2026",
      "start_time": "03:41 PM",
      "location_id": 907,
      "name": "Default location - Apr 25, 2026 03:41 PM",
      "type": 0,
      "is_partial": 1,
      "status": "pending",
      "created_at": 1777113069,
      "updated_at": 1777113069,
      "created_by_user_id": 4734,
      "materials": [
        {
          "material_id": 119197,
          "counted_quantity": 10.45,
          "expected_quantity": 0,
          "price": 0.2873,
          "name": "Test"
        }
      ]
    },
    {
      "id": 476,
      "start_date": "Apr 25, 2026",
      "start_time": "03:57 PM",
      "location_id": 907,
      "name": "Default location - Apr 25, 2026 03:57 PM",
      "type": 0,
      "is_partial": 1,
      "status": "approved",
      "created_at": 1777112893,
      "updated_at": 1777112893,
      "created_by_user_id": 4734,
      "materials": [
        {
          "material_id": 119197,
          "counted_quantity": 10.9985,
          "expected_quantity": 0,
          "price": 0.2873,
          "name": "Test"
        }
      ]
    }
  ]
}

get_inventory_count

GET /api/inventory-counts/by-id. Why: One inventory count with every line: line id, material, expected vs counted quantity, price and units. Needed before update_inventory_count_item (line ids), update_inventory_count_materials (full line list) or add_inventory_count_item (check the material is not already on the count), and to report variance. Read only. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_inventory_count"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_inventory_count",
  "id": 11
}'

Example Response

{
  "status": true,
  "message": "Inventory count found",
  "data": [
    {
      "id": 156,
      "start_date": "Mar 03, 2026",
      "start_time": "01:16 PM",
      "location_id": 907,
      "name": "Default location - Mar 03, 2026 01:16 PM",
      "type": 2,
      "is_partial": 0,
      "status": "approved",
      "created_at": 1772524002,
      "updated_at": 1772524002,
      "created_by_user_id": 4734,
      "created_by_user_name": "Nexus Cafe",
      "materials": [
        {
          "id": 1400,
          "material_id": 119196,
          "counted_quantity": 50,
          "expected_quantity": 100,
          "price": 100,
          "name": "Test Material",
          "unit": "Kilogram",
          "ingredientunit": "Gram",
          "conversionrate": "1000"
        }
      ]
    }
  ]
}

list_recipes

GET /api/recipe. Why: Recipe (BOM) catalog of the tenant: name, output yield_qty + unit, mode (phantom | stockable), last computed cost and brand tags. Recipes are tenant-wide (no branch filter). Use it to find recipe ids for get_recipe → update_recipe / delete_recipe, to pick STOCKABLE recipes for create_work_order (mode=stockable), or phantom recipes to link to products (create_product / update_product recipes[]). Ingredient lines, product links and branches are only in get_recipe. A recipe's prepared material (its stock item) is in list_materials (linked_recipe = recipe id). Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_recipes"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_recipes"
}'

Example Response

{
  "message": "Recipes Fetched Successfully",
  "data": [
    {
      "id": 16779,
      "customer_id": 437,
      "name": "Test",
      "yield_qty": 0.8,
      "unit": "Kilogram",
      "version": 1,
      "created_by": 4734,
      "mode": "stockable",
      "sku_no": "rcp-437-16779",
      "unit_id": 2,
      "unit_cost": 50,
      "total_cost": 50,
      "calculation_date": "2026-02-12T13:26:26.000Z",
      "material_count": 2,
      "waste_pct": 0,
      "notes": null,
      "brands": [
        {
          "id": 412,
          "name": "Nexus Cafe"
        },
        {
          "id": 473,
          "name": "Test "
        }
      ]
    }
  ],
  "pagination": {
    "total": 902,
    "page": 1,
    "limit": 1,
    "totalPages": 902
  }
}

get_recipe

GET /api/recipe/:id. Why: One recipe with its ingredient lines (material, qty in ingredient unit, yield override, material cost data), linked products (qty_used), brand tags and the branches of its prepared material. Always call it before update_recipe (update is a full replace) and before create_work_order (the work-order material lines are computed from these lines). Material ids → get_material / list_materials; product ids → get_product; branch ids → list_locations; brand ids → list_brands. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_recipe"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_recipe",
  "id": 11
}'

Example Response

{
  "message": "Recipe Fetched Successfully",
  "data": [
    {
      "id": 16779,
      "customer_id": 437,
      "name": "Test",
      "yield_qty": 0.8,
      "unit": "Kilogram",
      "version": 1,
      "created_by": 4734,
      "mode": "stockable",
      "sku_no": "rcp-437-16779",
      "unit_id": 2,
      "recipe_items": [
        {
          "recipe_id": 16779,
          "material_id": 119196,
          "qty": 500,
          "unit": "Gram",
          "wastage_pct": 0,
          "id": 988201,
          "type": "mat",
          "unit_id": 1,
          "yield_pct": null,
          "name": "Test Material",
          "ingredientunit": "Gram",
          "conversionrate": "1000",
          "avg_price": 22.0271,
          "price": 0
        },
        {
          "recipe_id": 16779,
          "material_id": 119158,
          "qty": 500,
          "unit": "Gram",
          "wastage_pct": 0,
          "id": 988202,
          "type": "mat",
          "unit_id": 1,
          "yield_pct": null,
          "name": "Cherry Blosom",
          "ingredientunit": "Gram",
          "conversionrate": "1000",
          "avg_price": 0.3295,
          "price": 0
        }
      ],
      "product_ids": [
        257508
      ],
      "linked_products": [
        {
          "product_id": 257508,
          "id": 257508,
          "name": "Mocha",
          "qty_used": 1,
          "portion_qty": 0.8,
          "unit": "Kilogram"
        }
      ],
      "brand_ids": [
        412,
        473
      ],
      "location_id": [
        907,
        909,
        908,
        922,
        910,
        1101,
        1102,
        1100,
        1117
      ]
    }
  ]
}

get_material_category

GET /api/inventory/categories/:id. Why: One material category (name, parent, description, image) — load it before update_material_category or to resolve a material's category_id to a name. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_material_category"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_material_category",
  "id": 11
}'

Example Response

{
  "success": true,
  "data": {
    "id": 3,
    "name": "Dairy",
    "description": "",
    "parent_id": 2,
    "customer_id": 437,
    "color": "",
    "image": "",
    "is_deleted": 0
  }
}

get_supplier

GET /api/suppliers/:id. Why: Load one supplier record (all its columns) before update_supplier — the update overwrites every column, so you need the current values to send back — or to show its contact / payment details. Ids come from list_suppliers. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_supplier"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_supplier",
  "id": 11
}'

Example Response

[
  {
    "id": 825,
    "name": "Grocery Supplier",
    "description": "Grocery items",
    "customer_id": 437,
    "location_id": 907,
    "address": "Warehouse 4, Al Quoz, Dubai",
    "logo": "",
    "tax_pct": 5,
    "payments": "{\"is_cash\":true,\"is_credit\":false,\"is_cheque\":false}",
    "trade_license": "",
    "contact_name": "Sample Contact",
    "contact_email": "orders@supplier.example",
    "contact_phone": "+971500000001",
    "trn_certificate": "",
    "can_recieve_email": 1
  }
]

get_purchase_order

GET /api/supplier-invoices/:uuid. Why: Full purchase order or draft: header (supplier snapshot, dates, refs, status, totals, who received/approved), every line with material, unit, qty, requested qty, unit price and line total, plus the branch's business info. Load it before update_draft_purchase_order_lines (you must resend all lines and keep the VAT rate) or delete_draft_purchase_order (check is_draft = 1), and to answer "what's on PO-123". uuid from list_supplier_invoices. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_purchase_order"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_purchase_order",
  "uuid": "example"
}'

Example Response

[
  {
    "id": 6187,
    "items_number": 1,
    "subtotal": 12,
    "vat": 0.6,
    "payable": 12.6,
    "discountamount": 0,
    "discountpct": 0,
    "paid": 0,
    "change": 0,
    "note": "",
    "published_date": null,
    "delivery_date": null,
    "delivery_details": null,
    "uuid": "52e14591-f11f-430c-8672-aa9412cc3eb9",
    "created_at": "2026-05-19T00:00:00.000Z",
    "customer_id": 437,
    "location_id": 907,
    "info_name": "Faisal Suppliers",
    "info_address": "Industrial Area 2, Sharjah",
    "info_phone": "+971500000003",
    "info_email": "sales@faisal.example",
    "status": "draft",
    "user": "Nexus Cafe",
    "table_id": 881,
    "your_order_ref": "",
    "supplier_order_ref": "",
    "supplier_invoice_number": null,
    "supplier_invoice_id": 3,
    "received_by": null,
    "received_at": null,
    "received_by_name": null,
    "approved_by": null,
    "approved_at": null,
    "approved_by_name": null,
    "rejected_by": null,
    "rejected_at": null,
    "rejected_by_name": null,
    "is_draft": 1,
    "parent_purchase_uuid": "6f6db90f-2a7d-4910-82e9-3a0dae7e6e70",
    "order_id": 18,
    "is_archive": 0,
    "parent_order_id": 6180,
    "location_name": "Default location",
    "items": [
      {
        "id": 14292,
        "name": "\t SRC-BT-86CBPR-SG3 BB86-BB92 INTERLOCK SHIMANO CERAMIC COATED BLACK",
        "price": 2,
        "qty": 6,
        "subtotal": 12,
        "purchase_uuid": "52e14591-f11f-430c-8672-aa9412cc3eb9",
        "customer_id": 437,
        "location_id": 907,
        "material_id": 112157,
        "extras": null,
        "custom_price": 2,
        "product_id": null,
        "unit": "Pieces",
        "wastage": null,
        "brand_id": null,
        "requested_qty": 6,
        "remark": null,
        "ingredientunit": "Pieces",
        "brand_name": null
      }
    ],
    "business_info": [
      {
        "id": 9993,
        "value": "Nexus",
        "name": "info_name"
      },
      {
        "id": 9994,
        "value": "Nexus located at Dev",
        "name": "info_address"
      },
      {
        "id": 9995,
        "value": "info@buyer.example",
        "name": "info_email"
      },
      {
        "id": 10237,
        "value": "+971500000009",
        "name": "info_phone"
      },
      {
        "id": 9996,
        "value": "100000000000003",
        "name": "info_vat_no"
      },
      {
        "id": 9997,
        "value": "1762167059218-logo.png",
        "name": "logo_image"
      }
    ]
  }
]

get_wastage

GET /api/wastage/:id. Why: One wastage batch with all its lines (material, qty, unit, cost). Needed before update_wastage_draft (it replaces the whole batch, so resend everything) or delete_wastage_draft (confirm it is still a draft). Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_wastage"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_wastage",
  "id": 11
}'

Example Response

{
  "success": true,
  "message": "Wastage batch fetched successfully",
  "data": [
    {
      "header": {
        "id": 33,
        "batch_number": "WB-2026-00030",
        "wastage_reason": "Customer complaint",
        "items_count": 7,
        "total_cost": 13.2238,
        "approval_status": "pending",
        "requires_approval": 1,
        "created_by": 4734,
        "approved_by": null,
        "batch_notes": "Refund wastage — invoice 79EEB56A-1E47-4DB1-9F24-9234A4FB017E",
        "approval_notes": null,
        "location_id": 907,
        "customer_id": 437,
        "submitted_at": "2026-07-01T13:17:21.000Z",
        "approved_at": null,
        "created_at": "2026-07-01T13:17:20.000Z",
        "updated_at": "2026-07-01T13:17:20.000Z",
        "reference_type": "invoice_refund",
        "reference_id": "79EEB56A-1E47-4DB1-9F24-9234A4FB017E",
        "brand_id": null,
        "location_name": "Default location",
        "created_by_name": "Nexus Cafe",
        "approved_by_name": null
      },
      "items": [
        {
          "id": 121,
          "wastage_batch_id": 33,
          "material_id": 111644,
          "qty": 3,
          "unit": "Pieces",
          "unit_price": 0.4512,
          "total_cost": 1.3536,
          "item_notes": null,
          "customer_id": 437,
          "created_at": "2026-07-01T13:17:20.000Z",
          "brand_id": null,
          "material_name": "[CBSH114I] Caliper Brake Road SHIMANO Ultegra BR-R8000 F/R ",
          "brand_name": null
        },
        {
          "id": 122,
          "wastage_batch_id": 33,
          "material_id": 111649,
          "qty": 3,
          "unit": "Pieces",
          "unit_price": 1.001,
          "total_cost": 3.003,
          "item_notes": null,
          "customer_id": 437,
          "created_at": "2026-07-01T13:17:20.000Z",
          "brand_id": null,
          "material_name": "[CBSH001FI] Caliper Brake Road SHIMANO 105 BR-R7000 IBRR7000AF82XL",
          "brand_name": null
        }
      ]
    }
  ]
}

get_stock_transfer

GET /api/stock-transfer-invoices/:id. Why: One transfer with its lines (material, requested/approved/dispatched/received qty, variance, cost, source on-hand and shortfall), status history, linked draft POs and parent/child re-supply transfers — the dashboard transfer page. Call it before update_stock_transfer / update_stock_transfer_items (status must be pending or draft, and you need items[].id), and to explain where a transfer stands. Ids come from list_stock_transfers; material ids link to get_material / list_materials; on_hand is the source branch stock (same as list_inventory for that branch). Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_stock_transfer"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_stock_transfer",
  "id": 11
}'

Example Response

{
  "success": true,
  "message": "Stock transfer fetched successfully",
  "data": [
    {
      "id": 7772,
      "items_number": 1,
      "subtotal": 1101.36,
      "vat": 55.068,
      "payable": 1156.428,
      "discountamount": 0,
      "discountpct": 0,
      "paid": 0,
      "change": 0,
      "note": "",
      "uuid": "799537a3-c13f-400b-a494-78aeb1a5bd79",
      "created_at": "2026-07-31T06:17:04.000Z",
      "customer_id": 437,
      "from_location_id": 907,
      "info_name": "Nexus Cafe",
      "info_address": null,
      "info_email": "admin@devnexus.co",
      "info_phone": null,
      "status": "completed",
      "user": "Nexus Cafe",
      "table_id": null,
      "payment_method": null,
      "order_id": null,
      "invoice_id": 41,
      "to_location_id": 909,
      "customer_location_id": 907,
      "email": null,
      "delivery_date": null,
      "user_id": 4734,
      "is_edit": null,
      "username": "Nexus Cafe",
      "transfer_no": "STR-2026-01623",
      "requested_by": 4734,
      "approved_by": 4734,
      "dispatched_by": 4734,
      "received_by": 4734,
      "requested_at": "2026-07-31T06:17:05.000Z",
      "approved_at": "2026-07-31T06:17:21.000Z",
      "dispatched_at": "2026-07-31T06:17:25.000Z",
      "received_at": "2026-07-31T06:17:38.000Z",
      "notes": null,
      "priority": null,
      "expected_delivery_date": null,
      "updated_at": "2026-07-31T06:17:45.000Z",
      "rejected_by": null,
      "rejected_at": null,
      "parent_transfer_id": null,
      "from_location": "Default location",
      "to_location": "Iqbal Town",
      "requested_by_username": "Nexus Cafe",
      "approved_by_username": "Nexus Cafe",
      "dispatched_by_username": "Nexus Cafe",
      "received_by_username": "Nexus Cafe",
      "items": [
        {
          "id": 67284,
          "name": "Test Material",
          "price": 11.0136,
          "qty": 100,
          "subtotal": 1101.36,
          "stock_transfer_uuid": "799537a3-c13f-400b-a494-78aeb1a5bd79",
          "location_id": 907,
          "customer_id": 437,
          "material_id": 119196,
          "extras": null,
          "is_edit": "0",
          "approved_qty": 100,
          "dispatched_qty": 100,
          "received_qty": 50,
          "variance_qty": -50,
          "variance_reason": "lost",
          "unit": "Kilogram",
          "unit_id": null,
          "item_status": null,
          "notes": null,
          "created_at": "2026-07-31T06:17:04.000Z",
          "updated_at": "2026-07-31T06:17:37.000Z",
          "stock_transfer_id": null,
          "brand_id": null,
          "disposition_type": null,
          "disposition_status": null,
          "resolved_by": null,
          "resolved_at": null,
          "disposition_notes": null,
          "po_meta": {},
          "purchase_uuid": null,
          "supplier_id": null,
          "supplier_name": null,
          "po_number": null,
          "moved_to_transfer_id": null,
          "moved_to_transfer_no": null,
          "on_hand": -21311072.05389,
          "shortfall": 21311172.05389,
          "resupply_draft_created": true,
          "resupply_draft_transfer_id": 7773,
          "resupply_draft_transfer_uuid": "808adb34-cc06-4c22-93bc-0589f3101788",
          "resupply_draft_transfer_no": "STR-2026-01624",
          "resupply_draft_status": "draft"
        }
      ],
      "history": [
        {
          "id": 9460,
          "stock_transfer_id": 0,
          "changed_by": 4734,
          "changed_at": "2026-07-31T06:17:45.000Z",
          "notes": "Transfer completed",
          "metadata": {
            "user": "Nexus Cafe",
            "action": "complete",
            "status": "completed",
            "old_status": "received"
          },
          "customer_id": 437,
          "stock_transfer_uuid": "799537a3-c13f-400b-a494-78aeb1a5bd79",
          "created_at": "2026-07-31T06:17:45.000Z",
          "changed_by_username": "Nexus Cafe"
        },
        {
          "id": 9458,
          "stock_transfer_id": 0,
          "changed_by": 4734,
          "changed_at": "2026-07-31T06:17:38.000Z",
          "notes": "Variance shortfall draft STR-2026-01624 created and linked to this transfer.",
          "metadata": {
            "user": "Nexus Cafe",
            "action": "variance_draft_created",
            "shortfall_items": 1,
            "child_transfer_id": 7773,
            "child_transfer_no": "STR-2026-01624",
            "child_transfer_uuid": "808adb34-cc06-4c22-93bc-0589f3101788"
          },
          "customer_id": 437,
          "stock_transfer_uuid": "799537a3-c13f-400b-a494-78aeb1a5bd79",
          "created_at": "2026-07-31T06:17:38.000Z",
          "changed_by_username": "Nexus Cafe"
        },
        {
          "id": 9456,
          "stock_transfer_id": 0,
          "changed_by": 4734,
          "changed_at": "2026-07-31T06:17:37.000Z",
          "notes": "Transfer moved from DISPATCHED to RECEIVED. All items received with variance adjustments.",
          "metadata": {
            "user": "Nexus Cafe",
            "action": "move_to_received",
            "new_status": "received",
            "old_status": "dispatched",
            "items_count": 1
          },
          "customer_id": 437,
          "stock_transfer_uuid": "799537a3-c13f-400b-a494-78aeb1a5bd79",
          "created_at": "2026-07-31T06:17:37.000Z",
          "changed_by_username": "Nexus Cafe"
        },
        {
          "id": 9455,
          "stock_transfer_id": 0,
          "changed_by": 4734,
          "changed_at": "2026-07-31T06:17:25.000Z",
          "notes": "Transfer moved from APPROVED to DISPATCHED. Approved quantities copied to dispatched quantities.",
          "metadata": {
            "user": "Nexus Cafe",
            "action": "move_to_dispatched",
            "new_status": "dispatched",
            "old_status": "approved",
            "items_count": 1
          },
          "customer_id": 437,
          "stock_transfer_uuid": "799537a3-c13f-400b-a494-78aeb1a5bd79",
          "created_at": "2026-07-31T06:17:25.000Z",
          "changed_by_username": "Nexus Cafe"
        },
        {
          "id": 9454,
          "stock_transfer_id": 0,
          "changed_by": 4734,
          "changed_at": "2026-07-31T06:17:21.000Z",
          "notes": "Transfer moved from PENDING to APPROVED. All items approved.",
          "metadata": {
            "user": "Nexus Cafe",
            "action": "move_to_approved",
            "new_status": "approved",
            "old_status": "pending",
            "items_count": 1
          },
          "customer_id": 437,
          "stock_transfer_uuid": "799537a3-c13f-400b-a494-78aeb1a5bd79",
          "created_at": "2026-07-31T06:17:21.000Z",
          "changed_by_username": "Nexus Cafe"
        },
        {
          "id": 9453,
          "stock_transfer_id": 0,
          "changed_by": 4734,
          "changed_at": "2026-07-31T06:17:04.000Z",
          "notes": "Stock transfer created",
          "metadata": {
            "user": "Nexus Cafe",
            "action": "create",
            "status": "pending",
            "items_number": 1
          },
          "customer_id": 437,
          "stock_transfer_uuid": "799537a3-c13f-400b-a494-78aeb1a5bd79",
          "created_at": "2026-07-31T06:17:04.000Z",
          "changed_by_username": "Nexus Cafe"
        }
      ],
      "purchase_orders": [],
      "is_auto_created": false,
      "is_variance_draft": false,
      "source_transfer_id": null,
      "source_transfer_no": null,
      "source_transfer_uuid": null,
      "parent_transfer": null,
      "child_transfers": [
        {
          "id": 7773,
          "uuid": "808adb34-cc06-4c22-93bc-0589f3101788",
          "transfer_no": "STR-2026-01624",
          "status": "draft",
          "created_at": "2026-07-31T06:17:38.000Z",
          "parent_transfer_id": 7772
        }
      ],
      "originating_po_uuids": [],
      "originating_po_numbers": [],
      "transfer_meta": {},
      "linked_po_count": 0
    }
  ]
}

get_stock_order_request

GET /api/stock-order-request/:uuid. Why: One order request with its lines (material, qty in storage unit, unit cost, supplier) and the draft PO it produced — the dashboard request detail page. Call it before update_stock_order_request (status must be Pending; you must resend every line). uuids come from list_stock_order_requests; material ids link to get_material, supplier ids to list_suppliers, purchase_uuid to get_purchase_order. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_stock_order_request"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_stock_order_request",
  "uuid": "example"
}'

Example Response

[
  {
    "id": 13,
    "username": "Nexus Cafe",
    "subtotal": 6000,
    "vat": 300,
    "email": null,
    "delivery_date": "2026-08-06T12:52:39.000Z",
    "payable": 6300,
    "change": 0,
    "note": "",
    "uuid": "59c4fb6e-fb85-4ab1-ac0b-4338bd97b70a",
    "reject_reason": null,
    "created_at": "2026-08-06T00:00:00.000Z",
    "customer_id": 437,
    "to_location_id": 907,
    "from_location_id": 907,
    "customer_location_id": 907,
    "info_name": "Nexus Cafe",
    "info_email": "admin@devnexus.co",
    "status": "Pending",
    "user": "Nexus Cafe",
    "table_id": 0,
    "purchase_uuid": null,
    "po_number": null,
    "from_location": "Default location",
    "to_location": "Default location",
    "location_name": "Default location",
    "items": [
      {
        "item_id": 35046,
        "order_uuid": "59c4fb6e-fb85-4ab1-ac0b-4338bd97b70a",
        "material_id": 112157,
        "name": "\t SRC-BT-86CBPR-SG3 BB86-BB92 INTERLOCK-W:86.5/89.5/92XOD:41 SHIMANO-CERAMIC COATED BLACK 4712910901471",
        "price": 3,
        "qty": 2000,
        "subtotal": 6000,
        "unit_name": "Pieces",
        "supplier_id": 881,
        "is_edit": "0",
        "reason": null,
        "old_qty": null,
        "new_qty": null,
        "material_table_id": 112157,
        "material_name": "\t SRC-BT-86CBPR-SG3 BB86-BB92 INTERLOCK-W:86.5/89.5/92XOD:41 SHIMANO-CERAMIC COATED BLACK 4712910901471",
        "material_unit": "Pieces",
        "ingredientunit": "Pieces",
        "storageunit": "Pieces",
        "id": 35046,
        "material": "\t SRC-BT-86CBPR-SG3 BB86-BB92 INTERLOCK-W:86.5/89.5/92XOD:41 SHIMANO-CERAMIC COATED BLACK 4712910901471"
      }
    ],
    "current_location_id": 907,
    "tax": "5.00"
  }
]

list_work_orders

GET /api/work-orders. Why: Production work orders (batches of stockable recipes to produce at a branch) with status, dates, branch, cost totals and a packed summary of their recipe lines. Filter by status, production date range, branch, recipe or text; get ids for get_work_order (lines) → update_work_order / delete_work_order (drafts only). Completed orders are the ones that moved stock (list_inventory_movements, reference WORK_ORDER_<uuid>). Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_work_orders"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_work_orders"
}'

Example Response

{
  "success": true,
  "message": "Work orders fetched successfully",
  "data": {
    "data": [
      {
        "id": 1737,
        "uuid": "66663B01-F720-4574-A3CF-65F6F1F02BB3",
        "public_slug": "8d090ad8-258f-41cd-91ae-ebab74853540",
        "work_order_no": "PRD-2026-01659",
        "status": "completed",
        "production_date": "2026-08-05T00:00:00.000Z",
        "expected_completion": null,
        "created_by": 4734,
        "notes": null,
        "net_total": 23017.9029,
        "location_id": 907,
        "customer_id": 437,
        "created_at": "2026-08-05T07:03:22.000Z",
        "updated_at": "2026-08-05T07:03:58.000Z",
        "total_materials_cost": 23017.9029,
        "total_recipes_cost": 23017.9029,
        "recipes_count": 1,
        "materials_count": 2,
        "recipe_data": "Gotcha Recipe|10000.000000|2.3018|23017.9029",
        "location_name": "Default location",
        "item_brand_names_csv": null
      }
    ],
    "pagination": {
      "total": 29,
      "page": 1,
      "limit": 1
    }
  }
}

get_work_order

GET /api/work-orders/:id. Why: One work order: header (status, dates, branch, notes, creator, QR image), its recipe lines (what is produced, qty in the recipe unit, cost) and material lines (what completion will consume, yield-adjusted qty, price). Call it before update_work_order (full replace) and to explain what completing it will do to stock. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_work_order"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_work_order",
  "id": 11
}'

Example Response

{
  "success": true,
  "message": "Work order fetched successfully",
  "data": [
    {
      "header": {
        "id": 1737,
        "uuid": "66663B01-F720-4574-A3CF-65F6F1F02BB3",
        "public_slug": "8d090ad8-258f-41cd-91ae-ebab74853540",
        "work_order_no": "PRD-2026-01659",
        "status": "completed",
        "production_date": "2026-08-05T00:00:00.000Z",
        "expected_completion": null,
        "created_by": 4734,
        "notes": null,
        "net_total": 23017.9029,
        "location_id": 907,
        "customer_id": 437,
        "qr_png": {
          "type": "Buffer",
          "data": [
            137,
            80,
            78,
            71,
            "…3870 byte values…"
          ]
        },
        "created_at": "2026-08-05T07:03:22.000Z",
        "updated_at": "2026-08-05T07:03:58.000Z",
        "location_name": "Default location",
        "created_by_name": "Nexus Cafe"
      },
      "materials": [
        {
          "id": 23605,
          "work_order_id": 1737,
          "recipe_id": 17224,
          "material_id": 119196,
          "unit": "Gram",
          "qty": 21312872.975277,
          "unit_price": 0.0001,
          "total_price": 2557.5448,
          "customer_id": 437,
          "created_at": "2026-08-05T07:03:22.000Z",
          "material_name": "Test Material",
          "brand_id": null,
          "brand_name": null
        },
        {
          "id": 23606,
          "work_order_id": 1737,
          "recipe_id": 17224,
          "material_id": 119158,
          "unit": "Gram",
          "qty": 12787723.785166,
          "unit_price": 0.0016,
          "total_price": 20460.3581,
          "customer_id": 437,
          "created_at": "2026-08-05T07:03:22.000Z",
          "material_name": "Cherry Blosom",
          "brand_id": null,
          "brand_name": null
        }
      ],
      "recipes": [
        {
          "id": 4470,
          "work_order_id": 1737,
          "recipe_id": 17224,
          "qty": 10000,
          "unit_cost": 2.3018,
          "total_cost": 23017.9029,
          "customer_id": 437,
          "created_at": "2026-08-05T07:03:22.000Z",
          "recipe_name": "Gotcha Recipe"
        }
      ]
    }
  ]
}

list_users

GET /api/users. Why: Staff users (the people who log into the dashboard and the POS) with their role, branches and every per-user POS switch — the admin view of the users table. Admin-only: the key's user must have is_admin 1 or role admin/super, else 401. Use it to get user ids for get_user / update_user / assign_user_role, for sync_invoice created_by_user_id / close_by_user_id and for list_orders_history user_id; role_id links to list_roles, location_id / allow_locations to list_locations, brand_id to list_selling_brands, channel_id to list_selling_channels. For the POS view of the session branch (setting object, devices) use list_pos_users; to change the session user's own POS switches use update_user_permissions; decoded ios_modules / max discount of the session user: get_user_extras. Customers are the CRM tools, not this. Rows carry the clear-text PIN — never show it. Without loc the server lists only the session user's branch (plus multi-branch users); for every user pass loc = comma-separated ids from list_locations. Bare array, no paging. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_users"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_users"
}'

Example Response

[
  {
    "id": 4789,
    "username": "Sara Cashier",
    "email": "sara.cashier@example.com",
    "pin": "0000",
    "role": "staff",
    "role_id": 32,
    "is_admin": 0,
    "location_id": 907,
    "customer_id": 437,
    "allow_locations": "907,909,908",
    "organization_customer_ids": null,
    "organization_id": null,
    "is_daily_report": 0,
    "is_weekly_report": 0,
    "is_monthly_report": 1,
    "modules": "1;1;1;1;1;1;1;1;1;1;1",
    "ios_modules": "1;1;1;1;1;1;1;1;1",
    "can_preview_invoice": 1,
    "max_discount_permit": 26,
    "image": "",
    "permissions": "1;0;1;1;0;0;0;0;1;1;0;0;0;0;0;1;0;0;0;1;0;0;0",
    "print_no_of_times": 1,
    "is_ingredient_disabled": 0,
    "brand_id": 0,
    "channel_id": 0,
    "fraction_digits": 2,
    "dining_guest_count": 0,
    "is_brand_groups": 0,
    "is_extras_enble": 1,
    "display_modifier_titles": 1,
    "modifier_sort_min_required_desc": 1,
    "print_only_save_kds_orders": 1,
    "print_note_on_receipt": 1,
    "orderhistory_print_receipt": 1,
    "show_receipt_screen": 1,
    "order_type": 1,
    "open_dine_in": 0,
    "hide_cart_pay_button": 0,
    "qr_code_on_print_receipt": 0,
    "is_channels_enable": 0,
    "tip_amount": 1,
    "print_void_orders": 0,
    "has_void_order_permission": 1,
    "delivery_detail_enable": 0,
    "is_attributed_receipt": 1,
    "exchange_format": 0,
    "is_cds_enable": null,
    "external_order_print_receipt": 0,
    "is_multi_location_allowed": 1,
    "is_master_locations_enabled": 1,
    "is_qr_payment": 0,
    "is_kds_expeditor": 0,
    "unify_brands": 0,
    "text_receipt": 0,
    "each_category_kds_print": 0,
    "dinein_serving_role": 0,
    "receipt_format": 0,
    "ingredient_stay_standalone": 0,
    "reservation_with_dine_in": 0,
    "pay_zero_amount": 0,
    "receipt_translation": 0,
    "product_translation": 0,
    "category_translation": 0,
    "print_invoice_translation": 0,
    "print_kds_translation": 0,
    "print_deleted_item_on_receipt": 0,
    "draft_order": 0,
    "splitefire": 0,
    "allegy_item": 0,
    "hide_clear_checkout": 1,
    "kds_instruction": 0,
    "pay_default_usd": 1,
    "rpt_business_logo": 1,
    "rpt_order_type": 1,
    "rpt_is_modified": 1,
    "rpt_biller_info": 1,
    "rpt_total_before_vat": 1,
    "rpt_vat_info": 1,
    "rpt_net_total": 1,
    "rpt_exchange_rate": 0,
    "rpt_dine_guest_count": 0,
    "rpt_paid_at": 0,
    "esc_command": 0,
    "one_table_one_order": 0,
    "is_socket_server": 0,
    "is_client": 0,
    "web_local_network_printer": 0,
    "open_price_pincode": 1,
    "is_transfer_enabled": 0,
    "block_print_until_order_open": 0,
    "user_product_sales_counter": 0,
    "is_change_payment_method_enabled": 0,
    "skip_zero_quantity_items": 0,
    "skip_zero_amount_items": 0,
    "settle_wallet_topup": 0,
    "sms_invoice": 0,
    "offline_order_sync": 1,
    "is_shift_management": 0,
    "acknowledge_dine_table_edit": 0,
    "lock_screen": 0,
    "force_crm_user": 0,
    "shift_transactions": 0,
    "eod_shift_report": 0,
    "override_shift": 0,
    "web_image": "",
    "is_crm_mobile_mandatory": 0,
    "reload_dine_order": 0
  }
]

get_user

GET /api/users/:id. Why: One staff user's full record — what the dashboard user edit form loads before update_user: the list_users columns plus language, Zebra printer, cloud-print target, KDS station, is_soldout and the branch currency. Admin-only. Currently fails through MCP (HTTP 500): this route has no Bearer-token auth, it only works with a dashboard login cookie. Use list_users (loc = all branch ids) and pick the row by id instead. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_user"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_user",
  "id": 11
}'

Example Response

[
  {
    "id": 4789,
    "username": "Sara Cashier",
    "email": "sara.cashier@example.com",
    "pin": "0000",
    "role": "staff",
    "role_id": 32,
    "is_admin": 0,
    "location_id": 907,
    "customer_id": 437,
    "allow_locations": "907,909,908",
    "organization_customer_ids": null,
    "organization_id": null,
    "is_daily_report": 0,
    "is_weekly_report": 0,
    "is_monthly_report": 1,
    "modules": "1;1;1;1;1;1;1;1;1;1;1",
    "ios_modules": "1;1;1;1;1;1;1;1;1",
    "can_preview_invoice": 1,
    "max_discount_permit": 26,
    "image": null,
    "permissions": "1;0;1;1;0;0;0;0;1;1;0;0;0;0;0;1;0;0;0;1;0;0;0",
    "print_no_of_times": 1,
    "is_ingredient_disabled": 0,
    "brand_id": 0,
    "channel_id": 0,
    "fraction_digits": 2,
    "dining_guest_count": 0,
    "is_brand_groups": 0,
    "is_extras_enble": 1,
    "display_modifier_titles": 1,
    "modifier_sort_min_required_desc": 1,
    "print_only_save_kds_orders": 1,
    "print_note_on_receipt": 1,
    "orderhistory_print_receipt": 1,
    "show_receipt_screen": 1,
    "order_type": 1,
    "open_dine_in": 0,
    "hide_cart_pay_button": 0,
    "qr_code_on_print_receipt": 0,
    "is_channels_enable": 0,
    "tip_amount": 1,
    "print_void_orders": 0,
    "has_void_order_permission": 1,
    "delivery_detail_enable": 0,
    "is_attributed_receipt": 1,
    "exchange_format": 0,
    "is_cds_enable": null,
    "external_order_print_receipt": 0,
    "is_multi_location_allowed": 1,
    "is_master_locations_enabled": 1,
    "is_qr_payment": 0,
    "is_kds_expeditor": 0,
    "unify_brands": 0,
    "text_receipt": 0,
    "each_category_kds_print": 0,
    "dinein_serving_role": 0,
    "receipt_format": 0,
    "ingredient_stay_standalone": 0,
    "reservation_with_dine_in": 0,
    "pay_zero_amount": 0,
    "receipt_translation": 0,
    "product_translation": 0,
    "category_translation": 0,
    "print_invoice_translation": 0,
    "print_kds_translation": 0,
    "print_deleted_item_on_receipt": 0,
    "draft_order": 0,
    "splitefire": 0,
    "allegy_item": 0,
    "hide_clear_checkout": 1,
    "kds_instruction": 0,
    "pay_default_usd": 1,
    "rpt_business_logo": 1,
    "rpt_order_type": 1,
    "rpt_is_modified": 1,
    "rpt_biller_info": 1,
    "rpt_total_before_vat": 1,
    "rpt_vat_info": 1,
    "rpt_net_total": 1,
    "rpt_exchange_rate": 0,
    "rpt_dine_guest_count": 0,
    "rpt_paid_at": 0,
    "esc_command": 0,
    "one_table_one_order": 0,
    "is_socket_server": 0,
    "is_client": 0,
    "web_local_network_printer": 0,
    "open_price_pincode": 1,
    "is_transfer_enabled": 0,
    "block_print_until_order_open": 0,
    "user_product_sales_counter": 0,
    "is_change_payment_method_enabled": 0,
    "skip_zero_quantity_items": 0,
    "skip_zero_amount_items": 0,
    "settle_wallet_topup": 0,
    "sms_invoice": 0,
    "offline_order_sync": 1,
    "is_shift_management": 0,
    "acknowledge_dine_table_edit": 0,
    "lock_screen": 0,
    "force_crm_user": 0,
    "ios_language": "en",
    "zebra_ip": "",
    "zebra_port": 0,
    "cloud_target_user_id": null,
    "cloud_target_device_id": null,
    "station_id": 0,
    "is_soldout": 0,
    "shift_transactions": 0,
    "eod_shift_report": 0,
    "row_discount": 0,
    "shift_z_report": 0,
    "view_estimated_cash": 0,
    "external_order_ready": 0,
    "currency_code": "AED"
  }
]

list_pos_crm_users

GET /api/v2/crm/users. Why: The customer list the POS cashier picks from to attach a customer to an order — exactly what web-pos loads (page_limit 500, order_by ASC) and caches. Each row carries what checkout needs: id (→ crm_user_id on the order), name, phone, delivery area, the wallet balance and the loyalty program. Customers are tenant-wide (every branch sees the same list). Use it to find/attach a customer; use list_crm_users_details / get_crm_user_details for analytics (visits, segment, wallet history). Paginated: loop current_page until you have total_records rows. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_pos_crm_users"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_pos_crm_users"
}'

Example Response

{
  "status": true,
  "message": "Users found",
  "data": {
    "total_records": 2,
    "records_per_page": 500,
    "current_page": 1,
    "users": [
      {
        "id": 63821,
        "first_name": "Test",
        "last_name": "Customer",
        "mobile_number": "+971500000000",
        "email": "test@example.com",
        "dob": "1990-01-01",
        "customer_id": 437,
        "delivery_area": "Test Area",
        "city": "Test City",
        "country": "Pakistan",
        "is_push_notification_enable": 0,
        "preferred_currency": "USD",
        "latitude": 0,
        "longitude": 0,
        "company_name": "Test Company",
        "thumbnail": "",
        "is_mobile_number_verified": 0,
        "gender": "male",
        "created_at_tz": 1782320919,
        "number_of_purchases": 2,
        "average_basket_size": 11,
        "earn_points": 3,
        "total_spend": 22,
        "trn_number": "100000000000003",
        "loyalty_program_name": "Loyalty 1",
        "redeem_points": 10,
        "redeem_amount": 1,
        "wallet_id": 35,
        "wallet_current_balance": 80,
        "wallet_currency_code": null,
        "wallet_status": "active"
      },
      {
        "id": 64887,
        "first_name": "Second",
        "last_name": "Customer",
        "mobile_number": "+971500000001",
        "email": "second@example.com",
        "dob": null,
        "customer_id": 437,
        "delivery_area": null,
        "city": null,
        "country": null,
        "is_push_notification_enable": 0,
        "preferred_currency": null,
        "latitude": 0,
        "longitude": 0,
        "company_name": null,
        "thumbnail": "",
        "is_mobile_number_verified": 0,
        "gender": null,
        "created_at_tz": 1782747497,
        "number_of_purchases": 0,
        "average_basket_size": 0,
        "earn_points": 0,
        "total_spend": 0,
        "trn_number": null,
        "loyalty_program_name": "Loyalty 1",
        "redeem_points": 10,
        "redeem_amount": 1,
        "wallet_id": null,
        "wallet_current_balance": 0,
        "wallet_currency_code": null,
        "wallet_status": null
      }
    ]
  }
}

list_crm_users

GET /api/crm-users. Why: Dashboard customer (CRM) list — one slim row per customer of the tenant (name, phone, email, company, TRN). Same ids as list_pos_crm_users and the crm_user_id on orders. To attach a customer at the POS use list_pos_crm_users (it has wallet + loyalty); for visits/segments use list_crm_users_details. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_crm_users"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_crm_users"
}'

Example Response

{
  "data": [
    {
      "id": 63821,
      "first_name": "Test",
      "last_name": "Customer",
      "company_name": "Test Company",
      "mobile_number": "+971500000000",
      "earn_points": 0,
      "email": "test@example.com",
      "gender": "male",
      "trn_number": "100000000000003",
      "thumbnail": " "
    },
    {
      "id": 64887,
      "first_name": "Second",
      "last_name": "Customer",
      "company_name": null,
      "mobile_number": "+971500000001",
      "earn_points": 0,
      "email": "second@example.com",
      "gender": null,
      "trn_number": null,
      "thumbnail": null
    }
  ],
  "total_records": 2
}

list_crm_users_details

GET /api/crm-users/details. Why: Dashboard CRM analytics list: every customer column plus an all-time order summary, RFM segment and churn risk per customer, with tenant-wide KPIs. Filters by order date window, branch, channel, spend, visit frequency, inactivity, segment. Sorted by last visit (most recent first, never-ordered last). Use it for marketing/retention questions; use list_pos_crm_users to attach a customer to an order. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_crm_users_details"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_crm_users_details"
}'

Example Response

{
  "status": true,
  "message": "CRM users with detail fetched successfully",
  "data": [
    {
      "id": 63821,
      "first_name": "Test",
      "last_name": "Customer",
      "mobile_number": "+971500000000",
      "email": "test@example.com",
      "dob": "1990-01-01",
      "customer_id": 437,
      "delivery_area": "Test Area",
      "city": "Test City",
      "country": "Pakistan",
      "created_at": "2026-06-24T12:08:39.000Z",
      "gender": "male",
      "preferred_currency": "USD",
      "latitude": 0,
      "longitude": 0,
      "thumbnail": " ",
      "is_mobile_number_verified": 0,
      "is_push_notification_enable": 0,
      "number_of_purchases": 2,
      "average_basket_size": 11,
      "total_spend": 22,
      "earn_points": 0,
      "trn_number": "100000000000003",
      "company_name": "Test Company",
      "summary": {
        "total_spend": 22,
        "visit_count": 2,
        "last_visit": "2026-08-20T11:07:42.000Z",
        "avg_order_value": 11
      },
      "segment": "Needs Attention",
      "churn_risk": "Low"
    },
    {
      "id": 64887,
      "first_name": "Second",
      "last_name": "Customer",
      "mobile_number": "+971500000001",
      "email": "second@example.com",
      "dob": null,
      "customer_id": 437,
      "delivery_area": null,
      "city": null,
      "country": null,
      "created_at": "2026-06-29T10:38:17.000Z",
      "gender": null,
      "preferred_currency": null,
      "latitude": 0,
      "longitude": 0,
      "thumbnail": null,
      "is_mobile_number_verified": 0,
      "is_push_notification_enable": 0,
      "number_of_purchases": 0,
      "average_basket_size": 0,
      "total_spend": 0,
      "earn_points": 0,
      "trn_number": null,
      "company_name": null,
      "summary": {
        "total_spend": 0,
        "visit_count": 0,
        "last_visit": null,
        "avg_order_value": 0
      },
      "segment": "New",
      "churn_risk": null
    }
  ],
  "total_records": 2,
  "kpis": {
    "total_customers": 2,
    "total_revenue": 893,
    "avg_order_value": 49.61,
    "vip_customers": 0,
    "high_churn_risk_customers": 0,
    "avg_visits_per_month": 1.7
  }
}

get_crm_user

GET /api/crm-users/:id. Why: One customer's stored profile (every contact/address field + server-maintained purchase stats). Tenant-checked. For visits, segment and wallet history use get_crm_user_details; for wallet balance and loyalty in POS terms use list_pos_crm_users. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_crm_user"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_crm_user",
  "id": 11
}'

Example Response

[
  {
    "id": 63821,
    "first_name": "Test",
    "last_name": "Customer",
    "company_name": "Test Company",
    "email": "test@example.com",
    "mobile_number": "+971500000000",
    "dob": "1990-01-01",
    "earn_points": 0,
    "customer_id": 437,
    "delivery_area": "Test Area",
    "city": "Test City",
    "is_push_notification_enable": 0,
    "preferred_currency": "USD",
    "trn_number": "100000000000003",
    "latitude": 0,
    "longitude": 0,
    "thumbnail": " ",
    "is_mobile_number_verified": 0,
    "gender": "male",
    "country": "Pakistan",
    "created_at": "2026-06-24T12:08:39.000Z",
    "number_of_purchases": 2,
    "average_basket_size": 11,
    "total_spend": 22
  }
]

get_crm_user_details

GET /api/crm-users/:id/details. Why: Customer intelligence for one customer: profile, all-time order summary, RFM segment, churn risk, value rank, visit patterns (time, days, order types), menu preferences (top items), spending trend, discount usage and the in-house wallet with its last 50 transactions. Tenant-checked. Use it to answer "who is this customer / how are they doing". Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_crm_user_details"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_crm_user_details",
  "id": 11
}'

Example Response

{
  "status": true,
  "message": "CRM user detail fetched successfully",
  "data": {
    "user": {
      "id": 63821,
      "first_name": "Test",
      "last_name": "Customer",
      "mobile_number": "+971500000000",
      "email": "test@example.com",
      "dob": "1990-01-01",
      "customer_id": 437,
      "delivery_area": "Test Area",
      "city": "Test City",
      "country": "Pakistan",
      "created_at": "2026-06-24T12:08:39.000Z",
      "gender": "male",
      "preferred_currency": "USD",
      "latitude": 0,
      "longitude": 0,
      "thumbnail": " ",
      "is_mobile_number_verified": 0,
      "is_push_notification_enable": 0,
      "number_of_purchases": 2,
      "average_basket_size": 11,
      "total_spend": 22,
      "earn_points": 0,
      "trn_number": "100000000000003",
      "company_name": "Test Company"
    },
    "summary": {
      "total_spend": 22,
      "visit_count": 2,
      "last_visit": "2026-08-20T11:07:42.000Z",
      "avg_order_value": 11,
      "visit_frequency": 2
    },
    "segment": "Needs Attention",
    "loyalty_tier": null,
    "churn_risk": "Low",
    "tags": null,
    "notes": null,
    "rfm_score": {
      "recency": 4,
      "frequency": 1,
      "monetary": 1,
      "rfm_segment": "Needs Attention"
    },
    "value_rank": "Mid Value",
    "value_rank_percentile": 50,
    "lifetime_value": 264,
    "visit_patterns": {
      "visit_frequency": 2,
      "preferred_time": "Lunch",
      "first_visit": "2026-08-20T11:07:42.000Z",
      "days_since_last_visit": 35,
      "avg_party_size": 1,
      "table_preference": "0",
      "preferred_days": [
        "Thursday"
      ],
      "order_type_split": {
        "Delivery": 100
      }
    },
    "menu_preferences": {
      "favorite_category": "espresso-based drinks",
      "avg_items_per_order": 1,
      "beverage_food_ratio": "100% beverages",
      "top_ordered_items": [
        "QA min Flat White"
      ],
      "dietary_preferences": null
    },
    "spending": {
      "total_spend": 22,
      "average_order_value": 11,
      "lowest_order": 11,
      "highest_order": 11,
      "lifetime_value": 264,
      "avg_items_per_order": 1,
      "spending_trend": "Decreasing",
      "trend_percentage": -100,
      "trend_label": "-100%"
    },
    "promotions_discounts": {
      "discount_usage_rate": 0,
      "discount_revenue_ratio": 0,
      "promo_responsiveness": 0
    },
    "wallet": {
      "current_balance": 80,
      "transactions": [
        {
          "id": 408,
          "wallet_id": 35,
          "user_id": 63821,
          "transaction_type": "credit",
          "amount": 60,
          "balance_before": 20,
          "balance_after": 80,
          "reference_type": "invoice",
          "reference_id": "8D27D146-767C-4E22-9FB3-0611991DAB63",
          "performed_by_user_id": 4734,
          "source": "invoice-sync-v3",
          "description": "Wallet debit for invoice 8D27D146-767C-4E22-9FB3-0611991DAB63",
          "customer_id": 437,
          "location_id": 907,
          "created_at": "2026-06-29T10:14:55.000Z",
          "payment_id": null,
          "payment_method_name": null
        }
      ]
    }
  }
}

list_roles

GET /api/roles. Why: Roles of the tenant with the permissions each grants — the left list of the dashboard Roles & Permissions page and the Roles dropdown of the user edit form. Use it to pick role_id for update_user / assign_user_role, to read which dashboard pages/actions a user's role (list_users role_id) allows, and to get permission ids for create_role / update_role. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"list_roles"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

No additional parameters — only the Authorization: Bearer header is required.

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "list_roles"
}'

Example Response

{
  "success": true,
  "data": [
    {
      "id": 32,
      "name": "Staff",
      "description": "Default staff role with module group permissions",
      "customer_id": 437,
      "is_deleted": 0,
      "created_at": "2025-09-29T08:05:50.000Z",
      "updated_at": "2025-09-29T08:05:50.000Z",
      "permissions": [
        {
          "id": 1,
          "name": "Manage Inventory Count",
          "value": "Inventory_Count",
          "group": "inventory",
          "sub_group": null,
          "action": null
        },
        {
          "id": 139,
          "name": "Attendance",
          "value": "module_attendance",
          "group": "module_access",
          "sub_group": null,
          "action": null
        },
        {
          "id": 629,
          "name": "Roles",
          "value": "users.roles",
          "group": "Users",
          "sub_group": "Roles",
          "action": null
        },
        {
          "id": 630,
          "name": "Add",
          "value": "users.roles.add",
          "group": "Users",
          "sub_group": "Roles",
          "action": "add"
        }
      ]
    },
    {
      "id": 182,
      "name": "Manager",
      "description": "",
      "customer_id": 437,
      "is_deleted": 0,
      "created_at": "2025-12-13T13:24:49.000Z",
      "updated_at": "2025-12-13T13:24:49.000Z",
      "permissions": [
        {
          "id": 139,
          "name": "Attendance",
          "value": "module_attendance",
          "group": "module_access",
          "sub_group": null,
          "action": null
        },
        {
          "id": 140,
          "name": "Configuration",
          "value": "module_config",
          "group": "module_access",
          "sub_group": null,
          "action": null
        }
      ]
    }
  ]
}

get_role

GET /api/roles/:id. Why: One role with its permissions — read it before update_role (which replaces the permission list) or to explain what a user's role (list_users role_id) lets them do in the dashboard. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"get_role"} when you need field meanings. Safety: read. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "get_role",
  "id": 11
}'

Example Response

{
  "success": true,
  "data": {
    "id": 182,
    "name": "Manager",
    "description": "",
    "customer_id": 437,
    "is_deleted": 0,
    "created_at": "2025-12-13T13:24:49.000Z",
    "updated_at": "2025-12-13T13:24:49.000Z",
    "permissions": [
      {
        "id": 139,
        "name": "Attendance",
        "value": "module_attendance",
        "group": "module_access",
        "sub_group": null,
        "action": null
      },
      {
        "id": 140,
        "name": "Configuration",
        "value": "module_config",
        "group": "module_access",
        "sub_group": null,
        "action": null
      },
      {
        "id": 141,
        "name": "Dashboard",
        "value": "module_dashboard",
        "group": "module_access",
        "sub_group": null,
        "action": null
      }
    ]
  }
}

describe_tool

Full documentation of another tool: every param, every response field with its meaning, the rules (how the POS/dashboard uses it and how it links to other tools), caveats and real examples. Read-only, no SysPOS call. Use it before any write tool and whenever you need to know what a response field means.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "describe_tool",
  "name": "Iced Latte"
}'

Example Response

{
  "message": "JSON body returned by the matching SysPOS API"
}

create_product

POST /api/products. Why: Add a new catalog product (master tenant). Check list_products (k=name) first — duplicate active names are rejected. Get category_id and its name (type) from list_categories, label_id from list_labels, branch ids for location_prices / location_id from list_locations, modifier_id from list_modifiers (item ids from list_modifier_items), channel ids from list_channels, recipe ids from list_recipes (phantom only). For add-ons use create_addon. The new product shows on list_selling_products only at branches listed in location_prices. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"create_product"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "create_product",
  "name": "Iced Latte"
}'

Example Response

{
  "success": true,
  "message": "Product created successfully",
  "productId": 257508
}

update_product

PUT /api/products/:id. Why: Edit one catalog product (name, price, category, branches + branch prices, modifier links, channel prices, BOM, recipes). NOT a patch: first call get_product and resend the whole record with your changes — omitted fields reset prices/image/tax to 0/empty, un-archive the product, wipe materials/recipes and rebuild or reprice branch rows. Same id sources as create_product (list_categories, list_labels, list_locations, list_modifiers, list_channels, list_recipes). Use archive_product to archive/restore, update_product_availability for the POS sold-out switch and delete_product to remove. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"update_product"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "update_product",
  "id": 11
}'

Example Response

{
  "success": true,
  "message": "Product updated successfully",
  "product": {
    "id": "257508",
    "name": "Mocha",
    "actual_price": 12,
    "category_id": 15231,
    "location_prices": [
      {
        "location_id": 907,
        "location_price": 12,
        "is_available": 1
      }
    ],
    "customer_id": 437
  }
}

archive_product

PUT /api/products/archive_product/:id. Why: Hide a product from the active catalog and every branch menu without deleting it (is_archive = 1), or restore it with is_archive="0". Archived products are listed with list_products is_archive=1 and dropped from list_selling_products. Use instead of delete_product when the item may come back; to hide it at one branch use update_product location_prices[].is_available=false, and for a temporary sell-out use update_product_availability. Note: update_product un-archives unless you send is_archive = 1. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"archive_product"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "archive_product",
  "id": 11
}'

Example Response

{
  "message": "Product archived successfully",
  "product": {
    "id": 113573,
    "category_id": 15481,
    "name": "Violet Whispers ",
    "description": null,
    "price": 0,
    "stock": 0,
    "type": "Alternate Options",
    "image": "https://dev1.syspos.ae/api/uploads/KOZ_3276 copy.jpg",
    "customer_id": 437,
    "location_id": [
      null
    ],
    "is_addon": 0,
    "addons": [],
    "bundle_items": [],
    "is_disabled": 0,
    "discount_pct": 0,
    "modifiers": [],
    "is_archive": 1,
    "barcode_type": null,
    "barcode_value": null,
    "is_open_price": 0,
    "is_combo": 0,
    "sync_deliverect": 0,
    "sync_otter": 0,
    "new_cost_date": null,
    "product_cost": null,
    "is_weightage_item": 0,
    "unit_id": 0,
    "actual_price": 0,
    "old_price": null,
    "vat": null,
    "localized": null,
    "base_price": null,
    "menu_sort_order": 0,
    "plu": 1236,
    "calories": null,
    "is_stock_product": 0,
    "is_auto_apply": null,
    "combo_price": 0,
    "localize_name": null,
    "localize_description": null,
    "label_id": null,
    "recipes": [],
    "sku_no": "prod-437-113573",
    "tax_id": null,
    "preparation_time": 0,
    "product_recipe_total": 0,
    "product_material_total": 0,
    "is_overridden": 1,
    "is_deleted": 0,
    "category_sort_order": null,
    "image_path": "KOZ_3276 copy.jpg",
    "web_image": "KOZ_3276 copy.jpg",
    "channel_price": [],
    "materials": [],
    "selectionLength": 0
  }
}

create_category

POST /api/categories. Why: Create a new catalog category (dashboard Add Category) linked to branches. Returns the new id, which you then use as product.category_id (and its name as product.type) in create_product / update_product, and add to a group with update_group so brands with groups show it on the POS. It sells only at the branches in location_id. Check list_categories k=<name> first — duplicate names are not rejected. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"create_category"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "create_category",
  "name": "Iced Latte",
  "location_id": 11
}'

Example Response

{
  "success": true,
  "message": "Category created successfully",
  "category_id": 19250
}

update_category

PUT /api/categories/:id. Why: Edit one catalog category (dashboard Edit Category / row Activate-Deactivate / Grubtech sync screen): rename (product.type follows for products filed under this id), change branches, activate/deactivate, image, colour, sort order, channel sync flags. Deactivating (is_active 0) is the safe alternative to delete_category when products still use it. Call get_category first and send the whole record back — image, is_active, sync_* and menu_sort_order RESET when omitted. Group membership is edited with update_group, not here. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"update_category"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "update_category",
  "id": 11,
  "location_id": 11
}'

Example Response

{
  "name": "Footwear",
  "location_id": [
    909,
    908,
    922,
    910,
    907,
    1131
  ],
  "image": "1767085134601-shoes.jpg",
  "is_active": 1,
  "sync_menu": 1,
  "sync_bitebell": 1,
  "sync_grubtech": 0,
  "sync_otter": 0,
  "sync_deliverect": 0,
  "menu_sort_order": 12,
  "id": "17557"
}

create_modifier

POST /api/modifiers. Why: Create a modifier GROUP (e.g. "Milk") at one or more branches (dashboard Modifiers › Add). Next: add its options with create_modifier_item (modifier_ids [new id], location_ids = the same branches), then link it to products with update_product modifiers[] ({modifier_id, min_allowed, max_allowed, priority, selection_type, default/mandatory item ids}). It reaches the POS (list_selling_modifiers / list_selling_products modifiers[]) only once a product links it. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"create_modifier"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "create_modifier",
  "name": "Iced Latte",
  "location_id": 11
}'

Example Response

{
  "name": "Milk",
  "description": "",
  "location_id": null,
  "customer_id": 437,
  "selection_allowed": 1,
  "selection_min_allowed": 0,
  "priority": 0,
  "localize_name": null,
  "localize_description": null,
  "id": 5701
}

update_modifier

PUT /api/modifiers/:id. Why: Rename a modifier group, change its group defaults / order / translations, or change which branches carry it (dashboard Modifiers › Edit). FULL overwrite: get_modifier first and resend every field; location_id replaces the branch list. Does not touch the group's items (update_modifier_item) or its product links and per-product min/max (update_product modifiers[]). Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"update_modifier"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "update_modifier",
  "id": 11,
  "name": "Iced Latte",
  "location_id": 11
}'

Example Response

{
  "success": true,
  "id": "4417",
  "name": "Milk",
  "description": "",
  "location_id": [
    907,
    908
  ],
  "selection_allowed": 1,
  "selection_min_allowed": 0,
  "priority": 0,
  "localize_name": "حليب",
  "localize_description": ""
}

create_modifier_item

POST /api/modifierItems. Why: Add an option (e.g. "Oat milk" +2.00) to one or more modifier groups at given branches (dashboard Modifier Items › Add). Needs group ids from list_modifiers / create_modifier. Then it shows at the POS under its primary group (list_selling_modifiers) on products that link that group, and its id can be used in update_product modifiers[] default / mandatory / unavailable item lists. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"create_modifier_item"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "create_modifier_item",
  "name": "Iced Latte",
  "modifier_ids": [
    11
  ],
  "location_ids": [
    11
  ]
}'

Example Response

{
  "name": "Oat milk",
  "actual_price": 2,
  "modifier_ids": [
    4417
  ],
  "location_ids": [
    907,
    908
  ],
  "priority": 3,
  "id": 30211,
  "modifier_id": 4417
}

update_modifier_item

PUT /api/modifierItems/:id. Why: Change an option's name, price, order, groups or branches (dashboard Modifier Items › Edit). Read it with get_modifier_item first and resend actual_price, priority, modifier_ids, location_ids and tax_id — omitted ones are reset or replaced. Per-product defaults / availability of the option are set with update_product, not here; the POS sold-out switch for options (update_product_availability itemType MODIFIER_ITEM) only reaches Grubtech. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"update_modifier_item"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "update_modifier_item",
  "id": 11,
  "actual_price": 1,
  "modifier_ids": [
    11
  ],
  "location_ids": [
    11
  ],
  "priority": 1
}'

Example Response

{
  "name": "Oat milk",
  "actual_price": 2.5,
  "modifier_ids": [
    4417
  ],
  "location_ids": [
    907,
    908
  ],
  "priority": 3,
  "tax_id": null,
  "id": "30211",
  "modifier_id": 4417
}

create_brand

POST /api/brands. Why: Create a new brand (dashboard catalog management) on one or more branches, optionally linking existing groups. The new id is what list_selling_brands returns as brand_id and what cart lines/invoices carry. A brand shows categories only through its groups — create groups (create_group) and link them here via brand_groups or later with update_brand. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"create_brand"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "create_brand",
  "brand_name": "example",
  "location_id": 11
}'

Example Response

{
  "success": true,
  "brand_ids": [
    480
  ]
}

update_brand

PUT /api/brands/:id. Why: Edit one brand: name, logo, receipt-header contact fields, branches and linked groups. It is a FULL REPLACE — call get_brand first and resend every field, brand_groups (else all groups are unlinked) and location_id (else branches are reset). Use it to attach/detach groups (and therefore categories) to a brand. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"update_brand"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "update_brand",
  "id": 11,
  "brand_name": "example",
  "location_id": 11
}'

Example Response

{
  "success": true,
  "brand_id": 459
}

create_group

POST /api/groups. Why: Create a group to attach categories to a brand's menu (e.g. "Hot drinks" under brand Nexus Cafe). Pass categories and brand as csv strings and location_id as an array. Produces group_id for get_group / update_group. Catalog management (dashboard) tool. For menu scoping on the POS use list_selling_brands, which already returns each brand's groups with their category ids. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"create_group"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "create_group",
  "group_name": "example",
  "location_id": 11
}'

Example Response

{
  "success": true,
  "group_id": 1486
}

update_group

PUT /api/groups/:id. Why: Rename a group, change its categories, brands or branches. FULL REPLACE — read get_group first and send every field back (categories and brand as csv of ids, location_id as array), or links are wiped. Consumes a group id from list_groups/get_group. Catalog management (dashboard) tool. For menu scoping on the POS use list_selling_brands, which already returns each brand's groups with their category ids. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"update_group"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "update_group",
  "id": 11,
  "group_name": "example",
  "location_id": 11
}'

Example Response

{
  "success": true,
  "message": "Group updated successfully",
  "group_id": "1341"
}

create_addon

POST /api/products. Why: Create a new add-on (products row with is_addon = 1). Set type to the parent category NAMES it is offered with (list_categories) and location_prices to the branches/prices it sells at (list_locations) — without location_prices a master add-on is in no branch and the POS never offers it. Channel prices: price_level (list_channels ids). Produces productId for get_addon / update_addon. Afterwards it shows in list_addons and, at those branches, in list_selling_addons. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"create_addon"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "create_addon",
  "name": "Iced Latte"
}'

Example Response

{
  "success": true,
  "message": "Product created successfully",
  "productId": 271199
}

update_addon

PUT /api/products/:id. Why: Edit an add-on: prices, name, offer list (type = category names from list_categories), branches and per-branch price/availability (location_prices, list_locations ids), channel prices (channel_price, list_channels ids), image. FULL REWRITE — read get_addon first and send every field back. Archive/unarchive only: archive_product is lighter. Sold-out at a branch: update_product_availability, not this tool. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"update_addon"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "update_addon",
  "id": 11,
  "name": "Iced Latte"
}'

Example Response

{
  "success": true,
  "message": "Product updated successfully",
  "product": {
    "id": "257559",
    "name": "Classic Sandwich",
    "description": "",
    "actual_price": 100,
    "price": 95,
    "vat": 5,
    "type": "Alternate Options,Brewed Coffee",
    "image": "",
    "is_addon": 1,
    "location_id": [
      907
    ],
    "location_prices": [
      {
        "location_id": 907,
        "location_price": 100,
        "is_available": 1
      }
    ],
    "customer_id": 437
  }
}

create_label

POST /api/label. Why: Add a product label (dashboard Products → Labels → Add). Check list_labels k=<name> first — duplicates are not rejected on master tenants. Branch ids from list_locations. Then put it on products with create_product / update_product label_id (full product from get_product); when product_unique_formula is "name,label_id" the same product name may exist once per label. Confirm with get_label. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"create_label"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "create_label",
  "name": "Iced Latte",
  "location_id": 11
}'

Example Response

[
  {
    "label": {
      "name": "Coffee beans",
      "description": "",
      "customer_id": 437,
      "location_id": [
        907,
        908
      ],
      "id": 61
    }
  },
  {
    "labels_locations": [
      {
        "id": 5120,
        "label_id": 61,
        "location_id": 907
      },
      {
        "id": 5121,
        "label_id": 61,
        "location_id": 908
      }
    ]
  }
]

update_label

PUT /api/label/:id. Why: Rename a label, change its description or its branch list (dashboard Edit Label). NOT a patch — resend name, description and every branch from list_labels / get_label. Products keep label_id, so a rename shows on list_products, create_product / update_product label pickers and on sold lines (sync_invoice / list_orders_history items[].label_id). Branch ids from list_locations. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"update_label"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "update_label",
  "id": 11,
  "name": "Iced Latte",
  "location_id": 11
}'

Example Response

{
  "label": {
    "id": "50",
    "name": "Coffee Seeds",
    "description": "Whole-bean products",
    "customer_id": 437,
    "location_id": [
      907,
      908,
      909,
      910,
      922,
      1131
    ]
  },
  "message": "Label updated successfully"
}

create_deal

POST /api/deals. Why: Add a fixed-price combo (is_combo 1, type "combo"): a name, a VAT-incl. actual_price, the branches (list_locations) and the choice slots — categories[] { category_id from list_categories, max_allowed }. At the POS the customer picks max_allowed products from each slot category (products whose type equals the category name, list_selling_products); the chosen children are sold as combo_items under one combo parent line in sync_invoice (BUILD 9); a child's combo_price (update_product) adds to its line. Channel prices: price_level with list_channels ids. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"create_deal"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "create_deal",
  "name": "Iced Latte"
}'

Example Response

{
  "name": "Lunch Combo",
  "description": "Burger + side + drink",
  "actual_price": 35,
  "price": 35,
  "discount_pct": 0,
  "location_id": "907",
  "categories": [
    {
      "category_id": 15231,
      "max_allowed": 1
    },
    {
      "category_id": 15240,
      "max_allowed": 2
    }
  ],
  "type": "combo",
  "customer_id": 437,
  "is_addon": false,
  "addons": [],
  "modifier": null,
  "barcode_type": null,
  "barcode_value": null,
  "image": "",
  "is_open_price": null,
  "vat": 0,
  "id": 260001,
  "plu": null
}

update_deal

PUT /api/deals/:id. Why: Edit one deal (price, name, branches, choice slots, channel prices, image). It is a FULL overwrite, not a patch: start from get_deal and resend every value; categories (slots → list_categories ids), location_id (branches → list_locations) and channel_price (list_channels) are fully replaced. Slot changes reach the POS through list_selling_products categories[]; to hide a deal use archive_product, to remove it delete_deal. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"update_deal"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "update_deal",
  "id": 11,
  "name": "Iced Latte",
  "actual_price": 1,
  "price": 1,
  "image": "example",
  "location_id": 11
}'

Example Response

{
  "id": 260001,
  "name": "Lunch Combo",
  "description": "Burger + side + drink",
  "actual_price": 39,
  "price": 39,
  "vat": 0,
  "discount_pct": 0,
  "barcode_type": "",
  "barcode_value": "",
  "image": "1780385109749-combo.png",
  "location_id": "907,908",
  "categories": [
    {
      "category_id": 15231,
      "max_allowed": 1
    },
    {
      "category_id": 15240,
      "max_allowed": 2
    }
  ],
  "channel_price": [
    {
      "channel_id": 12,
      "channel_name": "Talabat",
      "channel_price": 42,
      "channel_vat": 0,
      "channel_actual_price": 42
    }
  ],
  "type": "combo",
  "customer_id": 437
}

create_channel

POST /api/channels. Why: Add a sales channel and assign it to branches. The POS (list_selling_channels) offers it at those branches; per-channel product prices are then set on products (update_product channel_price) and discounts can be limited to it (channel_ids). Check list_channels first — names must be unique. Linkage: a channel id is referenced by list_selling_products data.products[].price_levels[].channel_id (per-channel price, product_channel_price), by orders (channel_id + channel_name, stored verbatim by sync_invoice — web-pos sends 0/""), and by discount codes channel_ids (list_discounts / get_user_extras data.discount_code[]). Branch availability lives in channels_locations (location_id in these tools); master channels have channels.location_id NULL. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"create_channel"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "create_channel",
  "name": "Iced Latte",
  "selected_location_ids": [
    11
  ]
}'

Example Response

{
  "message": "Channel created successfully",
  "data": {
    "name": "Talabat",
    "description": "Delivery app",
    "selected_location_ids": [
      907,
      908
    ],
    "customer_id": 437,
    "id": 516
  }
}

update_channel

PUT /api/channels/:id. Why: Rename a channel, change its description or the branches it is sold on. FULL REPLACE: name and description are both overwritten (omitted → NULL) and the branch list is replaced — call get_channel first and send everything back. Renaming also renames the channel on every product price row (price_levels[].channel_name); old orders keep the old channel_name. Linkage: a channel id is referenced by list_selling_products data.products[].price_levels[].channel_id (per-channel price, product_channel_price), by orders (channel_id + channel_name, stored verbatim by sync_invoice — web-pos sends 0/""), and by discount codes channel_ids (list_discounts / get_user_extras data.discount_code[]). Branch availability lives in channels_locations (location_id in these tools); master channels have channels.location_id NULL. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"update_channel"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "update_channel",
  "id": 11,
  "name": "Iced Latte",
  "selected_location_ids": [
    11
  ]
}'

Example Response

{
  "message": "Channel updated successfully",
  "success": true
}

create_menu

POST /api/menus. Why: Create a named menu: a name plus branches (list_locations), categories (list_categories) and products (list_products) with an optional stored price per product. Menus are dashboard records only: nothing else in SysPOS reads them today. The POS (web-pos) never calls /menus, list_selling_products / list_selling_categories do not look at menus, and the aggregator syncs (Deliverect, Grubtech, Otter, LimeTray) build their menus from categories (sync_* flags, list_categories) and products, not from these menus. Adding or removing a product here does not change what a branch sells; for that use update_product (location_prices) or the category tools. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"create_menu"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "create_menu",
  "name": "Iced Latte",
  "location_id": 11
}'

Example Response

{
  "success": true,
  "message": "Menu created successfully",
  "menu_id": 5,
  "data": {
    "id": 5,
    "name": "Breakfast Menu",
    "description": "Served until noon",
    "currency": "AED",
    "customer_id": 437,
    "location_id": [
      907,
      910
    ],
    "is_active": 1,
    "brand_id": null,
    "label_id": 51,
    "tax_id": null,
    "brand_name": null,
    "label_name": "Coffee beans",
    "tax_name": null,
    "tax_rate": null,
    "categories": [
      {
        "category_id": 15481,
        "category_name": "Alternate Options"
      }
    ],
    "products": [
      {
        "product_id": 247653,
        "category_id": 15481,
        "actual_price": 13,
        "product_name": "Chai",
        "product_type": "Alternate Options"
      }
    ]
  }
}

update_menu

PUT /api/menus/:id. Why: Edit a menu: rename, (de)activate, change branches, categories or products. It is a full replace, not a patch — load get_menu first and send every field back. Menus are dashboard records only: nothing else in SysPOS reads them today. The POS (web-pos) never calls /menus, list_selling_products / list_selling_categories do not look at menus, and the aggregator syncs (Deliverect, Grubtech, Otter, LimeTray) build their menus from categories (sync_* flags, list_categories) and products, not from these menus. Adding or removing a product here does not change what a branch sells; for that use update_product (location_prices) or the category tools. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"update_menu"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "update_menu",
  "id": 11,
  "name": "Iced Latte",
  "location_id": 11
}'

Example Response

{
  "success": true,
  "message": "Menu updated successfully",
  "menu_id": "4",
  "data": {
    "id": 4,
    "name": "classic menu",
    "description": "",
    "currency": "AED",
    "customer_id": 437,
    "location_id": [
      907,
      910,
      922,
      909,
      908
    ],
    "is_active": 1,
    "brand_id": 414,
    "label_id": 51,
    "tax_id": 16,
    "brand_name": null,
    "label_name": "Coffee beans",
    "tax_name": "Food Card Tax",
    "tax_rate": 5,
    "categories": [
      {
        "category_id": 15481,
        "category_name": "Alternate Options"
      }
    ],
    "products": [
      {
        "product_id": 247653,
        "category_id": 15481,
        "actual_price": 13,
        "product_name": null,
        "product_type": null
      }
    ]
  }
}

validate_coupon

POST /api/v2/coupons/validate. Why: Server check of a coupon code before you apply it — what web-pos calls after finding the code in list_selling_coupons. Checks: code exists for the tenant, linked to location_id, is_active = 1, now within start_date/end_date, total usage_limit, per-customer per_user_limit (only if crm_user_id is sent), fixed/percentage discount not larger than order_total (basket mode), and for product-scoped coupons that the basket holds a linked product. Returns the coupon row and, for product-scoped coupons, target_product_id. Does NOT return a discount amount and does NOT consume the coupon (usage is counted when sync_invoice saves the order). No side effects. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"validate_coupon"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "validate_coupon",
  "coupon_code": "example",
  "location_id": 11
}'

Example Response

{
  "status": true,
  "message": "Coupon is valid.",
  "target_product_id": 270965,
  "data": {
    "id": 1001,
    "customer_id": 437,
    "location_id": null,
    "code": "COLDBREW5",
    "description": "5 off Cold Brew",
    "discount_type": "value",
    "discount_value": 5,
    "min_order_value": null,
    "start_date": "2026-09-01T00:00:00.000Z",
    "end_date": "2026-12-31T23:59:59.000Z",
    "usage_limit": 100,
    "per_user_limit": 1,
    "is_active": 1,
    "created_at": "2026-09-01T08:00:00.000Z",
    "updated_at": "2026-09-01T08:00:00.000Z",
    "current_usage": 3,
    "linked_products": [
      {
        "id": 270965,
        "name": "(1) Cold Brew"
      }
    ],
    "user_usage": 0
  }
}

create_coupon

POST /api/coupons. Why: Create a coupon linked to one or more branches, optionally limited to products (list_coupon_products_by_locations) or categories (list_coupon_categories_by_locations) — not both. Send is_active: 1, or the coupon is stored inactive and never validates. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"create_coupon"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "create_coupon",
  "code": "example",
  "discount_type": "example",
  "location_id": 11
}'

Example Response

{
  "status": true,
  "message": "Your coupon has been successfully created with multiple locations.",
  "data": {
    "id": 1001,
    "customer_id": 437,
    "location_id": 907,
    "code": "COLDBREW5",
    "description": "5 off Cold Brew",
    "discount_type": "value",
    "discount_value": 5,
    "min_order_value": null,
    "start_date": "2026-09-01T00:00:00.000Z",
    "end_date": "2026-12-31T23:59:59.000Z",
    "usage_limit": 100,
    "per_user_limit": 1,
    "is_active": 1,
    "created_at": "2026-09-01T08:00:00.000Z",
    "updated_at": "2026-09-01T08:00:00.000Z",
    "current_usage": 0
  }
}

update_coupon

PUT /api/coupons/:id. Why: Change a coupon. Coupon columns are PARTIAL (only the ones you send change), but branch links and product/category links are FULLY REPLACED: always send location_id, and send product_ids or category_ids again (from get_coupon) or they are removed. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"update_coupon"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "update_coupon",
  "id": 11,
  "location_id": 11
}'

Example Response

{
  "status": true,
  "message": "Your coupon has been successfully updated.",
  "data": {
    "id": 1001,
    "customer_id": 437,
    "location_id": 907,
    "code": "COLDBREW5",
    "description": "5 off Cold Brew",
    "discount_type": "value",
    "discount_value": 5,
    "min_order_value": null,
    "start_date": "2026-09-01T00:00:00.000Z",
    "end_date": "2026-12-31T23:59:59.000Z",
    "usage_limit": 200,
    "per_user_limit": 1,
    "is_active": 1,
    "created_at": "2026-09-01T08:00:00.000Z",
    "updated_at": "2026-09-10T08:00:00.000Z",
    "current_usage": 3
  }
}

create_discount

POST /api/discounts. Why: Add a discount (discount code) that web-pos offers in its discount dialog (get_user_extras data.discount_code[]) at the listed branches while active and in date. Not a coupon (create_coupon). Branch ids from list_locations; scope ids: products list_selling_products, categories list_selling_categories, channels list_selling_channels (channel_id), order types list_order_types, payment methods list_selling_payment_methods. Check list_discounts first so the name (= the code cashiers type) is not a duplicate. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"create_discount"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "create_discount",
  "location_id": 11,
  "name": "Iced Latte",
  "start_date": "example",
  "end_date": "example"
}'

Example Response

{
  "status": true,
  "message": "Your discount has been successfully created.",
  "data": {
    "id": 2400,
    "name": "Weekend 10%",
    "discount_percent": 10,
    "max_cap_amount": 50,
    "min_basket_value": 30,
    "location_id": null,
    "is_active": 1,
    "start_date": "2026-10-01T00:00:00.000Z",
    "end_date": "2026-10-31T00:00:00.000Z",
    "discount_type": 0,
    "category_ids": null,
    "apply_discount_to": "entire_basket",
    "product_ids": null,
    "start_time": "00:00:00",
    "end_time": "23:59:00",
    "is_available_on": "friday,saturday,sunday",
    "is_auto_apply": 0,
    "is_promotion": 0,
    "payment_methods": null,
    "channel_ids": null,
    "customer_id": 437,
    "order_type_ids": null,
    "discount_method": "percentage",
    "discount_value": 10
  }
}

update_discount

PUT /api/discounts/:id. Why: Change a discount (discount code): value, scope, branches, dates, active flag. NOT a patch — read the row from list_discounts (loc="All"; get_discount is broken) and send every field again, or the omitted scope/value/time fields are cleared. The change reaches web-pos with its next get_user_extras. Scope ids: list_selling_products, list_selling_categories, list_selling_channels, list_selling_payment_methods, list_order_types; branches list_locations. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"update_discount"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "update_discount",
  "id": 11,
  "location_id": 11
}'

Example Response

{
  "status": true,
  "message": "Your discount has been successfully updated.",
  "data": {
    "id": 2400,
    "name": "Weekend 15%",
    "discount_percent": 15,
    "max_cap_amount": 50,
    "min_basket_value": 30,
    "location_id": null,
    "is_active": 1,
    "start_date": "2026-10-01T00:00:00.000Z",
    "end_date": "2026-10-31T00:00:00.000Z",
    "discount_type": 0,
    "category_ids": null,
    "apply_discount_to": "entire_basket",
    "product_ids": null,
    "start_time": "00:00:00",
    "end_time": "23:59:00",
    "is_available_on": "friday,saturday,sunday",
    "is_auto_apply": 0,
    "is_promotion": 0,
    "payment_methods": null,
    "channel_ids": null,
    "customer_id": 437,
    "order_type_ids": null,
    "discount_method": "percentage",
    "discount_value": 15
  }
}

create_payment_method

POST /api/payment-methods. Why: Add a tender type and enable it at chosen branches. The name becomes the invoice payment_method[] key, so match what cashiers/integrations will send (case-insensitive). Check list_payment_methods (no loc) first — names must be unique across the tenant. Linkage: the payment method NAME is the key in an invoice's payment_method[] (e.g. [{"cash": 30}]) and is matched case-insensitively against the methods linked to the invoice's branch — so renaming or deleting a method changes what the POS can settle with. Branch availability lives in payment_methods_locations (location_id[] in these tools); on master tenants payment_methods.location_id is NULL. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"create_payment_method"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "create_payment_method",
  "name": "Iced Latte",
  "location_id": 11
}'

Example Response

{
  "success": true,
  "message": "Payment method created successfully",
  "data": {
    "name": "Wallet",
    "is_enable": 1,
    "priority": 3,
    "type": "wallet",
    "sync_locations": 1,
    "id": 2140,
    "customer_id": 437,
    "location_id": [
      907,
      908
    ]
  }
}

update_payment_method

PUT /api/payment-methods/:id. Why: Rename, enable/disable, re-prioritise or change the branches of a payment method. FULL REPLACE: name, is_enable, priority, type and sync_locations are all overwritten (omitted → NULL/0), so call get_payment_method first and resend everything. Renaming changes the invoice payment_method[] key — invoices/integrations still sending the old name will no longer match. Linkage: the payment method NAME is the key in an invoice's payment_method[] (e.g. [{"cash": 30}]) and is matched case-insensitively against the methods linked to the invoice's branch — so renaming or deleting a method changes what the POS can settle with. Branch availability lives in payment_methods_locations (location_id[] in these tools); on master tenants payment_methods.location_id is NULL. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"update_payment_method"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "update_payment_method",
  "id": 11,
  "name": "Iced Latte"
}'

Example Response

{
  "success": true,
  "message": "Payment method updated successfully",
  "data": {
    "name": "Wallet",
    "is_enable": 1,
    "priority": 0,
    "type": "wallet",
    "sync_locations": 1,
    "id": "2135",
    "customer_id": 437,
    "location_id": [
      907,
      908,
      909
    ]
  }
}

create_order_type

POST /api/order-type. Why: Add a custom order type for the whole tenant (all branches get it), e.g. "Talabat" behaving as DELIVERY. Its name becomes the order_type string invoices carry, so choose it deliberately. Check list_order_types first — names must be unique per tenant. Order types are tenant-wide (order_type.customer_id) — NOT per branch; every branch sees the same list and there is no loc filter. The order type NAME (order_type here, `title` in GET /api/v2/order-types) is the string stored in an invoice's order_type; order_type_code is the fixed behaviour (DINE_IN / TAKEAWAY / DELIVERY / DRIVE_THRU) the POS uses to decide table/driver/address flow. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"create_order_type"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "create_order_type",
  "order_type": "example",
  "order_type_code": "example",
  "icon_key": "example"
}'

Example Response

{
  "success": true,
  "message": "Order type created successfully",
  "data": {
    "id": 1201,
    "order_type": "Talabat",
    "icon_key": "carbon:delivery",
    "order_type_code": "DELIVERY",
    "is_system_default": 0
  }
}

update_order_type

PUT /api/order-type/:id. Why: Rename a custom order type or change its icon. The 4 system defaults (is_system_default = 1) cannot be edited (403); the behaviour code can never change (delete and recreate instead). Renaming changes the order_type string that NEW invoices carry — old invoices keep the old name, so reports will show both. Send BOTH order_type and icon_key every time (full replace). Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"update_order_type"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "update_order_type",
  "id": 11,
  "order_type": "example",
  "icon_key": "example"
}'

Example Response

{
  "success": true,
  "message": "Order type updated successfully",
  "data": {
    "id": 1201,
    "order_type": "Talabat Delivery",
    "icon_key": "carbon:delivery",
    "order_type_code": "DELIVERY",
    "is_system_default": 0
  }
}

sync_invoice

POST /api/v2/invoice-sync-v3. Why: Create or update a POS order — web-pos 'Pay' / 'Save order' (finalizeSyncPayload). One call = the whole order: header, every line, and (when paid) the tender. New uuid → new order on the session branch with order_no / customer_invoice_id; the same uuid → update of that OPEN order (full resend). status 'open' saves a pay-later / dine order (stock reserved), status 'completed' + is_paid 1 closes a paid sale (payments, stock commit, quota, loyalty, wallet, coupon usage, CRM totals, SMS, KDS push). The server stores the totals as sent — it computes no prices, VAT or totals and validates none of them. Feed it from list_selling_products / list_selling_modifiers / list_selling_addons / list_selling_brands / list_selling_order_types / list_selling_tables / list_pos_crm_users / list_selling_payment_methods, validate_coupon, validate_loyalty_burn and list_product_quota. Read it back with list_orders_history or list_dine_orders; afterwards cancel_invoice, refund_invoice or update_invoice_payment_methods. MCP wraps this one invoice into the array the backend expects. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"sync_invoice"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "sync_invoice",
  "uuid": "example",
  "status": "example",
  "items": [
    11
  ],
  "subtotal": 1,
  "vat": 1,
  "payable": 1
}'

Example Response

{
  "status": true,
  "message": "order saved successfully",
  "data": [
    {
      "id": "5d0b7a6c4e19",
      "oid": 25,
      "customer_invoice_id": 25,
      "items_number": 1,
      "aggregator_order_id": null,
      "exchange_rate": null,
      "paid_in_usd": null,
      "is_wastage": null,
      "is_accepted": null,
      "external_order_ready": 0,
      "is_discount_on_total": null,
      "subtotal": 10.48,
      "vat": 0.52,
      "payable": 11,
      "discountamount": 0,
      "items_discount_amount": 0,
      "is_ticket_available": 1,
      "is_wallet_used": 0,
      "discountpct": 0,
      "paid": 11,
      "change": 0,
      "note": null,
      "uuid": "3f6c1d2a-8b4e-4c7a-9e21-5d0b7a6c4e19",
      "created_at": 1790242200,
      "updated_at": 1790242201,
      "customer_id": 437,
      "location_id": 907,
      "guest_name": "Walk-in",
      "info_name": null,
      "info_address": null,
      "info_phone": null,
      "info_email": null,
      "status": "completed",
      "user": "owner@example.com",
      "table_id": 0,
      "order_id": null,
      "payment_method": [
        {
          "CASH": 11
        }
      ],
      "earn_points": 0,
      "burn_points": 0,
      "burn_points_amount": 0,
      "available_points": 0,
      "available_points_amount": 0,
      "charges_fee": 0,
      "delivery_charges": 0,
      "phone_number": "",
      "loyalty_mobile_number": "",
      "loyalty_mobile_code": "",
      "crm_delivery_area": null,
      "row_discount": 0,
      "invoice_id": null,
      "done_at": null,
      "paid_at": 1790242200,
      "period": null,
      "is_kds_printed": 0,
      "is_invoice_printed": 0,
      "plate_number": null,
      "crm_user_id": 0,
      "crm_user_name": "",
      "order_no": 3,
      "token_number": null,
      "brand_id": null,
      "order_type": "Takeaway",
      "tip_amount": 0,
      "created_by_user_id": null,
      "close_by_user_id": null,
      "modified_by_user_ids": [],
      "channel_id": null,
      "is_vat_on_discount_exclude": 0,
      "discount_id": null,
      "dining_guests": null,
      "channel_name": null,
      "is_paid": 1,
      "discount_reason": null,
      "coupon_id": 0,
      "coupon_amount": 0,
      "coupon_code": null,
      "printed_invoice_receipts": 0,
      "printed_kds_receipts": 0,
      "round": null,
      "rider_pickup_at": null,
      "rider_arrived_at": null,
      "order_type_icon_key": "boxicons:takeaway",
      "notes": [],
      "order_type_icon": "https://images.weserv.nl/?url=https%3A%2F%2Fapi.iconify.design%2Fboxicons%2Ftakeaway.svg%3Fwidth%3D128%26height%3D128&output=png",
      "payment_methods": [
        {
          "CASH": {
            "amount": 11,
            "tip_amount": null
          }
        }
      ],
      "payments": [
        {
          "payment_method": "CASH",
          "amount": 11,
          "tip_amount": 0
        }
      ],
      "items": [
        {
          "id": 25504190,
          "identifier": "9a4f0c3e-6d21-4b8a-8e5f-2c7d1b0a9e44",
          "name": "Flat White",
          "name_localize": null,
          "base_price": null,
          "actual_price": 11,
          "preparation_time": null,
          "price": 11,
          "qty": 1,
          "is_weightage_item": 0,
          "unit_id": 0,
          "subtotal": 11,
          "line_total": null,
          "line_vat": null,
          "line_total_without_vat": null,
          "invoice_uuid": "3f6c1d2a-8b4e-4c7a-9e21-5d0b7a6c4e19",
          "product_id": 257506,
          "extras": null,
          "vat": 0.52,
          "is_updated": 0,
          "updated_qty": 0,
          "is_addon": 0,
          "is_refunded": 0,
          "refund_quantity": 0,
          "refund_reason": null,
          "note": null,
          "addon_linked_with": "9a4f0c3e-6d21-4b8a-8e5f-2c7d1b0a9e44",
          "discount_pct": 0,
          "discount_amount": 0,
          "modifier": [],
          "transferred_to": null,
          "transferred_to_uuid": null,
          "transferred_quantity": null,
          "transferred_to_uuid_list": [],
          "transferred_quantities": [],
          "transfer_recipients": [],
          "created_at": 1790242200,
          "updated_at": 1790242200,
          "is_prepared": null,
          "type": "Espresso-Based Drinks",
          "label_id": 50,
          "item_status": "active",
          "linked_uuid": null,
          "original_linked_uuid": null,
          "disposition_type": null,
          "image": null,
          "is_combo": null,
          "is_deleted": null,
          "deleted_at": null,
          "deleted_qty": null,
          "coupon_amount": 0,
          "coupon_id": 0,
          "coupon_code": "",
          "updated_by_user_ids": [],
          "re": null,
          "ri": 0,
          "is_wastage": 0,
          "discount_id": null,
          "discount_name": null,
          "round": null,
          "combo_items": null
        }
      ]
    }
  ]
}

cancel_invoice

PUT /api/v2/invoice-cancel/:uuid. Why: Void / cancel an order — the web-pos 'Cancel Order' button (order history: status open, opened, completed or partially_refunded) and 'Void Order' on an open dine table. Works on OPEN (unpaid) and COMPLETED (paid) orders. Sets invoices.status = 'cancelled' (the order drops out of sales, list_dine_orders and list_kds_orders), releases or returns the order's stock (master-inventory tenants), books every payment of the order as a cash-out (withdrawal), reverses a wallet payment, gives product-quota units back (list_product_quota), refreshes the CRM customer's totals and tells Grubtech / Limetray / Kiply. It CANNOT be undone and a cancelled order can no longer be refunded or have its payment changed. Use refund_pos_invoice (pending — route not deployed) instead when the sale stands but money (all or some lines) goes back to the guest. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"cancel_invoice"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "cancel_invoice",
  "uuid": "example"
}'

Example Response

{
  "status": true,
  "message": "Order canceled successfully"
}

refund_invoice

POST /api/v2/orders-refund. Why: LEGACY money-only full refund (the iOS route; web-pos does not call it). is_refund=1 marks the whole invoice refunded (invoices.is_refunded = 1 — status stays 'completed') and adds ONE negative payment of the full payable; undo_refund=1 reverses exactly that. No stock, lines, quota, wallet, loyalty or KDS change. Use it only when the user wants the money recorded as refunded without touching stock, or to undo a refund made by this tool. For web-pos parity (status 'refunded'/'partially_refunded', per-line refunds, stock returned or wasted) use refund_pos_invoice (pending — route not deployed). Never use both tools on the same order. Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"refund_invoice"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters

Example Request

curl -X POST https://pos-mcp.syspos.ae/api/call \
  -H "Authorization: Bearer syspos_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "refund_invoice",
  "order_uuid": "example"
}'

Example Response

{
  "status": true,
  "message": "Invoice refunded successfully"
}

update_invoice_payment_methods

PUT /api/v2/invoice/:uuid/payment-methods. Why: Re-book the tender of a PAID order (web-pos 'Change Payment Method' in order history, e.g. the guest paid by card, not cash). REPLACES all payments rows of the order with payment_methods and rewrites invoices.payment_method / paid / change / tip_amount / card_digits (and shift_id). The order total, lines and status do not change. Method names come from list_selling_payment_methods. Logged as an order activity 'Payment Method Updated' (get_invoice_activities). Full guide (every response field, rules, caveats, examples): call describe_tool {"name":"update_invoice_payment_methods"} BEFORE calling this tool. Safety: write. customer_id is taken from the MCP session — do not send it.

Parameters