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).
Endpoint
Method:
POSTPath:
/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 stringAuthorization(string) — signature or bearer token
Optional headers
licensespring-tpm-signature(string) — TPM licensing signature and algorithm, required for TPM licenseslicensespring-tpm-signature: algorithm="ES256",signature=""
licensespring-hardware-key(string) — hardware key signature, required for hardware-key licenses
Recommended headers
Accept: application/jsonContent-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) — always1request(string) — always"sync"request_id(string) — a new UUID for every request; it is echoed back in the responsehardware_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 keyusername(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 stringidfails the whole request withmissing_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 ornullonly 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
Response Body
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— therequest_idof the request, echoed exactly. Discard a response whoserequest_iddoesn't match the request you sent.date— ISO 8601 UTC response date, used in every product'soffline_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 responsedateexactly 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 thelicense_signature_v2field 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 forprocessed_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_atin epoch milliseconds).rejected—{ variable, reason }for every variable when they could not be stored;reasonismissing_company_feature_flag, orcompany_feature_value_exceededwhen 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:
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_keyUser-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
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?