Skip to main content
The Settings API provides endpoints for managing system configuration, tax settings, and administrative functions.

​
System settings

​
Get system settings

Retrieve current system settings. 
GET /api/system-settings

​
Response

​
id
integer
Settings ID
​
dateFormat
string
Date format for display
​
receiptHeaderText
string
Header text for receipts
​
receiptFooterText
string
Footer text for receipts
​
printReceiptAutomatically
boolean
Auto-print receipts after sale
​
theme
string
UI theme preference
​
autoLogoutMinutes
integer
Minutes of inactivity before auto-logout
​
enableReturns
boolean
Whether returns are enabled
​
returnTimeLimitDays
integer
Maximum days after sale to allow returns
​
requireManagerApprovalForReturns
boolean
Require manager approval for all returns
​
returnManagerApprovalAmount
decimal
Minimum return amount requiring manager approval
​
restockReturnedItems
boolean
Automatically restock items in good condition

​
Create or update system settings

Update system settings. If no settings exist, creates default settings. 
POST /api/system-settings

​
Request body

​
dateFormat
string
Date format
​
receiptHeaderText
string
Receipt header
​
receiptFooterText
string
Receipt footer
​
printReceiptAutomatically
boolean
Auto-print setting
​
theme
string
Theme preference
​
autoLogoutMinutes
integer
Auto-logout timeout
​
enableReturns
boolean
Enable/disable returns
​
returnTimeLimitDays
integer
Return time limit
​
requireManagerApprovalForReturns
boolean
Manager approval requirement
​
returnManagerApprovalAmount
decimal
Approval amount threshold
​
restockReturnedItems
boolean
Auto-restock setting

​
Example request

curl -X POST "https://api.example.com/api/system-settings" \
  -H "Content-Type: application/json" \
  -H "X-User-Id: 1" \
  -H "X-User-Name: Admin" \
  -d '{
    "dateFormat": "YYYY-MM-DD",
    "receiptHeaderText": "Thank you for shopping with us!",
    "receiptFooterText": "Visit us again soon",
    "printReceiptAutomatically": true,
    "theme": "light",
    "autoLogoutMinutes": 30,
    "enableReturns": true,
    "returnTimeLimitDays": 30,
    "requireManagerApprovalForReturns": false,
    "returnManagerApprovalAmount": 100.00,
    "restockReturnedItems": true
  }'
Upload a logo for receipts (BMP format for thermal printers). 
POST /api/system-settings/upload-logo

​
Request body

Multipart form data with file upload.
Logo file (BMP format, max 2MB)

​
Example request

curl -X POST "https://api.example.com/api/system-settings/upload-logo" \
  -H "Content-Type: multipart/form-data" \
  -F "logo=@/path/to/logo.bmp"

​
Get business time

Get the current business time (UTC). 
GET /api/system-settings/business-time

​
Tax settings

​
Get tax settings

Retrieve current tax configuration. 
GET /api/tax-settings

​
Response

​
id
integer
Settings ID
​
businessName
string
Business name
​
taxNumber
string
Tax registration number
​
businessAddress
string
Business address
​
enableTax
boolean
Whether tax is enabled
​
taxName
string
Primary tax name (e.g., “Sales Tax”)
​
taxRate
decimal
Primary tax rate percentage
​
enableSecondaryTax
boolean
Whether secondary tax is enabled
​
secondaryTaxName
string
Secondary tax name
​
secondaryTaxRate
decimal
Secondary tax rate percentage
​
enableTaxExemptions
boolean
Whether tax exemptions are allowed

​
Create or update tax settings

Update tax configuration. 
POST /api/tax-settings

​
Request body

​
businessName
string
required
Business name
​
taxNumber
string
required
Tax registration number
​
businessAddress
string
required
Business address
​
enableTax
boolean
default:"true"
Enable tax
​
taxName
string
default:"Sales Tax"
Primary tax name
​
taxRate
decimal
default:"10"
Primary tax rate (%)
​
enableSecondaryTax
boolean
default:"false"
Enable secondary tax
​
secondaryTaxName
string
default:"Service Tax"
Secondary tax name
​
secondaryTaxRate
decimal
default:"5"
Secondary tax rate (%)
​
enableTaxExemptions
boolean
default:"false"
Allow tax exemptions

​
Example request

curl -X POST "https://api.example.com/api/tax-settings" \
  -H "Content-Type: application/json" \
  -H "X-User-Id: 1" \
  -H "X-User-Name: Admin" \
  -d '{
    "businessName": "Acme Retail Store",
    "taxNumber": "TAX-123456789",
    "businessAddress": "123 Main Street, City, State 12345",
    "enableTax": true,
    "taxName": "Sales Tax",
    "taxRate": 10,
    "enableSecondaryTax": false,
    "enableTaxExemptions": false
  }'

​
Calculate tax

Calculate tax for a given subtotal. 
POST /api/tax-settings/calculate

​
Request body

​
subtotal
decimal
required
Subtotal amount
​
isExempt
boolean
Whether transaction is tax-exempt
​
discountAmount
decimal
Discount amount to subtract

​
Response

​
subtotal
decimal
Input subtotal
​
taxType
string
Tax type applied
​
taxRate
decimal
Primary tax rate
​
taxAmount
decimal
Primary tax amount
​
taxLabel
string
Primary tax label
​
secondaryTaxRate
decimal
Secondary tax rate (if enabled)
​
secondaryTaxAmount
decimal
Secondary tax amount
​
secondaryTaxLabel
string
Secondary tax label
​
total
decimal
Final total after tax and discounts

​
Example request

curl -X POST "https://api.example.com/api/tax-settings/calculate" \
  -H "Content-Type: application/json" \
  -d '{
    "subtotal": 100.00,
    "isExempt": false,
    "discountAmount": 0
  }'

​
Example response

{
  "subtotal": 100.00,
  "taxType": "Standard",
  "taxRate": 10,
  "taxAmount": 10.00,
  "taxLabel": "Sales Tax (10%)",
  "secondaryTaxRate": 0,
  "secondaryTaxAmount": 0,
  "total": 110.00
}

​
Admin settings

​
Get admin settings

Retrieve administrative settings and system status. 
GET /api/adminsettings

​
Response

​
id
integer
Settings ID
​
databaseStatus
string
Database connection status
​
lastBackup
string
Timestamp of last backup
​
requireStrongPins
boolean
Require strong PIN policy
​
maxFailedLoginAttempts
integer
Max failed login attempts
​
logLevel
string
Logging level
​
performanceMetricsEnabled
boolean
Performance monitoring enabled

​
Update admin settings

Update administrative configuration. 
PUT /api/adminsettings

​
Test database connection

Test the database connection. 
POST /api/adminsettings/test-connection

​
Get backup capabilities

Check backup system capabilities. 
GET /api/adminsettings/backup/capabilities

​
Create database backup

Create a manual database backup. 
POST /api/adminsettings/backup/create

​
Get local backups

List available local backups. 
GET /api/adminsettings/backup/local

​
Restore database backup

Restore from a backup file. 
POST /api/adminsettings/backup/restore

​
Clear database

Completely clear the database (use with caution). 
POST /api/adminsettings/clear-database
This endpoint permanently deletes all data. Use only for development or when starting fresh.

​
Get logs folder

Get the path to the logs folder. 
GET /api/adminsettings/logs/folder

​
Get latest log file

Get information about the most recent log file. 
GET /api/adminsettings/logs/latest

Build docs developers (and LLMs) love

Get started for freeTalk to us