Xilnex API Guide for 3rd party
1. Objective
The objective of this API guide is to provide a clear reference for developers and integration partners on how to utilize the Xilnex APIs to establish communication with the Xilnex system. The guide outlines the available endpoints, required parameters, authentication methods, and usage examples to enable seamless data exchange between Xilnex and external systems.
2. Xilnex API overview
- API url site : https://developers.xilnex.com
Authentication
Any web API call that accesses a resource that requires authentication token in the header. To do this, specify a HTTP header in the following format: *Get your account API token from https://developer.xilnex.com
Sample format for API token
- appid: W1Y0AKP8yrhzduKd3sh51uV2Fwj
- token:i+bpQ+QBHvWybAyMVQndkaxwWPEa6sHw
- auth: 5
*Request authentication API token from Xilnex Team
Idempotency key in API request
The API supports idempotency to prevent performing the same operation twice. This is useful when a POST method API is called but you do not receive a response. For example, when you call the create sales invoice API but does not receive respond due to network connection error or server timeout, you can retry the API request with the same idempotency key to verify whether the sinvoice record already created. Please take note idempotency key validity period is 120min.
To perform an idempotent request, provide an additional Idempotency Key header to the request, as follows:
- appid: W1Y0AKP8yrhzduKd3sh51uV2Fwj
- token:i+bpQ+QBHvWybAyMVQndkaxwWPEa6sHw
- auth: 5
- Idempotency_Key:4aecafe3-04f1-4a0b-bd7c-686ea2822627
3. Sync Product / Item master
The Sync Item API supports synchronization of item master information to ensure consistency and accuracy across all integrated platforms. This includes product details such as item code, product name, description, category classification, pricing structure, product images, unit of measurement (UOM), taxation settings and etc.
By synchronizing this information centrally, the system minimizes data discrepancies, maintains standardized pricing and tax treatment, and ensures that all sales channels operate using the same, up-to-date product information. This improves operational efficiency, reporting accuracy, and integration reliability across systems.
The third-party system must implement a scheduled polling mechanism (for example, every 1 minutes) to call the Sync item API using the last successfully synchronized timestamp as param. The API response will return sitem records with an update timestamp greater than the provided value in the Xilnex item master, allowing the external system to retrieve only newly updated records and perform incremental item synchronization efficiently.
Reference URL : https://developers.xilnex.com/docs/xilnex-developers/1f256df2344ec-sync-items
API end points : https://api.xilnex.com/apps/v2/sync/items
API Action : GET
Usage guides:
- Perform sync Item API for first time with starttimestamp=0x00
- System response item information in partial based on API records limit.
- Capture and save the lastTimestamp returned by API response. (Eg from sample 0x0000000159EBC29F)
- Perform subsequence API call item call with starttimestamp = lasttimestamp from last API call as indication the data is up-to date.
- Repeat the process 3-4 by defined period. eg : every 5mins
|
Plain Text |
|
JSON |
|
Plain Text |
|
JSON |
|
Plain Text |
|
JSON |
4. Client/Customer profile lookup
This API is to identify a loyalty member at the POS and retrieve their current profile and points balance.
API URL: https://developers.xilnex.com/docs/xilnex-developers/5f27fffaeed79-search-client-by-different-parameters
API Endpoint: https://api.xilnex.com/logic/v2/clients/query
API Action: GET
Query Param reference:
|
Field |
Type |
Description |
Example Value |
|
id |
string |
Xilnex Client ID |
9001 |
|
code |
string |
Client Code | member code |
|
|
clientcode |
string |
Client Code | member code |
|
|
|
string |
|
thomas_chin123@gmail.com |
|
ic |
string |
Identity Card Numbers |
991212115144 |
|
mobile |
string |
Client mobile phone number |
60123456789 |
|
name |
string |
Client name |
"Ah Beng" |
Sample Request:
|
JSON |
|
JSON |
5. Create FNB Sales in Xilnex
5.1 Process Flow
5.2 Get Xilnex Store ID
The API supports returning the Xilnex's Location table primary key, which serves as the unique identifier for each outlet/location. This key can be used for accurate store or outlet mapping during system integration and when calling other related APIs such as stock balance retrieval.
5.2.1 Highlighted API mapping info
|
Field |
Description / Usage |
Sample Value |
Remarks |
|
id |
Xilnex Location ID; used for mapping to external system’s store/outlet |
3e2b8a3e31774df4a00cc6976f437883 |
|
|
name |
Store name in Xilnex system |
01 - PENANG |
|
Reference URL : https://developers.xilnex.com/docs/xilnex-developers/64f5bea0aaa33-get-all-outlets
API end points : https://api.xilnex.com/logic/v2/outlets
5.2.2 Sample API Body and Response
|
Plain Text |
|
JSON |
5.3 Get Store Info
The API supports returning comprehensive location master data, including fields such as store code(POS's Store code) , store name, address, tax ID, store group, and other related attributes. These details can be used to facilitate outlet master synchronization and mapping between Xilnex and the external system.
Reference URL :https://developers.xilnex.com/docs/xilnex-developers/df9d8c45da4e6-get-outlet-by-outlet-id
API end points : https://api.xilnex.com/logic/v2/outlets/{id}
API Action : GET
5.3.1 Highlighted API mapping info
|
Field |
Description / Usage |
Sample Value |
Remarks |
|
locationId |
Xilnex Location ID; used for mapping to external system’s store/outlet |
3e2b8a3e31774df4a00cc6976f437883 |
|
|
branchCode |
Merchant's store code maintain is ERP / POS |
PG234 |
|
|
locationName |
01 - PENANG |
Store name for extra validation if needed |
|
5.3.2 Sample API Body and Response
|
Plain Text |
|
SQL |
5.4 Menu Profiles (getMenuProfile) API
Retrieve the list of available menu profiles configured for the selected outlet(s), including the menu setup and availability assigned to each outlet. This API is typically used to identify the applicable menu configuration before order creation and ensure the correct menu items are displayed based on the outlet selection.
API Endpoint : http://api.xilnex.com/logic/v1/menumanager/menuprofiles/{locationid}
API Action : GET
Param: locationId, menuProfileId (optional)
5.4.1 Highlighted API mapping info
|
Field Name |
Data Type |
Format / Allowed Values |
Description |
Example Value |
|
menuProfileID |
Integer |
Numeric ID |
Unique identifier for the menu profile. Auto-generated by the system. |
2708 |
|
menuProfileName |
String |
Free text |
Display name of the menu profile. |
New Profile |
|
locationId |
String |
Numeric string |
The outlet or location this menu profile is assigned to. |
1 |
|
date_Created |
String |
MM/DD/YYYY |
The date the menu profile was created. |
2/8/2019 |
|
bool_IsActivated |
String |
"True" / "False" |
Indicates whether this menu profile is currently active. Only activated profiles will be applied to the POS. |
TRUE |
|
remark |
String |
Free text (optional) |
Optional notes or remarks attached to the menu profile. |
(empty) |
|
timeStart |
String |
HHmmss (24-hour) |
The time from which this menu profile becomes effective each day. 000000 = midnight (start of day). |
0 |
|
timeEnd |
String |
HHmmss (24-hour) |
The time until which this menu profile remains effective each day. 235959 = end of day. |
235959 |
|
dateStart |
String |
MM/DD/YYYY (optional) |
Calendar date from which this profile starts being applied. Leave empty for no start date restriction. |
(empty) |
|
dateEnd |
String |
MM/DD/YYYY (optional) |
Calendar date until which this profile is applied. Leave empty for no end date restriction. |
(empty) |
|
bool_Monday |
String |
"True" / "False" |
Whether this profile is active on Mondays. |
TRUE |
|
bool_Tuesday |
String |
"True" / "False" |
Whether this profile is active on Tuesdays. |
TRUE |
|
bool_Wednesday |
String |
"True" / "False" |
Whether this profile is active on Wednesdays. |
TRUE |
|
bool_Thursday |
String |
"True" / "False" |
Whether this profile is active on Thursdays. |
TRUE |
|
bool_Friday |
String |
"True" / "False" |
Whether this profile is active on Fridays. |
TRUE |
|
bool_Saturday |
String |
"True" / "False" |
Whether this profile is active on Saturdays. |
TRUE |
|
bool_Sunday |
String |
"True" / "False" |
Whether this profile is active on Sundays. |
TRUE |
|
int_Time_Priority |
Integer |
Positive integer |
Priority level when multiple menu profiles overlap in time. Lower value = higher priority. |
2 |
|
int_Extend_1 |
Integer |
Numeric ID |
Extended reference field. Typically mirrors menuProfileID. Reserved for internal system use. |
2708 |
5.4.2 Sample API Body and Response
|
Plain Text |
|
JSON |
5.5 Menu Product (getMenuList)
Retrieve the list of available menu profiles assigned to the selected outlet(s), including the corresponding menu configurations and availability settings. This API enables the application to determine the applicable menus for each outlet, ensuring customers are presented with the correct product offerings, pricing, and menu structure based on the selected store or sales channel.
Param: locationId, menuProfileId (optional)
ORDER SOURCE Reference
LOCAL – Local application / 0
XILNEXFNBGO – Tablet ordering / 1
XILNEXBYODSALES – web Ordering /2
XILNEXKIOSK – Kiosk Ordering /3
XILNEXLIVESALES – 3(rd) party integration , no promo apply /5
XILNEXAPPSALES – Order from loyalty app /6
XILNEXORDERTERMINAL – Local terminal ordering /7
Description: Get product menu from profile
API Endpoint : http://api.xilnex.com/logic/v1/menumanager/menus?locationid={locationid}&menuProfileId={menuProfileId}&source={source}
API Action : GET
5.5.1 Highlighted API mapping info
|
Field Name |
Data Type |
Format / Allowed Values |
Description |
Example Value |
|
menuProfileID |
Integer |
Numeric ID |
Unique identifier for the menu profile. Auto-generated by the system. |
2708 |
|
menuProfileName |
String |
Free text |
Display name of the menu profile. |
New Profile |
|
locationId |
String |
Numeric string |
The outlet or location this menu profile is assigned to. |
1 |
|
date_Created |
String |
MM/DD/YYYY |
The date the menu profile was created. |
2/8/2019 |
|
bool_IsActivated |
String |
"True" / "False" |
Indicates whether this menu profile is currently active. Only activated profiles will be applied to the POS. |
TRUE |
|
remark |
String |
Free text (optional) |
Optional notes or remarks attached to the menu profile. |
Special Profile for new year |
|
timeStart |
String |
HHmmss (24-hour) |
The time from which this menu profile becomes effective each day. 000000 = midnight (start of day). |
00 |
|
timeEnd |
String |
HHmmss (24-hour) |
The time until which this menu profile remains effective each day. 235959 = end of day. |
235959 |
|
dateStart |
String |
MM/DD/YYYY (optional) |
Calendar date from which this profile starts being applied. Leave empty for no start date restriction. |
01/01/2026 |
|
dateEnd |
String |
MM/DD/YYYY (optional) |
Calendar date until which this profile is applied. Leave empty for no end date restriction. |
01/01/2026 |
|
bool_Monday |
String |
"True" / "False" |
Whether this profile is active on Mondays. |
TRUE |
|
bool_Tuesday |
String |
"True" / "False" |
Whether this profile is active on Tuesdays. |
TRUE |
|
bool_Wednesday |
String |
"True" / "False" |
Whether this profile is active on Wednesdays. |
TRUE |
|
bool_Thursday |
String |
"True" / "False" |
Whether this profile is active on Thursdays. |
TRUE |
|
bool_Friday |
String |
"True" / "False" |
Whether this profile is active on Fridays. |
TRUE |
|
bool_Saturday |
String |
"True" / "False" |
Whether this profile is active on Saturdays. |
TRUE |
|
bool_Sunday |
String |
"True" / "False" |
Whether this profile is active on Sundays. |
TRUE |
|
int_Time_Priority |
Integer |
Positive integer |
Priority level when multiple menu profiles overlap in time. Lower value = higher priority. |
2 |
|
int_Extend_1 |
Integer |
Numeric ID |
Extended reference field. Typically mirrors menuProfileID. Reserved for internal system use. |
2708 |
5.5.2 Sample API Body and Response
|
Plain Text |
|
JSON |
5.6 Fnb Sales Calculate
The F&B Orders API is used to pre-calculate the sales transaction by validating and computing item pricing, taxes, discounts, service charges, and voucher deductions before payment confirmation. This API ensures accurate order amount calculation and provides the final payable total prior to order completion and submission to the POS for food preparation processing.
Reference URL :https://developers.xilnex.com/docs/xilnex-developers/620d379026f00-calculate-fn-b-sales
API end points : https://api.xilnex.com/logic/v2/sales/fnbOrders/total
5.6.1 Highlighted API mapping info
The following fields are mandatory in every sales submission request. The POS Vendor must map these from the POS transaction record at the time of checkout completion.
Sales Item
Modifiers
Modifiers — For F&B items that carry customisations (e.g. size, sugar level, add-ons), the POS system must populate the modifiers array nested within each salesItems entry. Each modifier carries the same field structure as a sales item. The quantity, price, and subTotal of the modifier must reflect the add-on's own value, not the parent item's value.
Voucher Collection
5.6.2 Sample API Body and Response
|
JSON |
|
JSON |
5.7 Order Injection for Fnb Sales
The FNB Orders API is used to create sales in Xilnex. However, to fully complete the transaction, you must also call the Payment API to process the total sales amount.
Reference URL : https://developers.xilnex.com/docs/xilnex-developers/f747a416a6167-fn-b-orders
API end points : https://api.xilnex.com/logic/v2/sales/fnbOrders
5.7.1 Highlighted API mapping info
The following fields are mandatory in every sales submission request. The POS Vendor must map these from the POS transaction record at the time of checkout completion.
Sales Item
Modifiers
Modifiers — For F&B items that carry customisations (e.g. size, sugar level, add-ons), the POS system must populate the modifiers array nested within each salesItems entry. Each modifier carries the same field structure as a sales item. The quantity, price, and subTotal of the modifier must reflect the add-on's own value, not the parent item's value.
5.7.2 Sample Body And response
Sample Json:
|
JSON |
Response:
|
JSON |
Member-related fields:
Click the image to view the sheet.
For non-member transactions, customerId, customerName, xCard, and customerAltLookUp must be submitted as null or omitted.
Additional Information
By default, the Xilnex API auto-calculates sales. To override this automatic calculation and submit manual sales data, you must include the X-Origin custom header in your API request:
X-Origin: https://api-wrapper.azurewebsites.net
5.8 FnB Order payment API
This API is used to finalize a sales transaction by capturing and posting the payment details against the order. Once the payment is successfully recorded, the system marks the order as completed and automatically pushes the order to the POS for food preparation processing.
Reference URL : https://xilnex.stoplight.io/docs/xilnex-developers/cc7b914067441-post-payment-tips-and-complete-sales
API end points : https://api.xilnex.com/logic/v2/sales/paymentsv2
5.8.1 Highlighted API mapping info
|
Field Name |
Data Type |
Format / Allowed Values |
Description |
Example Value |
|
DOUBLE_Amount |
Float |
Decimal (2 d.p.) |
Payment amount tendered for this transaction. |
50 |
|
Method |
String |
"Cash" / "Card" / "eWallet" / "Voucher" / "Points" |
Payment method used for the transaction. |
Card |
|
Reference |
String |
Free text |
Primary payment reference. For card payments, this is the masked card number. |
card number |
|
STRING_EXTEND_1 |
String |
Free text |
Extended reference field 1. For card payments, this stores the approval code returned by the payment terminal. |
approval code |
|
STRING_EXTEND_2 |
String |
Free text |
Extended reference field 2. For card payments, this stores the card type (e.g. Visa, Mastercard). |
card type |
|
Reference_3 |
String |
Free text |
Extended reference field 3. For card payments, this stores the credit card expiry date. |
credit card expiry |
|
Reference_4 |
String |
Free text |
Extended reference field 4. For card payments, this stores the trace number from the payment terminal. |
trace no |
|
Received_By |
String |
Email address |
Email address of the cashier / user account that received this payment. |
|
|
Received_By_Cashier_Name |
String |
Free text |
Display name of the cashier who processed this payment. |
Wondercafe |
|
Location_ID |
String |
UUID / alphanumeric hash |
Unique identifier of the outlet or location where the payment was collected. |
4624401e8fa846579ac81adfc826f4cd |
|
Remark |
String |
Free text (optional) |
Optional remarks or notes attached to this payment record. |
remark |
|
Invoice_ID |
String |
Numeric string |
The invoice or bill number this payment is linked to. |
900272 |
5.8.2 Sample Body And response
By Cash Payment
|
JSON |
By Cash Response:
|
JSON |
By Credit Card Payment
|
JSON |
By E-Wallet Payment
|
JSON |
By Voucher Payment
|
JSON |
By Other Payment
|
JSON |
Mix Payment
|
JSON |
Mix Payment Response:
|
JSON |
Related Articles
Basic - Xilnex Support Help Center
1.0 Xilnex Support Help Center Welcome to the Xilnex Support Help Center – your one-stop destination for comprehensive resources, including our Knowledge Base, FAQs, and a seamless way to sign up and submit support tickets to our team. 2.0 Sign Up If ...Basic - How to change Xilnex Currency
Checking current currency Open Control Panel Go to Clock and Region On Region click on additional settings Click on Currency tab The currency will be shown on Currency symbol field Change Xilnex currency On the same Currency symbol field click on the ...Basic - How to enable E-Receipt Portal and QR Code Setup on Printing format in Xilnex
Enable E-Receipt Portal Enable the E-receipt functionality Once Enabled, you will be getting the E-Receipt portal link Continue under Theme & Styling, enabled for the E-Invoice (LHDN) You can customize the look and feel of the E-Receipt portal ...Basic - How to check Missing Foodpanda and Grabfood Orders via Xilnex Portal
1. Login to Xilnex portal 2. Navigate to the page: Integration > Integration Log > Integration Log Headers. Alternatively, use the search function for quicker access. (Please grant permission if your account does not have access to this module) 3. ...Basic - How To enabling E-Invoicing Module
Introducing the Xilnex Portal - Malaysia LHDN E-Invoicing The Xilnex Portal is the central platform where all configurations and settings for your system can be managed. Designed for flexibility and ease of use, the portal allows you to set up, ...
Recent Articles
Cancel Print of Full Tax Invoice
Overview In Classic POS, there is a feature called Print Full Tax Invoice, which allows users to generate a full tax invoice for a completed sale. The system must maintain an auditable log whenever a Full Tax Invoice is cancelled. This guideline ...Xilnex API Guide for 3rd party
1. Objective The objective of this API guide is to provide a clear reference for developers and integration partners on how to utilize the Xilnex APIs to establish communication with the Xilnex system. The guide outlines the available endpoints, ...Enabling On The Move 1.0 Access Permission (OTM1.0)
Overview This guide explains how to enable access for users who need to use On The Move 1.0 (OTM 1.0). For OTM 1.0, only one permission is required: Allow to access on the move If this permission is not enabled for the user's assigned user group, the ...Available Events: Xilnex Event Hub
Last Updated: 05 May 2026 Sales # Event Name 1 Create Sales 2 Confirm Sales 3 Confirm Sales v2 4 Complete Sales 5 Complete Sales v2 6 Cancel Sales 7 Update Sales 8 Cancel Sales Order 9 Confirm Sales Order 10 Complete Sales Order 11 Post Quotation to ...Integrating with Xilnex: Event Triggers & Webhook Configuration
Overview Xilnex Event Hub is an integration framework that enables your system to automatically dispatch real-time notifications to external applications whenever a defined business action occurs — such as completing a sale, creating a client, or ...
Popular Articles
Basic - How to create a voucher-coupon
Voucher and coupon definition Voucher can be generated in bulk and can be used once Coupon can only be created one at a time (reusable code) and can be use multiple times Pre-voucher / coupon setup There are 2 things need to be prepared before we can ...Understanding DuitNow QR Payment in ClassicPOS
Introduction This document introduces the DuitNow QR payment feature available in the Xilnex Retail POS, enabling merchants to accept payments conveniently through Malaysia's national QR payment standard. The integration of DuitNowQR simplifies the ...Basic - How to change custom cost to another branch that don’t have custom cost
Change custom cost to another branch that don’t have custom cost 1. Get the item list from the location with custom cost (Item Code, Name, Custom Cost) 2. Make sure the Show Location Price are selected 3. Export the item list in Excel 4. The file ...Intermediate - How to Bill & Post to Sales from Transfer Note
1.0 Purpose A bill is required from transfer note when an inventory transfer involves financial transactions, cost allocation, or compliance with tax and accounting regulations. It is used when stock is moved between outlets that operate as separate ...Basic - How to enable E-Receipt Portal and QR Code Setup on Printing format in Xilnex
Enable E-Receipt Portal Enable the E-receipt functionality Once Enabled, you will be getting the E-Receipt portal link Continue under Theme & Styling, enabled for the E-Invoice (LHDN) You can customize the look and feel of the E-Receipt portal ...