Physical POS
API Reference
End-of-Day Policy

End-of-Day Policy

Who calls these endpoints?External API (s2s)
Base path
/api/v1/physical-pos
Identity
Ed25519 request signature on every request — X-Key-Id, X-Date, X-Nonce, X-Signature, plus Digest on requests with a body. ±5 min clock window, single-use nonce. A Bearer token or a panel session is not accepted here.
Authorization
The key must carry the Physical POS product (PHYSICAL_POS) and the scope for the endpoints on this page: physical_pos:view · physical_pos:manage. Without the product the call gets 403 PRODUCT_NOT_ENABLED; without the scope 403 API_INSUFFICIENT_SCOPE. See Authentication and Scopes.
Cross-surface
These endpoints are the s2s surface — call them from your own server with a signed request. The same records have screens in the panel, but panel endpoints cannot be called with an API key, and these endpoints cannot be called with a panel session.

The end-of-day policy decides how devices take end of day: by hand, started by Lunixi at the time you set, or by the device's own automatic end of day. You set the policy at three levels; a lower level fully overrides the level above it, and fields are never merged.

LevelPathReadWrite
Account/api/v1/physical-pos/settlement-policyphysical_pos:viewphysical_pos:manage
Store/api/v1/physical-pos/stores/{storeId}/settlement-policyphysical_pos:viewphysical_pos:manage
Device/api/v1/physical-pos/devices/{deviceId}/settlement-policyphysical_pos:viewphysical_pos:manage
The device's effective policyGET /api/v1/physical-pos/devices/{deviceId}/settlement-policy/effectivephysical_pos:view—

At each level GET reads, PUT writes and DELETE clears the level (it then inherits from above). If no policy was ever written, MANUAL applies. In the panel the same setting is on the Automatic End of Day screen.

  • A test key reads policies; writes get 403 physical_pos.environment.test_key_read_only.
  • PUT and DELETE share the rate limit of starting end of day: 30 requests per API key in 60 seconds.

Modes

modeWhat happens
MANUALYou start end of day: on the device, in the panel or from the API. Default.
SCHEDULEDLunixi starts end of day at scheduleTime. If the device is busy or not connected, it retries within the attempt window.
DEVICE_AUTOThe device takes end of day itself; Lunixi only records the result and watches for delays.

SCHEDULED cannot be written at device level for a device that does not support end of day from the server (422 physical_pos.settlement.scheduled_unsupported); DEVICE_AUTO is checked the same way (422 physical_pos.settlement.device_auto_unsupported). If an account- or store-level SCHEDULED applies to such a device, that day's end of day is skipped and physical_pos.settlement.skipped is sent; the effective policy shows this in advance with scheduleWarning.

The policy object

Reads and writes return { "policy": { … } }.

FieldTypeDescription
scopeTypestringACCOUNT, STORE or DEVICE.
storeId, deviceIdstring | nullTarget at store or device level.
activebooleanWhether a policy is written at this level. If false, the level inherits from above.
modestringMANUAL, SCHEDULED or DEVICE_AUTO.
scheduleTimestring | nullStart time for SCHEDULED, HH:mm (24-hour).
timeZonestringTime zone (IANA name). Default Europe/Istanbul.
scheduleDaysstring[]Days for SCHEDULED: MON…SUN. Every day is listed as all seven days.
retryWindowMinutesinteger | nullAttempt window for SCHEDULED, in minutes.
retryIntervalMinutesinteger | nullTime between attempts for SCHEDULED, in minutes.
offlineBehaviorstring | nullFor SCHEDULED, when the device is not connected: RETRY_IN_WINDOW (retry within the window) or ALERT_IMMEDIATELY (fail at once and notify).
overdueAlertHoursinteger | nullAn overdue notification is sent when this many hours have passed since the last end of day; null means off.
rowVersionintegerThe record's version; send it as expectedRowVersion when writing. 0 on a level never written.
updatedAtstring | nullLast change.

Write a policy

PUT …/settlement-policy · physical_pos:manage

PUT replaces the level's policy as a whole; any field you leave out returns to its default.

FieldTypeRequiredDescription
modestringYesMANUAL, SCHEDULED or DEVICE_AUTO.
scheduleTimestringFor SCHEDULEDHH:mm. Not sent for other modes.
timeZonestringNoIANA time zone. Default Europe/Istanbul.
scheduleDaysstring[]NoMON, TUE, WED, THU, FRI, SAT, SUN; no duplicates. Empty or omitted means every day. SCHEDULED only.
retryWindowMinutesintegerNo5–720, default 120. SCHEDULED only.
retryIntervalMinutesintegerNo1–120, default 15; must be less than retryWindowMinutes. SCHEDULED only.
offlineBehaviorstringNoRETRY_IN_WINDOW (default) or ALERT_IMMEDIATELY. SCHEDULED only.
overdueAlertHoursintegerNo1–168. Allowed in every mode; omitted means the overdue alert is off.
expectedRowVersionintegerNoThe rowVersion you read. If you send it and the record changed in the meantime, you get 409 physical_pos.settlement.policy_version_conflict; if omitted, the last write wins.

