> For the complete documentation index, see [llms.txt](https://docs.licensespring.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.licensespring.com/license-api/consumption/consumption-sync-online-method.md).

# 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)](https://docs.licensespring.com/license-api/consumption/consumption-sync-offline-method.md).

{% hint style="info" %}
The LicenseSpring SDKs call this endpoint for you. You only need the details below if you integrate with the License API directly.
{% endhint %}

### 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

See [License API Authorization](https://docs.licensespring.com/license-api/license-api-authorization.md).

#### 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

#### Recommended headers

* `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](#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](https://docs.licensespring.com/license-api/device-variables/track-device-variables.md). 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](https://docs.licensespring.com/license-api/consumption/add-consumption.md) with the same `idempotency-key`, is not applied again.

### Examples

{% tabs %}
{% tab title="curl" %}

```bash
curl --location --request POST '/api/v4/consumption_sync/' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Date: string' \
--header 'Authorization: string' \
--data-raw '{
  "schema_version": 1,
  "request": "sync",
  "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "hardware_id": "some-unique-id",
  "licenses": {
    "XY": {
      "license_key": "AAAA-BBBB-CCCC-DDDD",
      "resources": {
        "consumption": {
          "local_consumptions": 7,
          "events": [
            { "id": "0f8e1c1a-6b8e-4c43-9d2a-1f5b1c9e7a01", "count": 3, "timestamp": "2026-10-20T09:00:00Z" },
            { "id": "6a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "count": 4, "timestamp": "2026-10-20T14:30:00Z" }
          ]
        },
        "device_variables": { "seat_label": "design-team-03" }
      }
    }
  }
}'
```

{% endtab %}

{% tab title="nodejs" %}

```javascript
var request = require('request');
var options = {
  method: 'POST',
  url: '/api/v4/consumption_sync/',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Date': 'string',
    'Authorization': 'string'
  },
  body: JSON.stringify(sync_payload)
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
```

{% endtab %}

{% tab title="javascript (fetch)" %}

```javascript
var myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Date", "string");
myHeaders.append("Authorization", "string");

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: JSON.stringify(sync_payload),
  redirect: 'follow'
};

fetch("/api/v4/consumption_sync/", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
```

{% endtab %}

{% tab title="python" %}

```python
import requests

url = "/api/v4/consumption_sync/"

payload = {
  "schema_version": 1,
  "request": "sync",
  "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "hardware_id": "some-unique-id",
  "licenses": {
    "XY": {
      "license_key": "AAAA-BBBB-CCCC-DDDD",
      "resources": {
        "consumption": {
          "local_consumptions": 3,
          "events": [{ "id": "0f8e1c1a-6b8e-4c43-9d2a-1f5b1c9e7a01", "count": 3, "timestamp": "2026-10-20T09:00:00Z" }]
        }
      }
    }
  }
}

headers = {
  "Accept": "application/json",
  "Content-Type": "application/json",
  "Date": "string",
  "Authorization": "string"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

{% endtab %}

{% tab title="ruby" %}

```ruby
require "uri"
require "net/http"
require "json"

url = URI("/api/v4/consumption_sync/")

http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Accept"] = "application/json"
request["Content-Type"] = "application/json"
request["Date"] = "string"
request["Authorization"] = "string"
request.body = JSON.dump(sync_payload)

response = http.request(request)
puts response.read_body
```

{% endtab %}
{% endtabs %}

### Schema

#### Request Body

<details>

<summary><strong>Request schema (TypeScript + JSON Schema)</strong></summary>

**TypeScript**

```typescript
type SyncEvent = {
  id: string,
  count: number,
  timestamp?: string | null,
}

type SyncConsumption = {
  local_consumptions: number,
  events: SyncEvent[],
  allow_overages?: boolean | undefined,
  max_overages?: number | undefined,
}

type SyncLicenseEntry = ({
  // for key-based licenses:
  license_key: string,
} | {
  // for user-based licenses:
  username: string,
}) & {
  license_id?: number | undefined,
  resources: {
    consumption?: SyncConsumption,
    feature_consumption?: { [featureCode: string]: SyncConsumption },
    device_variables?: { [name: string]: string },
  },
}

type ConsumptionSyncRequestBody = {
  schema_version: 1,
  request: 'sync',
  request_id: string,
  hardware_id: string,
  licenses: { [productCode: string]: SyncLicenseEntry },
}
```

**JSON Schema**

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "$defs": {
    "SyncConsumption": {
      "type": "object",
      "properties": {
        "local_consumptions": { "type": "integer" },
        "events": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": { "type": "string", "minLength": 1 },
              "count": { "type": "integer" },
              "timestamp": { "type": ["string", "null"] }
            },
            "required": ["id"]
          }
        },
        "allow_overages": { "type": "boolean" },
        "max_overages": { "type": "integer", "minimum": 0 }
      },
      "required": ["local_consumptions", "events"]
    }
  },
  "properties": {
    "schema_version": { "type": "integer" },
    "request": { "type": "string" },
    "request_id": { "type": "string", "minLength": 1 },
    "hardware_id": { "type": "string" },
    "licenses": {
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "license_key": { "type": "string" },
          "username": { "type": "string" },
          "license_id": { "type": "integer" },
          "resources": {
            "type": "object",
            "properties": {
              "consumption": { "$ref": "#/$defs/SyncConsumption" },
              "feature_consumption": {
                "type": "object",
                "additionalProperties": { "$ref": "#/$defs/SyncConsumption" }
              },
              "device_variables": { "type": "object" }
            }
          }
        },
        "anyOf": [{ "required": ["license_key"] }, { "required": ["username"] }],
        "required": ["resources"]
      }
    }
  },
  "required": ["schema_version", "request", "request_id", "hardware_id", "licenses"]
}
```

</details>

#### Response Body

<details>

<summary><strong>Response schema (TypeScript)</strong></summary>

```typescript
type SyncRejection = {
  code: string,
  message: string,
}

