> 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-offline-method.md).

# Consumption Sync (Offline Method)

{% hint style="info" %}
The offline method is for devices without internet access: the device writes a request file, which is uploaded through the offline portal, and the response file is brought back to the device. Devices that are online use [Consumption Sync (Online Method)](https://docs.licensespring.com/license-api/consumption/consumption-sync-online-method.md).
{% endhint %}

Syncs consumption events and device variables for one license, or for every member of a bundle, from a request file. Every event carries its own `id` and is applied exactly once, so the same file can always be uploaded again safely. The response file tells the device which events were applied, which were rejected and why, and contains a signed license snapshot per product.

### Endpoint

* Method: `POST`
* Path: `/api/v4/consumption_sync_offline/`
* Description: Applies a batch of consumption events and device variables from an offline request file (base64 payload) and returns the response as a file.

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

#### Recommended headers

* `Accept: application/json`
* `Content-Type: text/plain`

### Request

#### Body

The request body is a **base64-encoded, stringified JSON envelope** containing the sync request object and its signature (see [Signature](#signature)). A request can be up to **4 MB**; larger requests are refused with HTTP 413.

{% hint style="danger" %}
If using `multipart/form-data`, the `file` form parameter is mandatory.
{% endhint %}

### Examples

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

```bash
curl --location --request POST '/api/v4/consumption_sync_offline/' \
--header 'Accept: application/json' \
--header 'Content-Type: text/plain' \
--header 'Date: string' \
--header 'Authorization: string' \
--data-raw '_BASE64_PAYLOAD_HERE_'
```

{% endtab %}

{% tab title="curl (multipart)" %}

```bash
curl --location --request POST '/api/v4/consumption_sync_offline/' \
--header 'Accept: application/json' \
--header 'Date: string' \
--header 'Authorization: string' \
--form 'file=@"ls_sync.req"'
```

{% endtab %}

{% tab title="nodejs" %}

```javascript
var request = require('request');
var options = {
   'method': 'POST',
   'url': '/api/v4/consumption_sync_offline/',
   'headers': {
      'Accept': 'application/json',
      'Content-Type': 'text/plain',
      'Date': 'string',
      'Authorization': 'string'
   },
   body: requestBody // the base64 envelope, see Finalized payload
};

request(options, function (error, response) {
   if (error) throw new Error(error);
   console.log(response.body);
});
```

{% endtab %}

{% tab title="javascript" %}

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

var requestOptions = {
   method: 'POST',
   headers: myHeaders,
   body: requestBody, // the base64 envelope, see Finalized payload
   redirect: 'follow'
};

fetch("/api/v4/consumption_sync_offline/", 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_offline/"

payload = "_BASE64_PAYLOAD_HERE_"
headers = {
   'Accept': 'application/json',
   'Content-Type': 'text/plain',
   'Date': 'string',
   'Authorization': 'string'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)
```

{% endtab %}

{% tab title="ruby" %}

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

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

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

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

{% endtab %}
{% endtabs %}

***

### Schema

#### Request Body

The decoded file is an envelope: \
`{ "request": <sync request object>, "signature": <signature> }`.\
\
The sync request object is the same as for the [online method](https://docs.licensespring.com/license-api/consumption/consumption-sync-online-method.md), plus the offline fields `date`, `api_key` or `client_id`, and, for device-bound licenses, `signature` and the TPM or hardware-key signature.

{% hint style="danger" %}
If using "multipart/form-data" for the request, the "file" form parameter is mandatory
{% endhint %}

<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 ConsumptionSyncOfflineRequestObject = {

  // required properties:
  schema_version: 1,
  request: 'sync',
  request_id: string,
  date: string,
  hardware_id: string,
  licenses: { [productCode: string]: SyncLicenseEntry },

} & ({
  api_key: string // for API key authorization
} | {
  client_id: string // for OAuth authorization
}) & {

  // required for TPM and hardware-key licenses:
  signature?: string | undefined,
  'licensespring-tpm-signature'?: string | undefined,
  'licensespring-hardware-key'?: string | undefined,
}

type ConsumptionSyncOfflineEnvelope = {
  request: ConsumptionSyncOfflineRequestObject,
  signature: string,
}
```

**JSON Schema** (the `request` object)

```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 },
    "date": { "type": "string" },
    "hardware_id": { "type": "string" },
    "api_key": { "type": "string" },
    "client_id": { "type": "string" },
    "signature": { "type": "string" },
    "licensespring-tpm-signature": { "type": "string" },
    "licensespring-hardware-key": { "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"]
      }
    }
  },
  "anyOf": [{ "required": ["api_key"] }, { "required": ["client_id"] }],
  "required": ["schema_version", "request", "request_id", "date", "hardware_id", "licenses"]
}
```

</details>

The fields of the request object are described on the [online method](https://docs.licensespring.com/license-api/consumption/consumption-sync-online-method.md) page (license entries, resources and events). The offline-only fields:

* `date` (string) — ISO 8601 UTC date the request file was created
* `api_key` (string) or `client_id` (string) — `client_id` for OAuth-configured accounts
* `signature` (string) — the v1 offline signature, required for TPM and hardware-key licenses, see [Device-bound licenses](#device-bound-licenses)
* `licensespring-tpm-signature` / `licensespring-hardware-key` (string) — TPM and hardware-key licenses only

***

### Signature

The envelope `signature` is an HMAC-SHA256 over the request object, signed with the company shared key (or client secret for OAuth):

{% stepper %}
{% step %}

### Step

Build the sync request object, including `date` and `api_key` (or `client_id`).
{% endstep %}

{% step %}

### Step

Serialize it to compact JSON.
{% endstep %}

{% step %}

### Step

HMAC-SHA256 that JSON string with the signing key and encode the result as base64.
{% endstep %}

{% step %}

### Step

Put the same JSON string, unchanged, under `request` in the envelope, next to `signature`. The signature is verified over the exact bytes of `request` as they appear in the file.
{% endstep %}
{% endstepper %}

Example (Node.js):

```javascript
import crypto from 'node:crypto';

const syncRequest = {
  schema_version: 1,
  request: 'sync',
  request_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
  date: new Date().toISOString(),
  hardware_id: 'some-unique-id',
  api_key: '...', // or client_id for OAuth
  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' }]
        }
      }
    }
  }
};

// if using API key authorization: the signing key is the Shared Key
// if using OAuth: the signing key is the Client Secret
const signingKey = '...';

const requestJson = JSON.stringify(syncRequest);
const signature = crypto
  .createHmac('sha256', signingKey)
  .update(requestJson)
  .digest('base64');
```

#### Device-bound licenses

For TPM and hardware-key licenses, the request object also carries a v1 offline `signature`, built like the signature of an [offline activation request](https://docs.licensespring.com/license-api/license-activation-and-deactivation/activate-license-offline-method.md): \
`HMAC-SHA256("licenseSpring\ndate: <date>\n<license_key or username>\n<hardware_id>\n<api_key or client_id>", signingKey)`, base64-encoded. \
\
For a bundle, use the bundle's license key. \
\
The `licensespring-tpm-signature` or `licensespring-hardware-key` field then signs that v1 signature. Add these fields before computing the envelope signature.

***

### Finalized payload

Wrap the request JSON and its signature in the envelope and encode it to base64.

{% tabs %}
{% tab title="JS Browser" %}

```javascript
const requestBody = btoa(`{"request":${requestJson},"signature":"${signature}"}`);
```

{% endtab %}

{% tab title="nodeJS" %}

```javascript
const requestBody = Buffer.from(`{"request":${requestJson},"signature":"${signature}"}`).toString('base64');
```

{% endtab %}
{% endtabs %}

Send the resulting base64 string as the raw request body, or as the `file` field of a multipart request.

***

### Response Body

On success, the endpoint responds with HTTP 200 and the downloadable file \
`sync_response.lic` (`Content-Disposition: attachment`). \
\
The file contains the same JSON as the [online method](https://docs.licensespring.com/license-api/consumption/consumption-sync-online-method.md) response, and the response carries the same `LicenseSignature` header.

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

* `request_id` — echoes the request file's `request_id`. Discard a response file whose `request_id` doesn't match the pending request.
* `processed_ids` — every applied event ID, including IDs applied by an earlier sync; remove exactly these from the local journal. `count` is the total actually applied for them.
* `rejected_ids` — events that were not applied, with a code; see [Rejection codes](https://docs.licensespring.com/license-api/consumption/consumption-sync-online-method.md#rejection-codes) for which ones to retry.
* Anything from the request that appears in neither `processed_ids` nor `rejected_ids`, including an omitted product, is still pending and belongs in the next request file.
* `offline_checkout` — present when the device holds an offline checkout from a consumption pool. Synced usage is recorded in `consumed`; a sync never applies more than `remaining`.

### Response signatures

Each product entry in the response file is signed three ways:

* `license_signature` — HMAC-SHA256 signature explained in [Response Signature](https://docs.licensespring.com/license-api/license-api-authorization/response-signature.md).
* `offline_signature` — HMAC-SHA256 signature constructed identically to the v1 request `signature` (see [Device-bound licenses](#device-bound-licenses)), but using the response `date` value.
* `license_signature_v2` — RSA-SHA256 signature over the product entry's compact JSON, in the key order received, with only the `license_signature_v2` field removed.

### 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 from the file is applied and no response file is produced. 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_content (400)</strong></summary>

The request has no body, or no file in a multipart request

</details>

<details>

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

The envelope `signature` does not verify against the request object

</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`, or both `api_key` and `client_id` are missing

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

{% hint style="info" %}
If you want to use this API endpoint directly, instead of using an SDK (which does most of the heavy lifting for you), please contact us for additional instructions.
{% endhint %}

***

### Deactivating after a sync

[Deactivate License (Offline Method)](https://docs.licensespring.com/license-api/license-activation-and-deactivation/deactivate-license-offline-method.md) does not accept sync events. After a device has synced, the `consumptions` in its deactivation file 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.

***

### Guide on using Offline Licenses

If any aspect of the offline licensing model remains unclear, see [Offline License Activation](https://docs.licensespring.com/license-entitlements/license-activation-types/offline-license-activation.md).


---

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