Numbers must be JSON integers ("120" is rejected).

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/stores/00000000-0000-0000-0000-000000000101/settlement-policy"
BODY='{"mode":"SCHEDULED","scheduleTime":"23:30","scheduleDays":["MON","TUE","WED","THU","FRI","SAT"],"retryWindowMinutes":120,"retryIntervalMinutes":15,"offlineBehavior":"RETRY_IN_WINDOW","overdueAlertHours":26,"expectedRowVersion":2}'
lunixi_sign PUT "$REQ_PATH" "$BODY"
 
curl -X PUT "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "Digest: $DIGEST" \
  -H "X-Signature: $SIGNATURE" \
  --data-raw "$BODY"
{
  "policy": {
    "scopeType": "STORE",
    "storeId": "00000000-0000-0000-0000-000000000101",
    "deviceId": null,
    "active": true,
    "mode": "SCHEDULED",
    "scheduleTime": "23:30",
    "timeZone": "Europe/Istanbul",
    "scheduleDays": ["MON", "TUE", "WED", "THU", "FRI", "SAT"],
    "retryWindowMinutes": 120,
    "retryIntervalMinutes": 15,
    "offlineBehavior": "RETRY_IN_WINDOW",
    "overdueAlertHours": 26,
    "rowVersion": 3,
    "updatedAt": "2026-01-02T09:00:00.000Z"
  }
}

Clear a policy

DELETE …/settlement-policy?expectedRowVersion=3 · physical_pos:manage

Removes the level's policy; the level inherits from above (active: false). If the account level is cleared, the default MANUAL applies. timeZone is kept. expectedRowVersion is optional. The response is the level's current state: { "policy": { … } }.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/devices/00000000-0000-0000-0000-000000000401/settlement-policy?expectedRowVersion=1"
lunixi_sign DELETE "$REQ_PATH"
 
curl -X DELETE "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE"

The device's effective policy

GET /api/v1/physical-pos/devices/{deviceId}/settlement-policy/effective · physical_pos:view

Shows which level's policy applies to the device, the next scheduled end of day and the overdue state.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/devices/00000000-0000-0000-0000-000000000401/settlement-policy/effective"
lunixi_sign GET "$REQ_PATH"
 
curl "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE"
{
  "effective": {
    "deviceId": "00000000-0000-0000-0000-000000000401",
    "sourceScopeType": "STORE",
    "policy": { "scopeType": "STORE", "storeId": "00000000-0000-0000-0000-000000000101", "deviceId": null, "active": true, "mode": "SCHEDULED", "scheduleTime": "23:30", "timeZone": "Europe/Istanbul", "scheduleDays": ["MON", "TUE", "WED", "THU", "FRI", "SAT"], "retryWindowMinutes": 120, "retryIntervalMinutes": 15, "offlineBehavior": "RETRY_IN_WINDOW", "overdueAlertHours": 26, "rowVersion": 3, "updatedAt": "2026-01-02T09:00:00.000Z" },
    "serverSettlementSupported": true,
    "deviceAutoSupported": true,
    "nextScheduledAt": "2026-01-02T20:30:00.000Z",
    "lastSettlementAt": "2026-01-01T20:31:12.000Z",
    "overdue": false,
    "scheduleWarning": null
  }
}
FieldTypeDescription
sourceScopeTypestringThe level the policy comes from: DEVICE, STORE, ACCOUNT or DEFAULT (no policy, MANUAL).
policyobjectThe policy that applies.
serverSettlementSupportedbooleanWhether the device supports end of day started by the server.
deviceAutoSupportedbooleanWhether the device's own automatic end-of-day result can be recorded.
nextScheduledAtstring | nullNext scheduled end of day (UTC). null if not SCHEDULED, if there is no slot within 8 days, or if scheduleWarning is set.
lastSettlementAtstring | nullThe device's last end of day.
overduebooleantrue if overdueAlertHours is set and the last end of day is older than that (or there is none).
scheduleWarningstring | nullSCHEDULED_UNSUPPORTED: the policy is SCHEDULED but the device does not support end of day from the server; scheduled end of day will be skipped.

Overdue and failure notifications

WebhookWhen
physical_pos.settlement.completedThe device reported an end-of-day result (by hand, scheduled or the device's own end of day).
physical_pos.settlement.failedA scheduled end of day could not be taken within the attempt window.
physical_pos.settlement.skippedA scheduled end of day was skipped: the device does not support it or is not active.
physical_pos.settlement.overdueoverdueAlertHours hours have passed since the last end of day.

Payloads: Webhook Events › End-of-day events.

Errors

HTTPcodeWhen
400physical_pos.settlement.policy_invalidA field breaks a policy rule (details.field, details.reason: required, invalid, not_allowed, out_of_range, duplicate, not_less_than_window).
400VALIDATION_ERRORUndefined field, or a number that is not a JSON integer.
403physical_pos.environment.test_key_read_onlyThe write was made with a test key.
404physical_pos.store.not_found · physical_pos.device.not_foundThe store or device does not exist, is not yours or lives in the other environment.
409physical_pos.settlement.policy_version_conflictexpectedRowVersion is not current; read the policy again.
422physical_pos.settlement.scheduled_unsupportedSCHEDULED at device level; the device does not support end of day from the server.
422physical_pos.settlement.device_auto_unsupportedDEVICE_AUTO at device level; the device cannot report its own end-of-day result.
429RATE_LIMITEDEnd-of-day write limit exceeded.

All codes: Error Codes.