For the complete documentation index, see llms.txt. This page is also available as Markdown.

Consumption Sync (Online Method)

Syncs consumption events and device variables for one license, or for every member of a bundle, in a single request. Use it when a device records usage locally and reports it later in batches.

Every event carries its own id and is applied exactly once, so a request can always be sent again safely. The response tells you which events were applied, which were rejected and why, and returns a signed license snapshot per product, so the device can remove the applied events from its local journal and refresh its local license.

For devices without internet access, see Consumption Sync (Offline Method).

The LicenseSpring SDKs call this endpoint for you. You only need the details below if you integrate with the License API directly.

Endpoint

  • Method: POST

  • Path: /api/v4/consumption_sync/

  • Description: Applies a batch of consumption events and device variables for one or more licenses on a device.

Authentication

Required headers

  • Date (string) — RFC7231 GMT date string

  • Authorization (string) — signature or bearer token

Optional headers

  • licensespring-tpm-signature (string) — TPM licensing signature and algorithm, required for TPM licenses

    • licensespring-tpm-signature: algorithm="ES256",signature=""

  • licensespring-hardware-key (string) — hardware key signature, required for hardware-key licenses

  • Accept: application/json

  • Content-Type: application/json

Request

A request can be up to 4 MB. Larger requests are refused with HTTP 413; split a larger backlog over several syncs.

Body parameters

Required:

  • schema_version (integer) — always 1

  • request (string) — always "sync"

  • request_id (string) — a new UUID for every request; it is echoed back in the response

  • hardware_id (string)

  • licenses (object) — map keyed by product code: one entry for a single license, one entry per member for a bundle

Unknown fields are ignored.

License entry (licenses.<product_code>)

One of:

  • license_key (string) — for a bundle member, the bundle's license key

  • username (string)

Required:

  • resources (object) — what to sync for this license, see below. Unknown resource kinds are ignored.

Optional:

  • license_id (number) — the license's own ID; for a bundle member, the member's ID, not the bundle's

resources.consumption

The license's own consumption.

  • local_consumptions (number) — required. The device's current pending total. Informational only, the server never applies it.

  • events (array) — required. The consumption events, see Events.

  • allow_overages (boolean), max_overages (number) — optional overage request, stored on non-pooled licenses. Ignored for pooled licenses.

resources.feature_consumption

A map keyed by feature code. Each value has the same shape as resources.consumption; allow_overages and max_overages are ignored for features.

resources.device_variables

A flat { "name": "value" } object, the same as in Track Device Variables. Variables are matched by name and an existing value is overwritten. Variables are applied all or nothing.

Events

Each event is an object { "id": string, "count": number, "timestamp": string }:

  • id — a non-empty string of up to 255 characters, unique per license or feature. UUIDs are recommended. An event without a string id fails the whole request with missing_parameters.

  • count — a non-zero integer that fits a signed 32-bit integer. Negative counts are corrections and need negative consumptions to be allowed on the license (or its consumption pool).

  • timestamp — ISO 8601 UTC. It may be omitted or null only for a single aggregate event that represents usage recorded before the device kept individual events.

Events are applied in timestamp order, with events without a timestamp first. An event whose id was already applied, by an earlier sync or by Add Consumption with the same idempotency-key, is not applied again.

Examples

Schema

Request Body

Request schema (TypeScript + JSON Schema)

TypeScript

JSON Schema

Response Body

Response schema (TypeScript)

Response

On success, the endpoint responds with HTTP 200, the JSON body below and a LicenseSignature header (see Response Signature v2).

Top level

  • request_id — the request_id of the request, echoed exactly. Discard a response whose request_id doesn't match the request you sent.

  • date — ISO 8601 UTC response date, used in every product's offline_signature.

  • licenses — one entry per product that has something to report, keyed by product code.

Product entry (licenses.<product_code>)

Each entry contains the license snapshot, built like the offline activation response (total_consumptions, max_consumptions, allow_overages, max_overages, product_features, custom_fields, validity_period, offline_checkout and so on), plus:

  • hardware_id — must match the device.

  • license_signature — the v1 license signature, see Response Signature.

  • offline_signature — HMAC-SHA256("licenseSpring\ndate: <date>\n<license_key or username>\n<hardware_id>\n<api_key or client_id>", signingKey), base64-encoded, using the response date exactly as received. The signing key is the Shared Key, or the Client Secret for OAuth.

  • license_signature_v2 — RSA-SHA256 signature over this product entry's compact JSON, in the key order received, with only the license_signature_v2 field removed.

  • resources — the result per resource kind, see below.

