Overview

Licenses let manufacturers conditionally enable functionality on a Device based on the Digital Products and Subscriptions an End Customer has purchased.

There are three common patterns, depending on the type of product:

1. Physical Products (Hardware as a Service) — the Device offers limited or no functionality until a compatible License is applied. The License is generated automatically when the End Customer purchases the Physical Product in the store. If the End Customer stops paying, the License is revoked and the Device stops working.
2. Digital Products (feature enablement) — the Device operates with baseline functionality and unlocks advanced features when one or more Licenses are assigned.
3. Usage-based / metered — some or all Device functionality is disabled by default and enabled only when a metered License is assigned. Once active, the Device sends a metering Telemetry key so the platform can bill the End Customer (e.g. by miles driven).

License flows

There are four flows the firmware needs to handle:

1. Initial License assignment.
2. License expiration update (renewal).
3. License removal.
4. Automated expiration.

Initial License assignment

When an End Customer assigns a License to a Device, the next Send Telemetry API response sets new_licenses to true. The Device calls Get License API to fetch the License details, applies the License locally, then calls Update License API to confirm.

The action to take — add, remove, or update — is indicated by the add, remove, and update fields in the Get License API response.

License expiration update

Licenses tied to recurring products carry an expired_at field. On every billing cycle, Xyte charges the End Customer; on success, the server extends expired_at by one cycle and sets new_licenses to true on the next Telemetry response.

The Device calls Get License API, updates the expiration on the active License locally, and confirms via Update License API.

License removal

Licenses can be revoked for several reasons — payment failure, Subscription cancellation, the user moving a License between Devices, and so on.

When a License is removed, the next Send Telemetry API response sets new_licenses to true. The Device calls Get License API to identify which License was removed, disables it locally, and confirms via Update License API.

A License cannot be transferred to another Device until the originating Device has confirmed its removal.

Automated expiration

Recurring Licenses always carry expired_at. In normal operation, the server extends this value on every successful billing cycle (with some grace time) and notifies the Device.

If the Device detects that expired_at has passed on an active License, it must disable the License locally without waiting for the server. This protects against the case where the End Customer assigns a License then disconnects the Device from the network, preventing the server from delivering the removal.

License states

A License moves through several states across its lifecycle as it is purchased, applied, transferred, and cancelled. New Licenses normally start in available, with a few edge-case exceptions.

A License can be assigned to a single Device at a time. Assignment can happen from the Customer Portal, via API, or automatically during the ecommerce flow.

Platform licenses

Platform Licenses are a special type that Partners can use to gate Commands or Telemetry from the server side, without involving the Device. For example, a Platform License can hide a "premium feature" Command from the Customer Portal even on Devices that don't implement License management.

Platform Licenses skip every pending state — there's no remove or disable waiting for Device confirmation.