Add Consumption

10min
Adds 1 or more consumptions to a license (only for consumption-type licenses)
POST
Request
Header Parameters
Date
String
required
In RFC7231 format (see "License API Authorization"), eg.: Thu, 17 Nov 2022 20:51:35 GMT
Authorization
String
required
See "License API Authorization" article
Body Parameters
hardware_id
String
required
Unique hardware ID generated for the client device
product
String
required
Product short code
license_key
String
optional
Required if product is key-based (see section below)
username
String
optional
Required if product is user based (see section below)
license_id
Number
optional
Ensures that the action affects only the license with the specified ID. This is useful if e.g. you have multiple licenses for the same product assigned to the same user. For obtaining a list of licenses assigned to a user, see "User Licenses"
consumptions
Number
optional
Number of consumptions to add, defaults to 1. May be negative, unless `allow_negative_consumptions` is set to false
max_overages
String
optional
Maximum number of overages
allow_overages
String
optional
Allow or disallow overages
event
Array
optional
An optional array of strings specifying which events will be recorded in the activity log for this request. Currently can be either `consumption_add` (default) or `offline_floating_consumptions_sync` (these 2 events are mutually exclusive)
Curl
Node.js
JS
Python
Ruby
import requests

url = "/api/v4/add_consumption"

payload = "{\"hardware_id\":\"String\",\"product\":\"string\",\"license_key\":\"string\",\"username\":\"string\",\"consumptions\":\"Number\",\"max_overages\":\"string\",\"allow_overages\":\"string\"}"
headers = {
   'Accept': 'application/json',
   'Date': 'string',
   'Authorization': 'string'
}

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

print(response.text)

import requests

url = "/api/v4/add_consumption"

payload = "{\"hardware_id\":\"String\",\"product\":\"string\",\"license_key\":\"string\",\"username\":\"string\",\"consumptions\":\"Number\",\"max_overages\":\"string\",\"allow_overages\":\"string\"}"
headers = {
   'Accept': 'application/json',
   'Date': 'string',
   'Authorization': 'string'
}

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

print(response.text)
Responses
200
400
{
    "id": 12345,
    "max_consumptions": 4,
    "total_consumptions": 9,
    "allow_overages": true,
    "max_overages": 5,
    "allow_negative_consumptions": true,
    "allow_unlimited_consumptions": false,
    "reset_consumption": false,
    "consumpton_period": "monthly"
}
{
    "id": 12345,
    "max_consumptions": 4,
    "total_consumptions": 9,
    "allow_overages": true,
    "max_overages": 5,
    "allow_negative_consumptions": true,
    "allow_unlimited_consumptions": false,
    "reset_consumption": false,
    "consumpton_period": "monthly"
}
﻿
Schema
Request Body
TypeScript
JSON Schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "allOf": [
    {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "license_key": { "type": "string" }
          },
          "required": ["license_key"],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "username": { "type": "string" }
          },
          "required": ["username"],
          "additionalProperties": false
        }
      ]
    },
    {
      "type": "object",
      "properties": {
        "hardware_id": { "type": "string" },
        "product": { "type": "string" },
        "license_id": { "type": "number" },
        "consumptions": { "type": "number" },
        "max_overages": { "type": "number" },
        "allow_overages": { "type": "number" },
        "event": {
          "type": "array",
          "items": { "type": "string", "enum": ["consumption_add", "offline_floating_consumptions_sync"] },
          "minItems": 1,
          "not": {
            "allOf": [
              { "contains": { "const": "consumption_add" } },
              { "contains": { "const": "offline_floating_consumptions_sync" } }
            ]
          }
        }
      },
      "required": ["hardware_id", "product"],
      "additionalProperties": false
    }
  ]
}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "allOf": [
    {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "license_key": { "type": "string" }
          },
          "required": ["license_key"],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "username": { "type": "string" }
          },
          "required": ["username"],
          "additionalProperties": false
        }
      ]
    },
    {
      "type": "object",
      "properties": {
        "hardware_id": { "type": "string" },
        "product": { "type": "string" },
        "license_id": { "type": "number" },
        "consumptions": { "type": "number" },
        "max_overages": { "type": "number" },
        "allow_overages": { "type": "number" },
        "event": {
          "type": "array",
          "items": { "type": "string", "enum": ["consumption_add", "offline_floating_consumptions_sync"] },
          "minItems": 1,
          "not": {
            "allOf": [
              { "contains": { "const": "consumption_add" } },
              { "contains": { "const": "offline_floating_consumptions_sync" } }
            ]
          }
        }
      },
      "required": ["hardware_id", "product"],
      "additionalProperties": false
    }
  ]
}
﻿
Response Body
TypeScript
JSON Schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": { "type": "number" },
    "max_consumptions": { "type": "number" },
    "total_consumptions": { "type": "number" },
    "allow_unlimited_consumptions": { "type": "boolean" },
    "allow_negative_consumptions": { "type": "boolean" },
    "allow_overages": { "type": "boolean" },
    "max_overages": { "type": "number" },
    "reset_consumption": { "type": "boolean" },
    "consumption_period": { "type": [ "string", "null" ], "enum": [ "daily", "weekly", "monthly", "annually", null ] },
  },
  "required": [
    "id",
    "max_consumptions",
    "total_consumptions",
    "allow_unlimited_consumptions",
    "allow_negative_consumptions",
    "allow_overages",
    "max_overages",
    "reset_consumption",
    "consumption_period"
  ],
  "additionalProperties": false
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": { "type": "number" },
    "max_consumptions": { "type": "number" },
    "total_consumptions": { "type": "number" },
    "allow_unlimited_consumptions": { "type": "boolean" },
    "allow_negative_consumptions": { "type": "boolean" },
    "allow_overages": { "type": "boolean" },
    "max_overages": { "type": "number" },
    "reset_consumption": { "type": "boolean" },
    "consumption_period": { "type": [ "string", "null" ], "enum": [ "daily", "weekly", "monthly", "annually", null ] },
  },
  "required": [
    "id",
    "max_consumptions",
    "total_consumptions",
    "allow_unlimited_consumptions",
    "allow_negative_consumptions",
    "allow_overages",
    "max_overages",
    "reset_consumption",
    "consumption_period"
  ],
  "additionalProperties": false
}
﻿
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: client interactions with the license have to be authorized using a license_key
User-based product licenses: the license has a corresponding "license user" instead of a license key. Client interactions with the license have to be authorized using a username 
Errors
If an error occurs, the response will have an HTTP status code of 400 or higher, and the response body will contain an error description in the following format:
TypeScript
JSON
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": { "type": "number" },
    "code": { "type": "string" },
    "message": { "type": "string" }
  },
  "required": [
    "status",
    "code",
    "message"
  ],
  "additionalProperties": false
}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": { "type": "number" },
    "code": { "type": "string" },
    "message": { "type": "string" }
  },
  "required": [
    "status",
    "code",
    "message"
  ],
  "additionalProperties": false
}
﻿
List of exceptions
unknown_product (400): Provided product was not found
license_not_found (400): License with the provided license user not found
license_not_active (400): The license is not active
license_not_enabled (400): The license is not enabled
license_not_consumption (400): The license needs to be of consumption type
license_not_enough_consumptions (400): Not enough consumptions left
negative_consumptions_not_allowed (400): Negative consumptions not allowed
device_not_found (400): An active device matching the hardware_id not found
blacklisted (400): This device is blacklisted
﻿
Updated 10 Feb 2025
Did this page help you?
Consumption
Add Feature Consumption