End-of-Day Policy
- Base path
/api/v1/physical-pos- Identity
- Ed25519 request signature on every request —
X-Key-Id,X-Date,X-Nonce,X-Signature, plusDigeston 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 gets403 PRODUCT_NOT_ENABLED; without the scope403 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.
| Level | Path | Read | Write |
|---|---|---|---|
| Account | /api/v1/physical-pos/settlement-policy | physical_pos:view | physical_pos:manage |
| Store | /api/v1/physical-pos/stores/{storeId}/settlement-policy | physical_pos:view | physical_pos:manage |
| Device | /api/v1/physical-pos/devices/{deviceId}/settlement-policy | physical_pos:view | physical_pos:manage |
| The device's effective policy | GET /api/v1/physical-pos/devices/{deviceId}/settlement-policy/effective | physical_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. PUTandDELETEshare the rate limit of starting end of day: 30 requests per API key in 60 seconds.
Modes
mode | What happens |
|---|---|
MANUAL | You start end of day: on the device, in the panel or from the API. Default. |
SCHEDULED | Lunixi starts end of day at scheduleTime. If the device is busy or not connected, it retries within the attempt window. |
DEVICE_AUTO | The 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": { … } }.
| Field | Type | Description |
|---|---|---|
scopeType | string | ACCOUNT, STORE or DEVICE. |
storeId, deviceId | string | null | Target at store or device level. |
active | boolean | Whether a policy is written at this level. If false, the level inherits from above. |
mode | string | MANUAL, SCHEDULED or DEVICE_AUTO. |
scheduleTime | string | null | Start time for SCHEDULED, HH:mm (24-hour). |
timeZone | string | Time zone (IANA name). Default Europe/Istanbul. |
scheduleDays | string[] | Days for SCHEDULED: MON…SUN. Every day is listed as all seven days. |
retryWindowMinutes | integer | null | Attempt window for SCHEDULED, in minutes. |
retryIntervalMinutes | integer | null | Time between attempts for SCHEDULED, in minutes. |
offlineBehavior | string | null | For SCHEDULED, when the device is not connected: RETRY_IN_WINDOW (retry within the window) or ALERT_IMMEDIATELY (fail at once and notify). |
overdueAlertHours | integer | null | An overdue notification is sent when this many hours have passed since the last end of day; null means off. |
rowVersion | integer | The record's version; send it as expectedRowVersion when writing. 0 on a level never written. |
updatedAt | string | null | Last 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.
| Field | Type | Required | Description |
|---|---|---|---|
mode | string | Yes | MANUAL, SCHEDULED or DEVICE_AUTO. |
scheduleTime | string | For SCHEDULED | HH:mm. Not sent for other modes. |
timeZone | string | No | IANA time zone. Default Europe/Istanbul. |
scheduleDays | string[] | No | MON, TUE, WED, THU, FRI, SAT, SUN; no duplicates. Empty or omitted means every day. SCHEDULED only. |
retryWindowMinutes | integer | No | 5–720, default 120. SCHEDULED only. |
retryIntervalMinutes | integer | No | 1–120, default 15; must be less than retryWindowMinutes. SCHEDULED only. |
offlineBehavior | string | No | RETRY_IN_WINDOW (default) or ALERT_IMMEDIATELY. SCHEDULED only. |
overdueAlertHours | integer | No | 1–168. Allowed in every mode; omitted means the overdue alert is off. |
expectedRowVersion | integer | No | The 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
}
}| Field | Type | Description |
|---|---|---|
sourceScopeType | string | The level the policy comes from: DEVICE, STORE, ACCOUNT or DEFAULT (no policy, MANUAL). |
policy | object | The policy that applies. |
serverSettlementSupported | boolean | Whether the device supports end of day started by the server. |
deviceAutoSupported | boolean | Whether the device's own automatic end-of-day result can be recorded. |
nextScheduledAt | string | null | Next scheduled end of day (UTC). null if not SCHEDULED, if there is no slot within 8 days, or if scheduleWarning is set. |
lastSettlementAt | string | null | The device's last end of day. |
overdue | boolean | true if overdueAlertHours is set and the last end of day is older than that (or there is none). |
scheduleWarning | string | null | SCHEDULED_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
| Webhook | When |
|---|---|
physical_pos.settlement.completed | The device reported an end-of-day result (by hand, scheduled or the device's own end of day). |
physical_pos.settlement.failed | A scheduled end of day could not be taken within the attempt window. |
physical_pos.settlement.skipped | A scheduled end of day was skipped: the device does not support it or is not active. |
physical_pos.settlement.overdue | overdueAlertHours hours have passed since the last end of day. |
Payloads: Webhook Events › End-of-day events.
Errors
| HTTP | code | When |
|---|---|---|
400 | physical_pos.settlement.policy_invalid | A field breaks a policy rule (details.field, details.reason: required, invalid, not_allowed, out_of_range, duplicate, not_less_than_window). |
400 | VALIDATION_ERROR | Undefined field, or a number that is not a JSON integer. |
403 | physical_pos.environment.test_key_read_only | The write was made with a test key. |
404 | physical_pos.store.not_found · physical_pos.device.not_found | The store or device does not exist, is not yours or lives in the other environment. |
409 | physical_pos.settlement.policy_version_conflict | expectedRowVersion is not current; read the policy again. |
422 | physical_pos.settlement.scheduled_unsupported | SCHEDULED at device level; the device does not support end of day from the server. |
422 | physical_pos.settlement.device_auto_unsupported | DEVICE_AUTO at device level; the device cannot report its own end-of-day result. |
429 | RATE_LIMITED | End-of-day write limit exceeded. |
All codes: Error Codes.