POST
Report device sync status
POS sync device For: Integrator Conditions
  • The caller must present the device’s own access token as a bearer token, and the token must match the device in the URL; otherwise the call is refused with 401.
  • The device must be active; a revoked device is refused with 401.
  • state must be one of stale, syncing, synced or error, and contract_version is required and must be at least 1; the device cannot omit the contract version it was built for.
What else happens
  • Stores the last seen time, the reported state and the reported metadata (last sync time, lag, contract version) on the device.
  • Clears a pending resync request when a device on the current contract reports synced with a last_synced_at later than the request.
Part of Connect offline POS devices.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

instance
string
required

Identifier of the POS sync device (27-character KSUID).

Body

application/json

Validates the state reported by a POS instance heartbeat.

contract_version is REQUIRED, and that is the load-bearing rule of this whole request: it is the version the till's applier and local schema were BUILT for. A till that omits it cannot be told that its contract is behind, so it may not omit it.

state
enum<string>
required

Local sync state reported by the device: stale, syncing, synced or error. Required.

Available options:
stale,
syncing,
synced,
error
contract_version
integer
required

Integer version of the sync contract the device was built for, at least 1. Required; a version below the published one makes the answer update_required.

Required range: x >= 1
last_synced_at
string<date-time> | null

When the device last finished a sync (ISO 8601). Optional; a synced report only clears a pending resync request if this is later than the request.

lag_seconds
integer | null

How many seconds the device is behind the catalogue stream, an integer of at least 0. Optional.

Required range: x >= 0

Response

PosSyncHeartbeatResource

data
PosSyncHeartbeatResource · object
required

Items of this page.