resources.consumption and resources.feature_consumption.<feature_code>

  • acknowledged.processed_ids — every event ID from the request that has been applied, including IDs applied by an earlier sync. Remove exactly these events from the local journal.

  • acknowledged.count — the total actually applied for processed_ids. It can differ from the sum of their counts: a negative event that would take the total below 0 is applied only down to 0.

  • rejected_ids — event ID → { code, message } for events that were not applied, see Rejection codes.

acknowledged is omitted when nothing in that kind was applied, and rejected_ids when nothing was rejected.

resources.device_variables

  • accepted — the stored variables, in the same shape as the Track Device Variables response (created_at in epoch milliseconds).

  • rejected — { variable, reason } for every variable when they could not be stored; reason is missing_company_feature_flag, or company_feature_value_exceeded when the device-variable limit would be exceeded. Rejected variables are not stored; consumption sent in the same request is still applied.

What is left out

A resource kind, or a whole product, with nothing to report is omitted rather than sent empty. Anything from the request that appears in neither processed_ids nor rejected_ids (including an omitted product, which can happen when the license is busy with another write) is still pending and should be sent again with the next sync.

Offline checkout

When the device holds an offline checkout from a consumption pool, the license (and each pooled consumption feature in product_features) carries offline_checkout: { checked_out, consumed, returned, remaining, synced_at, closed_at }, the same as in the offline activation response. Synced usage is recorded in consumed; the checkout stays open until the device is deactivated. A sync never applies more than remaining: a larger event is rejected with pool_quota_exhausted.

Rejection codes

Codes in rejected_ids:

Code
When
What to do

license_not_enough_consumptions, feature_not_enough_consumptions

The license or feature limit would be exceeded

Retryable: keep the event and send it again later

pool_quota_exhausted

The consumption pool is full, or the event is larger than what is left of the device's offline checkout

Retryable

invalid_sync_event

The count or timestamp is invalid, the id is longer than 255 characters, or the same id was sent with different counts

Permanent: drop the event

negative_consumptions_not_allowed

A negative event, but the license (or its consumption pool) does not allow negative consumptions

Permanent

unsupported_product_feature

The feature code is unknown or not a consumption feature, or the feature has expired and the event is dated after the expiry (or undated). Events dated before the expiry are still applied.

Permanent

license_not_consumption

The license is not a consumption license

Permanent

invalid_pool_type, missing_company_feature_flag

The consumption pool configuration or the company plan does not allow it

Permanent

Treat any other code as retryable.

License Authorization Method

There are two types of product licenses based on how the client application authorizes itself to interact with a license:

  • Key-based product licenses: the license entry uses license_key

  • User-based product licenses: the license entry uses username

Errors

These errors fail the whole request: nothing is applied. The response has an HTTP status code of 400 or higher and the response body contains an error description in the following format:

When one of the licenses in licenses cannot be found or authenticated, the message ends with (product: <code>) so you know which entry caused it. Every entry is checked before anything is written, so the other entries are not applied either.

List of exceptions

missing_headers (400)

The Authorization or Date header is missing

missing_parameters (400)

A required field is missing or has the wrong type, including an event without a non-empty string id

invalid_sync_request (400)

request is not "sync", or schema_version is not 1

unknown_product_code (400)

A product code in licenses was not found

license_not_found (400)

A license in licenses was not found

license_user_not_found (400)

The username is not assigned to the license

device_not_found (400)

The license is not activated on this hardware_id

license_not_active (400)

The license or the device is not active

license_not_enabled (400)

The license is not enabled

blacklisted (400)

This device is blacklisted

tpm_signature_required (400)

The TPM signature is missing and TPM usage is enforced

tpm_signature_mismatch (400)

The TPM signature can't be verified against the TPM public key

hardware_key_required (400)

The hardware-key signature is missing for a hardware-key license

hardware_key_signature_mismatch (401)

The hardware-key signature is invalid

413

The request is larger than 4 MB

Deactivating after a sync

After a device has synced, the consumptions it reports when deactivating must only contain the usage recorded since the last sync, otherwise it is counted twice. Bundle deactivation ignores consumptions, so sync a bundle's usage before deactivating it.

Last updated

Was this helpful?