1. Overview & Architecture
NUQTA exposes API-key-secured customer and transaction endpoints for trusted POS and backend systems. Customers are identified by system LoyaltyID and business MobileNumber. Accumulation and redemption also support a short-lived digital-card QR token through CustomerIdentifier.
The live balance is held in Customer.CurrentBalance and is updated together with the loyalty ledger. Tier placement is based on lifetime accumulation spend, and promotions may add header-level or item-level bonus points.
2. Authentication
All POS endpoints use API-key authentication. The API key must be stored only in trusted backend or POS middleware and must never be embedded in a public mobile app or browser client.
- Send JSON with
Content-Type: application/json. - Include the NUQTA-issued API key in every request.
- Each key maps to a ClientID and optionally a SiteID for store/channel reporting.
3. Customer Endpoints
/API/customer/CheckIfExistChecks whether a customer record exists using the supplied mobile number.
Request
{
"MobileNumber": "0501234567"
}Success response
{
"success": 1,
"message": "Customer Exists",
"loyaltyId": 10234
}Not-found response
{
"success": 0,
"message": "Customer Not Exist"
}/API/customer/GetBalanaceReturns the active customer's points balance, currency equivalent and current tier.
Request
{
"MobileNumber": "0501234567"
}Response
{
"Success": 1,
"Message": "Success",
"LoyaltyID": 10234,
"PointsBalance": 1520,
"CurrencyCode": "AED",
"CurrencyBalance": 15.2,
"TierName": "Gold"
}/API/customer/CreateCreates a customer from POS or back-office. Only MobileNumber is required; optional profile fields may be omitted, allowing a quick POS registration with an incomplete profile that can be completed later.
Request
{
"FirstName": "Sara",
"LastName": "Al Ali",
"MobileNumber": "0501234567",
"Email": "[email protected]",
"CityID": 1,
"AreaID": 5,
"BirthDate": "1995-04-12",
"Gender": 2,
"Address": "Khalifa City, Abu Dhabi"
}Response
{
"Success": 1,
"Message": "Customer Created Successfully",
"LoyaltyID": 10234
}Invalid optional CityID, AreaID, BirthDate or Gender values are ignored rather than failing the request. Welcome points may be created as a separate accumulation transaction when enabled.
/API/customer/GetSummary?mobileNumber=0501234567&page=1&pageSize=50Returns profile, balance, lifetime spend, tier and a paged transaction feed.
Response
{
"Success": 1,
"Message": "Success",
"LoyaltyID": 10234,
"FirstName": "Sara",
"LastName": "Al Ali",
"MobileNumber": "0501234567",
"CurrentBalance": 1520,
"TotalSpend": 8400,
"TierID": 2,
"TierName": "Gold",
"LastAccumulated": "2026-07-20T14:32:00",
"LastRedeemed": "2026-06-15T10:05:00",
"Transactions": [
{
"TransactionID": 98213,
"TransactionType": 1,
"TransactionTypeName": "Accumulation",
"Points": 250,
"Amount": 250,
"ReferenceNumber": "INV-55231",
"Remarks": "Grocery purchase",
"CreatedBy": "POS-01",
"CreatedOn": "2026-07-20T14:32:00"
}
]
}4. Transaction Endpoints
/API/Transactions/AccumelateAwards points after a completed purchase. The customer may be identified by mobile number or digital-card QR token.
Request
{
"CustomerIdentifier": "0501234567",
"Amount": 250,
"ReferenceNumber": "INV-55231",
"Remarks": "Grocery purchase",
"CreatedBy": "POS-01",
"Items": [
{ "ItemID": 4021, "Quantity": 2, "UnitPrice": 45, "LineAmount": 90 },
{ "ItemID": 4110, "Quantity": 1, "UnitPrice": 160, "LineAmount": 160 }
]
}Response
{
"Success": 1,
"Message": "Transaction Created Successfully",
"LoyaltyID": 10234,
"Tier": 2,
"TransactionID": 98213,
"TransactionPoints": 250,
"CurrentBalance": 1520
}/API/Transactions/RedeemConverts points into a currency-value discount and consumes oldest-expiring point buckets first.
Request
{
"CustomerIdentifier": "0501234567",
"InvoiceAmount": 120,
"RedeemAmount": 20,
"ReferenceNumber": "INV-55240",
"Remarks": "Partial redemption at checkout",
"CreatedBy": "POS-01"
}Response
{
"Success": 1,
"Message": "Points Redeemed Successfully",
"LoyaltyID": 10234,
"TransactionID": 98214,
"RedeemedAmount": 20,
"DeductedPoints": 2000,
"CurrentBalance": 1270
}Insufficient balance response
{
"Success": 0,
"Message": "Insufficient Balance",
"CurrentBalance": 1270
}/API/Transactions/CancelCreates a separate cancellation ledger row when a sale is voided or refunded. This endpoint identifies the customer by mobile number.
Request
{
"MobileNumber": "0501234567",
"CancelledAmount": 250,
"ReferenceNumber": "INV-55231-VOID",
"Remarks": "Customer returned items",
"CreatedBy": "POS-01"
}Response
{
"Success": 1,
"Message": "Cancellation Completed Successfully",
"LoyaltyID": 10234,
"ReversedPoints": 250,
"CurrentBalance": 1270,
"CancelTransactionID": 98215
}5. Business Rules Reference
Points accrual
Header mode uses Amount × tier multiplier. Itemized mode sums LineAmount × item multiplier × tier multiplier and skips excluded or unknown items.
Tier promotion
The highest active tier whose minimum spend is met is applied immediately, including the current purchase amount.
Redemption
Required points equal RedeemAmount × points-per-currency rate. Point buckets are consumed by earliest expiry, then oldest creation date.
Negative balance
A negative result is permitted only when both the global loyalty setting and the customer's tier allow it.
Cancellation
A separate TransactionType 5 row is created instead of changing the original transaction.
Promotions
Header and item promotions are added to base points and logged for auditing.
6. Error Handling
Most business validation responses use HTTP 200 with a Success flag and human-readable Message. Integrators must inspect the response body rather than relying only on HTTP status.
Customer identification failure in Accumelate or Redeem is returned as HTTP 400:
{
"Success": false,
"ErrorCode": "CUSTOMER_IDENTIFICATION_FAILED",
"Message": "The mobile number or digital card is invalid."
}