type SyncConsumptionAck = {
  acknowledged?: {
    count: number,
    processed_ids: string[],
  },
  rejected_ids?: { [eventId: string]: SyncRejection },
}

type SyncDeviceVariablesAck = {
  accepted: {
    variable: string,
    value: string,
    device_id: number,
    created_at: number,
  }[],
  rejected: {
    variable: string,
    reason: string,
  }[],
}

type OfflineCheckoutState = {
  checked_out: number,
  consumed: number,
  returned: number,
  remaining: number,
  synced_at: string | null,
  closed_at: string | null,
}

type ConsumptionSyncLicenseEntry = {
  // the license snapshot, as in the offline activation response,
  // including offline_checkout?: OfflineCheckoutState
  [licenseField: string]: unknown,

  hardware_id: string,
  license_signature: string,
  offline_signature: string,
  license_signature_v2: string,
  resources: {
    consumption?: SyncConsumptionAck,
    feature_consumption?: { [featureCode: string]: SyncConsumptionAck },
    device_variables?: SyncDeviceVariablesAck,
  },
}

type ConsumptionSyncResponseBody = {
  request_id: string,
  date: string,
  licenses: { [productCode: string]: ConsumptionSyncLicenseEntry },
}
```

</details>

### Response

On success, the endpoint responds with HTTP 200, the JSON body below and a `LicenseSignature` header (see [Response Signature v2](https://docs.licensespring.com/license-api/license-api-authorization/response-signature-v2.md)).

```json
{
  "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "date": "2026-10-22T12:01:00Z",
  "licenses": {
    "XY": {
      "hardware_id": "some-unique-id",
      "license_signature": "...",
      "offline_signature": "...",
      "resources": {
        "consumption": {
          "acknowledged": {
            "count": 3,
            "processed_ids": ["0f8e1c1a-6b8e-4c43-9d2a-1f5b1c9e7a01"]
          },
          "rejected_ids": {
            "6a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d": {
              "code": "license_not_enough_consumptions",
              "message": "Not enough consumptions left."
            }
          }
        },
        "device_variables": {
          "accepted": [
            { "variable": "seat_label", "value": "design-team-03", "device_id": 123, "created_at": 1760011260000 }
          ],
          "rejected": []
        }
      },
      "total_consumptions": 103,
      "max_consumptions": 103,
      "...": "the other license fields, as in the offline activation response",
      "license_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](https://docs.licensespring.com/license-api/license-activation-and-deactivation/activate-license-offline-method.md) (`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](https://docs.licensespring.com/license-api/license-api-authorization/response-signature.md).
* `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](#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](https://docs.licensespring.com/license-api/device-variables/track-device-variables.md) 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`:

<table><thead><tr><th width="309.765625">Code</th><th>When</th><th width="166.875">What to do</th></tr></thead><tbody><tr><td><code>license_not_enough_consumptions</code>, <code>feature_not_enough_consumptions</code></td><td>The license or feature limit would be exceeded</td><td>Retryable: keep the event and send it again later</td></tr><tr><td><code>pool_quota_exhausted</code></td><td>The consumption pool is full, or the event is larger than what is left of the device's offline checkout</td><td>Retryable</td></tr><tr><td><code>invalid_sync_event</code></td><td>The <code>count</code> or <code>timestamp</code> is invalid, the <code>id</code> is longer than 255 characters, or the same <code>id</code> was sent with different counts</td><td>Permanent: drop the event</td></tr><tr><td><code>negative_consumptions_not_allowed</code></td><td>A negative event, but the license (or its consumption pool) does not allow negative consumptions</td><td>Permanent</td></tr><tr><td><code>unsupported_product_feature</code></td><td>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.</td><td>Permanent</td></tr><tr><td><code>license_not_consumption</code></td><td>The license is not a consumption license</td><td>Permanent</td></tr><tr><td><code>invalid_pool_type</code>, <code>missing_company_feature_flag</code></td><td>The consumption pool configuration or the company plan does not allow it</td><td>Permanent</td></tr></tbody></table>

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:

```typescript
{
  status: number,
  code: string,
  message: string
}
```

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

<details>

<summary><strong>missing_headers (400)</strong></summary>

The `Authorization` or `Date` header is missing

</details>

<details>

<summary><strong>missing_parameters (400)</strong></summary>

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

</details>

<details>

<summary><strong>invalid_sync_request (400)</strong></summary>

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

</details>

<details>

<summary><strong>unknown_product_code (400)</strong></summary>

A product code in `licenses` was not found

</details>

<details>

<summary><strong>license_not_found (400)</strong></summary>

A license in `licenses` was not found

</details>

<details>

<summary><strong>license_user_not_found (400)</strong></summary>

The `username` is not assigned to the license

</details>

<details>

<summary><strong>device_not_found (400)</strong></summary>

The license is not activated on this `hardware_id`

</details>

<details>

<summary><strong>license_not_active (400)</strong></summary>

The license or the device is not active

</details>

<details>

<summary><strong>license_not_enabled (400)</strong></summary>

The license is not enabled

</details>

<details>

<summary><strong>blacklisted (400)</strong></summary>

This device is blacklisted

</details>

<details>

<summary><strong>tpm_signature_required (400)</strong></summary>

The TPM signature is missing and TPM usage is enforced

</details>

<details>

<summary><strong>tpm_signature_mismatch (400)</strong></summary>

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

</details>

<details>

<summary><strong>hardware_key_required (400)</strong></summary>

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

</details>

<details>

<summary><strong>hardware_key_signature_mismatch (401)</strong></summary>

The hardware-key signature is invalid

</details>

<details>

<summary><strong>413</strong></summary>

The request is larger than 4 MB

</details>

### 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.licensespring.com/license-api/consumption/consumption-sync-online-method.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
