Create Order

URL : /api/v1/orders/create_order/

Method : POST

Parameters

id - String
- required
- Order ID. This is a unique identifier for an order within a company
is_bundle - Boolean
- optional
- If true, defines the order as a bundle order. Defaults to false. For more details on bundle orders, see the Bundle section below
append - Boolean
- optional
- If set to true and order ID already exists, licenses (items) sent will be appended to the existing order. If set to false and order ID already exists, an error will be returned. If not set defaults to false.
is_test - Boolean
- optional
- Whether or not this is a test order
created - String
- optional
- Date and time order is created
order_type - String
- optional
- Current possible value is: normal
language - String
- optional
- Order language, value should be language short code
campaign_params - String
- optional
- e.g. Google campaign params for the order
download_id - String
- optional
- Custom order download ID
prevent_vm - Boolean
- optional
- If set to true, license activation won't be possible on a Virtual Machine
metadata - String
- optional
- Custom metadata, in the format of a serialized JSON object
items - Array of Objects
- each object can contain
  - product_code - String
    required
    Product code to identify the product license order is being created for
  - licenses - Array
    A list of license definitions for this order. See the Licenses section below for more details
  - note - String
    optional
customer - Object
- can contain
  - email - String
    optional
    customer's email address
  - first_name - String
    optional
    customer's first name
  - last_name - String
    optional
    customer's last name
  - company - String
    optional
    customer's company name
  - phone - String
    optional
    customer's phone number
  - address - String
    optional
    customer's address
  - reference - String
    optional
    customer's custom reference. This can be any identifier for the customer in your system like an UUID.
  - is_manager - Boolean
    optional
    if true, customer will be set as manager of licenses in this order
customer_account_id - Integer
- optional
- Assignes the order to a Customer Account. If the provided Customer is already assigned to a Customer Account, you can omit this value
add_to_customer_account - Boolean
- optional
- Determines whether the Order will be assigned to a Customer Account (defaults to true). If you're providing a Customer who is assigned to a Customer Account, but do not wish the Order to be automatically assigned to that same Customer Account, set this parameter to false

Notes

Metadata should be in literal string format, e.g: "metadata": "{ "some_key": "some_value" }" .

The id property in the request is a client-generated unique identifier for the request, such as a uuid string.

If append is set to true and no order with the given ID exists, a new order will be created.

Request

Non-Bundle Order Request

Typescript

type RequestSchema = {
  id: string;
  append?: boolean;
  campaign_params?: string;
  created?: string;
  download_id?: string;
  include_metadata_string?: boolean;
  is_test?: boolean;
  language?: string;
  prevent_vm?: boolean;
  add_to_customer_account?: boolean;
  customer?: Customer;
  items: Item[];
}

type Item = {
  active?: boolean;
  customer_account_id?: number;
  key?: string;
  license_policy?: string;
  note?: string;
  product_code: string;
  subscription_id?: string;
  licenses: License[];
}

type Customer = {
  email?: string;
  first_name?: string;
  last_name?: string;
  company_name?: string;
  phone?: string;
  reference?: string;
}

type License = (LicenseWithKey | LicenseWithUsers) & LicenseOptional;

type LicenseWithKey = {
  key?: string;
}

type LicenseWithUsers = {
  users: {
    email: string;
    is_manager?: boolean;
    max_activations?: number;
  }[];
}

type LicenseOptional = {
  active?: boolean,
  allow_grace_period?: boolean,
  allow_negative_consumptions?: boolean,
  allow_overages?: boolean,
  allow_unlimited_activations?: boolean,
  allow_unlimited_consumptions?: boolean,
  can_borrow?: boolean,
  consumption_period?: 'daily' | 'weekly' | 'monthly' | 'annually',
  enable_maintenance_period?: boolean,
  enabled?: boolean,
  floating_timeout?: number,
  floating_users?: number,
  grace_period?: number,
  is_air_gapped?: boolean,
  is_floating_cloud?: boolean,
  is_floating?: boolean,
  is_hardware_key_auth?: boolean,
  is_trial?: boolean,
  license_template_code?: string,
  license_template?: number,
  license_type?: LicenseTypes,
  maintenance_duration?: string,
  maintenance_period?: string,
  max_activations?: number,
  max_borrow_time?: number,
  max_consumptions?: number,
  max_license_users?: number,
  max_overages?: number,
  max_transfers?: number,
  metadata?: JSONObjectRequired | null,
  policy_code?: string,
  prevent_vm?: boolean,
  reset_consumption?: boolean,
  start_date?: string,
  subscription_id?: string,
  trial_days?: number,
  valid_duration?: string,
  validity_period?: string,
  custom_fields?: CustomField[],
  product_features?: ProductFeature[],
}

type CustomField = {
  name: string,
  data_type: 'numer' | 'text' | 'date/time',
  value: string | undefined;
};

type ProductFeature = 'string' | {
  code: string,
  allow_overages?: boolean,
  allow_unlimited_consumptions?: boolean,
  allow_negative_consumptions?: boolean,
  consumption_period?: 'daily' | 'weekly' | 'monthly' | 'annually',
  expiry_date?: string,
  floating_timeout?: number,
  floating_users?: number,
  is_floating_cloud?: boolean,
  is_floating?: boolean,
  max_consumption?: number,
  max_overages?: number,
  metadata?: JSONObjectRequired,
  reset_consumption?: boolean,
};

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "RequestSchema",
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "append": { "type": "boolean" },
    "campaign_params": { "type": "string" },
    "created": { "type": "string" },
    "download_id": { "type": "string" },
    "include_metadata_string": { "type": "boolean" },
    "is_test": { "type": "boolean" },
    "language": { "type": "string" },
    "prevent_vm": { "type": "boolean" },
    "add_to_customer_account": { "type": "boolean" },
    "customer": { "$ref": "#/$defs/Customer" },
    "items": {
      "type": "array",
      "items": { "$ref": "#/$defs/Item" }
    }
  },
  "required": [
    "id",
    "items"
  ],
  "additionalProperties": false,
  "$defs": {
    "Customer": {
      "type": "object",
      "properties": {
        "email": { "type": "string" },
        "first_name": { "type": "string" },
        "last_name": { "type": "string" },
        "company_name": { "type": "string" },
        "phone": { "type": "string" },
        "reference": { "type": "string" }
      },
      "additionalProperties": false
    },
    "Item": {
      "type": "object",
      "properties": {
        "active": { "type": "boolean" },
        "customer_account_id": { "type": "number" },
        "key": { "type": "string" },
        "license_policy": { "type": "string" },
        "note": { "type": "string" },
        "product_code": { "type": "string" },
        "subscription_id": { "type": "string" },
        "licenses": {
          "type": "array",
          "items": { "$ref": "#/$defs/License" }
        }
      },
      "required": [
        "product_code",
        "licenses"
      ],
      "additionalProperties": false
    },
    "License": {
      "allOf": [
        {
          "oneOf": [
            { "$ref": "#/$defs/LicenseWithKey" },
            { "$ref": "#/$defs/LicenseWithUsers" }
          ]
        },
        { "$ref": "#/$defs/LicenseOptional" }
      ]
    },
    "LicenseWithKey": {
      "type": "object",
      "properties": {
        "key": { "type": "string" }
      },
      "additionalProperties": false
    },
    "LicenseWithUsers": {
      "type": "object",
      "properties": {
        "users": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "email": { "type": "string" },
              "is_manager": { "type": "boolean" }
            },
            "required": ["email"],
            "additionalProperties": false
          }
        }
      },
      "required": ["users"],
      "additionalProperties": false
    },
    "LicenseOptional": {
      "type": "object",
      "properties": {
        "active": { "type": "boolean" },
        "allow_grace_period": { "type": "boolean" },
        "allow_negative_consumptions": { "type": "boolean" },
        "allow_overages": { "type": "boolean" },
        "allow_unlimited_activations": { "type": "boolean" },
        "allow_unlimited_consumptions": { "type": "boolean" },
        "can_borrow": { "type": "boolean" },
        "consumption_period": { "type": "string", "enum": ["daily","weekly","monthly","annually"] },
        "enable_maintenance_period": { "type": "boolean" },
        "enabled": { "type": "boolean" },
        "floating_timeout": { "type": "number" },
        "floating_users": { "type": "number" },
        "grace_period": { "type": "number" },
        "is_air_gapped": { "type": "boolean" },
        "is_floating_cloud": { "type": "boolean" },
        "is_floating": { "type": "boolean" },
        "is_hardware_key_auth": { "type": "boolean" },
        "is_trial": { "type": "boolean" },
        "license_template_code": { "type": "string" },
        "license_template": { "type": "number" },
        "license_type": { "$ref": "#/$defs/LicenseTypes" },
        "maintenance_duration": { "type": "string" },
        "maintenance_period": { "type": "string" },
        "max_activations": { "type": "number" },
        "max_borrow_time": { "type": "number" },
        "max_consumptions": { "type": "number" },
        "max_license_users": { "type": "number" },
        "max_overages": { "type": "number" },
        "max_transfers": { "type": "number" },
        "metadata": {
          "anyOf": [
            { "$ref": "#/$defs/JSONObjectRequired" },
            { "type": "null" }
          ]
        },
        "policy_code": { "type": "string" },
        "prevent_vm": { "type": "boolean" },
        "reset_consumption": { "type": "boolean" },
        "start_date": { "type": "string" },
        "subscription_id": { "type": "string" },
        "trial_days": { "type": "number" },
        "valid_duration": { "type": "string" },
        "validity_period": { "type": "string" },
        "custom_fields": {
          "type": "array",
          "items": { "$ref": "#/$defs/CustomField" }
        },
        "product_features": {
          "type": "array",
          "items": { "$ref": "#/$defs/ProductFeature" }
        }
      },
      "additionalProperties": false
    },
    "CustomField": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "data_type": { "enum": ["numer", "text", "date/time"] },
        "value": { "type": "string" }
      },
      "required": ["name", "data_type"],
      "additionalProperties": false
    },
    "ProductFeature": {
      "oneOf": [
        { "type": "string", "const": "string" },
        {
          "type": "object",
          "properties": {
            "code": { "type": "string" },
            "allow_overages": { "type": "boolean" },
            "allow_unlimited_consumptions": { "type": "boolean" },
            "allow_negative_consumptions": { "type": "boolean" },
            "consumption_period": { "type": "string", "enum": ["daily","weekly","monthly","annually"] },
            "expiry_date": { "type": "string" },
            "floating_timeout": { "type": "number" },
            "floating_users": { "type": "number" },
            "is_floating_cloud": { "type": "boolean" },
            "is_floating": { "type": "boolean" },
            "max_consumption": { "type": "number" },
            "max_overages": { "type": "number" },
            "metadata": { "$ref": "#/$defs/JSONObjectRequired" },
            "reset_consumption": { "type": "boolean" }
          },
          "required": ["code"],
          "additionalProperties": false
        }
      ]
    },
    "JSONObjectRequired": {
      "type": "object",
      "additionalProperties": true
    },
    "LicenseTypes": {
      "enum": [
        "perpetual",
        "subscription",
        "consumption",
        "time-limited"
      ]
    }
  }
}

Example: Key-based license

{
  "id": "id_1546606209296",
  "items": [
    {
      "product_code": "TT",
      "note": "Test 1",  // global note applied to all licenses if no license-level note exists
      "licenses": [
        {
          "key": "123-123-123-123-123",
          "note": "Test 2"  // specific note for this license, overrides global note
        }
      ]
    }
  ]
}

Example: User-based license

{
  "id": "id_1546606209296",
  "items": [
    {
      "product_code": "TT",
      "note": "Test 1",  // global note for the product/item
      "licenses": [
        {
          "users": [
            {
              "email": "[email protected]",
              "is_manager": false
            }
          ],
          "note": "Test 2"  // specific note for this license, overrides global note
        }
      ]
    }
  ]
}

Bundle Order Request

Typescript

type Schema = {
  id: string;
  is_bundle: true;
  append?: boolean;
  campaign_params?: string;
  created?: string;
  download_id?: string;
  include_metadata_string?: boolean;
  is_test?: boolean;
  language?: string;
  prevent_vm?: boolean;
  add_to_customer_account?: boolean;
  customer?: Customer | null;
  items: Item[];
}

type Item = {
  active?: boolean;
  customer_account_id?: number;
  key?: string;
  license_policy?: string;
  note?: string;
  product_code: string;
  subscription_id?: string;
  licenses: License[];
}

type Customer = {
  email?: string;
  first_name?: string;
  last_name?: string;
  company_name?: string;
  phone?: string;
  reference?: string;
}

type LicenseWithKey = {
  key?: string;
  license_template_code?: string;
  policy_code: string;
  allow_negative_consumptions?: boolean;
}

type LicenseWithUsers = {
  product_code: string;
  users: {
    email: string;
    is_manager?: boolean;
  }[];
}

type License = (LicenseWithKey | LicenseWithUsers) & LicenseOptional;

type LicenseCommon = {
  active?: boolean,
  allow_grace_period?: boolean,
  allow_negative_consumptions?: boolean,
  allow_overages?: boolean,
  allow_unlimited_activations?: boolean,
  allow_unlimited_consumptions?: boolean,
  can_borrow?: boolean,
  consumption_period?: 'daily' | 'weekly' | 'monthly' | 'annually',
  enable_maintenance_period?: boolean,
  enabled?: boolean,
  floating_timeout?: number,
  floating_users?: number,
  grace_period?: number,
  is_air_gapped?: boolean,
  is_floating_cloud?: boolean,
  is_floating?: boolean,
  is_hardware_key_auth?: boolean,
  is_trial?: boolean,
  license_template_code?: string,
  license_template?: number,
  license_type?: LicenseTypes,
  maintenance_duration?: string,
  maintenance_period?: string,
  max_activations?: number,
  max_borrow_time?: number,
  max_consumptions?: number,
  max_license_users?: number,
  max_overages?: number,
  max_transfers?: number,
  metadata?: JSONObjectRequired | null,
  policy_code?: string,
  prevent_vm?: boolean,
  reset_consumption?: boolean,
  start_date?: string,
  subscription_id?: string,
  trial_days?: number,
  valid_duration?: string,
  validity_period?: string,
  custom_fields?: CustomField[],
  product_features?: ProductFeature[],
}

type CustomField = {
  name: string,
  data_type: 'numer' | 'text' | 'date/time',
  value: string | undefined;
};

type ProductFeature = 'string' | {
  code: string,
  allow_overages?: boolean,
  allow_unlimited_consumptions?: boolean,
  allow_negative_consumptions?: boolean,
  consumption_period?: 'daily' | 'weekly' | 'monthly' | 'annually',
  expiry_date?: string,
  floating_timeout?: number,
  floating_users?: number,
  is_floating_cloud?: boolean,
  is_floating?: boolean,
  max_consumption?: number,
  max_overages?: number,
  metadata?: JSONObjectRequired,
  reset_consumption?: boolean,
};

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Schema",
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "is_bundle": { "const": true },
    "append": { "type": "boolean" },
    "campaign_params": { "type": "string" },
    "created": { "type": "string" },
    "download_id": { "type": "string" },
    "include_metadata_string": { "type": "boolean" },
    "is_test": { "type": "boolean" },
    "language": { "type": "string" },
    "prevent_vm": { "type": "boolean" },
    "add_to_customer_account": { "type": "boolean" },
    "customer": {
      "oneOf": [
        { "$ref": "#/$defs/Customer" },
        { "type": "null" }
      ]
    },
    "items": {
      "type": "array",
      "items": { "$ref": "#/$defs/Item" }
    }
  },
  "required": ["id", "is_bundle", "items"],
  "additionalProperties": false,
  "$defs": {
    "Customer": {
      "type": "object",
      "properties": {
        "email": { "type": "string" },
        "first_name": { "type": "string" },
        "last_name": { "type": "string" },
        "company_name": { "type": "string" },
        "phone": { "type": "string" },
        "reference": { "type": "string" }
      },
      "additionalProperties": false
    },
    "Item": {
      "type": "object",
      "properties": {
        "active": { "type": "boolean" },
        "customer_account_id": { "type": "number" },
        "key": { "type": "string" },
        "license_policy": { "type": "string" },
        "note": { "type": "string" },
        "product_code": { "type": "string" },
        "subscription_id": { "type": "string" },
        "licenses": {
          "type": "array",
          "items": { "$ref": "#/$defs/License" }
        }
      },
      "required": ["product_code", "licenses"],
      "additionalProperties": false
    },
    "License": {
      "allOf": [
        {
          "oneOf": [
            { "$ref": "#/$defs/LicenseWithKey" },
            { "$ref": "#/$defs/LicenseWithUsers" }
          ]
        },
        { "$ref": "#/$defs/LicenseOptional" }
      ]
    },
    "LicenseWithKey": {
      "type": "object",
      "properties": {
        "key": { "type": "string" },
        "license_template_code": { "type": "string" },
        "policy_code": { "type": "string" },
        "allow_negative_consumptions": { "type": "boolean" }
      },
      "required": ["policy_code"],
      "additionalProperties": false
    },
    "LicenseWithUsers": {
      "type": "object",
      "properties": {
        "product_code": { "type": "string" },
        "users": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "email": { "type": "string" },
              "is_manager": { "type": "boolean" }
            },
            "required": ["email"],
            "additionalProperties": false
          }
        }
      },
      "required": ["product_code", "users"],
      "additionalProperties": false
    },
    "LicenseOptional": {
      "type": "object",
      "properties": {
        "active": { "type": "boolean" },
        "allow_grace_period": { "type": "boolean" },
        "allow_negative_consumptions": { "type": "boolean" },
        "allow_overages": { "type": "boolean" },
        "allow_unlimited_activations": { "type": "boolean" },
        "allow_unlimited_consumptions":

Example: Key-based bundle

{
  "id": "45gvs334t3edsa",
  "is_bundle": true,
  "items": [
    {
      "product_code": "lkpb",
      "note": "Global note for bundle lkpb",  // global note applied to all licenses if no license-level note exists
      "key": "AAAA-AAAA-AAAA-1130",
      "active": true,
      "subscription_id": 12345,
      "licenses": [
        {
          "product_code": "lkbp1",
          "note": "Note for lkbp1"  // specific note for this license
        },
        {
          "product_code": "lkbp2",
          "note": "Note for lkbp2"  // specific note for this license
        }
      ]
    }
  ]
}

Example: User-based bundle

{
  "id": "54yghtref45t",
  "is_bundle": true,
  "items": [
    {
      "product_code": "upb",
      "note": "Global note for bundle upb",  // global note applied to all licenses if no license-level note exists
      "licenses": [
        {
          "active": true,
          "max_activations": 30,
          "product_code": "up",
          "is_trial": false,
          "policy_code": "dftlp",
          "note": "Specific note for this license",  // specific note overrides global note
          "custom_fields": [
            {
              "name": "customField1",
              "value": "abcd"
            }
          ]
        }
      ],
      "users": [
        {
          "email": "[email protected]",
          "is_manager": false
        }
      ]
    }
  ]
}

Notes overview

Global note → applied to all licenses
License-level note → applies only to that license
Both → license-level note takes priority
None → no note field included

Response

Non-Bundle Order Response

TypeScript

type OrderResponse = {
  order_id: string,
  order_items: [
    {
      id: number,
      product_id: number,
      Licenses: License[],
    }
  ],
  new_passwords: { email: string, password: string }[],
}

type License = LicenseCommon & ({
  license_key: string;
  users: never;
  max_license_users: never;
} | {
  license_key: never;
  users: {
    email: string,
    first_name?: string,
    last_name?: string,
    phone_number?: string,
    is_manager: boolean,
  }[];
  max_license_users: number;
}) & ({
  license_type: 'perpetual'
} | {
  license_type: 'subscription';
  allow_grace_period: boolean;
  grace_period: number;
  time_activated: number;
} | {
  license_type: 'consumption';
  allow_negative_consumptions: boolean;
  allow_overages: boolean;
  allow_unlimited_consumptions: boolean;
  consumption_period: string | null;
  max_consumptions: number;
  max_overages: number;
  reset_consumption: boolean;
} | {
  license_type: 'time-limited'
}) & ({
  enable_maintenance_period: false;
} | {
  enable_maintenance_period: true;
  maintenance_duration: string;
  maintenance_period?: string | null;
});

type LicenseCommon = {
  id: number,
  product_id: number,
  active: boolean,
  enabled: true,
  created_at: number,
  updated_at: number,
  license_type: LicenseTypes,
  max_activations: number,
  allow_unlimited_activations: boolean,
  valid_duration: string | null,
  floating_timeout: number,
  max_transfers: number,
  can_borrow: boolean,
  max_borrow_time: number,
  start_date: string | null,
  is_air_gapped: boolean,
  license_template_id: number | null,
  validity_period: string | null,
  subscription_id: string,
  enable_maintenance_period: boolean,
  is_floating_cloud: boolean,
  is_floating: boolean,
  floating_users: number,
  is_trial: boolean,
  trial_days: number,
  prevent_vm: boolean,
  metadata: Record<string, any>,
  is_hardware_key_auth: boolean,
  order_id: number,
  LicenseCustomFields: {
    product_custom_field_id: number;
    value: string | undefined;
  }[],
  LicenseProductFeatures: {
    id: number,
    allow_negative_consumptions: boolean,
    allow_overages: boolean,
    allow_unlimited_consumptions: boolean,
    consumption_period?: string,
    expiry_date: string | null,
    floating_timeout: number,
    floating_users?: number,
    is_floating_cloud?: boolean,
    is_floating?: boolean,
    max_consumption: number,
    max_overages: number,
    metadata: Record<string, any>,
    name?: string,
    product_feature_id: number,
    reset_consumption: boolean,
  }[],
};

enum LicenseTypes {
  perpetual = 'perpetual',
  time_limited = 'time-limited',
  consumption = 'consumption',
  subscription = 'subscription',
};

Json Schema

type OrderResponse = {
  order_id: string,
  order_items: [
    {
      id: number,
      product_id: number,
      Licenses: License[],
    }
  ],
  new_passwords: { email: string, password: string }[],
}

type License = LicenseCommon & ({
  license_key: string;
  users: never;
  max_license_users: never;
} | {
  license_key: never;
  users: {
    email: string,
    first_name?: string,
    last_name?: string,
    phone_number?: string,
    is_manager: boolean,
  }[];
  max_license_users: number;
}) & ({
  license_type: 'perpetual'
} | {
  license_type: 'subscription';
  allow_grace_period: boolean;
  grace_period: number;
  time_activated: number;
} | {
  license_type: 'consumption';
  allow_negative_consumptions: boolean;
  allow_overages: boolean;
  allow_unlimited_consumptions: boolean;
  consumption_period: string | null;
  max_consumptions: number;
  max_overages: number;
  reset_consumption: boolean;
} | {
  license_type: 'time-limited'
}) & ({
  enable_maintenance_period: false;
} | {
  enable_maintenance_period: true;
  maintenance_duration: string;
  maintenance_period?: string | null;
});

type LicenseCommon = {
  id: number,
  product_id: number,
  active: boolean,
  enabled: true,
  created_at: number,
  updated_at: number,
  license_type: LicenseTypes,
  max_activations: number,
  allow_unlimited_activations: boolean,
  valid_duration: string | null,
  floating_timeout: number,
  max_transfers: number,
  can_borrow: boolean,
  max_borrow_time: number,
  start_date: string | null,
  is_air_gapped: boolean,
  license_template_id: number | null,
  validity_period: string | null,
  subscription_id: string,
  enable_maintenance_period: boolean,
  is_floating_cloud: boolean,
  is_floating: boolean,
  floating_users: number,
  is_trial: boolean,
  trial_days: number,
  prevent_vm: boolean,
  metadata: Record<string, any>,
  is_hardware_key_auth: boolean,
  order_id: number,
  LicenseCustomFields: {
    product_custom_field_id: number;
    value: string | undefined;
  }[],
  LicenseProductFeatures: {
    id: number,
    allow_negative_consumptions: boolean,
    allow_overages: boolean,
    allow_unlimited_consumptions: boolean,
    consumption_period?: string,
    expiry_date: string | null,
    floating_timeout: number,
    floating_users?: number,
    is_floating_cloud?: boolean,
    is_floating?: boolean,
    max_consumption: number,
    max_overages: number,
    metadata: Record<string, any>,
    name?: string,
    product_feature_id: number,
    reset_consumption: boolean,
  }[],
};

enum LicenseTypes {
  perpetual = 'perpetual',
  time_limited = 'time-limited',
  consumption = 'consumption',
  subscription = 'subscription',
};

Example response

{
  "order_id": "1740411907268009",
  "order_items": [
    {
      "id": "1740411907316029",
      "product_id": 1737539180381356,
      "licenses": [
        {
          "id": "1740411907281019",
          "product_id": 1737539180381356,
          "active": false,
          "enabled": true,
          "created_at": 1740411907285,
          "updated_at": 1740411907285,
          "license_type": "perpetual",
          "max_activations": 1,
          "allow_unlimited_activations": false,
          "valid_duration": null,
          "floating_timeout": 120,
          "max_transfers": 0,
          "can_borrow": false,
          "max_borrow_time": 0,
          "start_date": null,
          "is_air_gapped": false,
          "license_template_id": null,
          "validity_period": null,
          "subscription_id": "",
          "enable_maintenance_period": false,
          "is_floating_cloud": false,
          "is_floating": false,
          "floating_users": 0,
          "is_trial": false,
          "trial_days": 0,
          "prevent_vm": false,
          "metadata": {},
          "is_hardware_key_auth": false,
          "license_key": "B4E5-YAPF-B7YB-SHLK",
          "order_id": "1740411907268009",
          "LicenseProductFeatures": [],
          "LicenseCustomFields": []
        }
      ]
    }
  ],
  "new_passwords": [
    []
  ]
}

Bundle Order Response

TypeScript

type BundleOrderResponse = {
  order_id: string,
  order_items: [
    {
      id: number,
      product_id: number,
      Licenses: License[],
    }
  ],
  new_passwords: { email: string, password: string }[],
}

type License = BundleLicense | SubLicense;

type BundleLicense = LicenseCommon & {
  order_id: number,
  note?: string,
  is_bundle: true,
  time_activated?: number,
} & ({
  license_key: string;
  users: never;
  max_license_users: never;
} | {
  license_key: never;
  users: {
    email: string,
    first_name?: string,
    last_name?: string,
    phone_number?: string,
    is_manager: boolean,
  }[];
  max_license_users: number;
});

type SubLicense = LicenseCommon & {
  order_id: number,
  note?: string,
  bundle_license_id: number,
  LicenseCustomFields: {
    product_custom_field_id: number;
    value: string | undefined;
  }[],
  LicenseProductFeatures: {
    id: number,
    allow_negative_consumptions: boolean,
    allow_overages: boolean,
    allow_unlimited_consumptions: boolean,
    consumption_period?: 'daily' | 'weekly' | 'monthly' | 'annually',
    expiry_date: string | null,
    floating_timeout: number,
    floating_users?: number,
    is_floating_cloud?: boolean,
    is_floating?: boolean,
    max_consumption: number,
    max_overages: number,
    metadata: Record<string, any>,
    name?: string,
    product_feature_id: number,
    reset_consumption: boolean,
  }[],
}

type LicenseCommon = {
  id: number;
  active: boolean;
  allow_unlimited_activations: boolean;
  can_borrow: boolean;
  created_at: number;
  enabled: boolean;
  floating_timeout: number;
  floating_users: number;
  is_air_gapped: boolean;
  is_floating_cloud: boolean;
  is_floating: boolean;
  is_hardware_key_auth: boolean;
  is_trial: boolean;
  license_template_id?: number | null;
  max_activations: number;
  max_borrow_time: number;
  max_transfers: number;
  metadata: Record<string, any>;
  prevent_vm: boolean;
  product_id: number;
  start_date: string | null;
  subscription_id: string;
  trial_days: number;
  updated_at: number;
  valid_duration: string | null;
  validity_period?: string;
} & ({
  license_type: 'perpetual'
} | {
  license_type: 'subscription';
  allow_grace_period: boolean;
  grace_period: number;
  time_activated: number;
} | {
  license_type: 'consumption';
  allow_negative_consumptions: boolean;
  allow_overages: boolean;
  allow_unlimited_consumptions: boolean;
  consumption_period: 'daily' | 'weekly' | 'monthly' | 'annually' | null;
  max_consumptions: number;
  max_overages: number;
  reset_consumption: boolean;
} | {
  license_type: 'time-limited'
}) & ({
  enable_maintenance_period: false;
} | {
  enable_maintenance_period: true;
  maintenance_duration: string;
  maintenance_period?: string | null;
});

enum LicenseTypes {
  perpetual = 'perpetual',
  time_limited = 'time-limited',
  consumption = 'consumption',
  subscription = 'subscription',
};

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "BundleOrderResponse",
  "type": "object",
  "properties": {
    "order_id": { "type": "string" },
    "order_items": {
      "type": "array",
      "prefixItems": [
        { "$ref": "#/$defs/OrderItem" }
      ],
      "minItems": 1,
      "maxItems": 1
    },
    "new_passwords": {
      "type": "array",
      "items": { "$ref": "#/$defs/NewPassword" }
    }
  },
  "required": [
    "order_id",
    "order_items",
    "new_passwords"
  ],
  "additionalProperties": false,
  "$defs": {
    "OrderItem": {
      "type": "object",
      "properties": {
        "id": { "type": "number" },
        "product_id": { "type": "number" },
        "Licenses": {
          "type": "array",
          "items": { "$ref": "#/$defs/License" }
        }
      },
      "required": [
        "id",
        "product_id",
        "Licenses"
      ],
      "additionalProperties": false
    },
    "NewPassword": {
      "type": "object",
      "properties": {
        "email": { "type": "string" },
        "password": { "type": "string" }
      },
      "required": [
        "email",
        "password"
      ],
      "additionalProperties": false
    },
    "License": {
      "oneOf": [
        { "$ref": "#/$defs/BundleLicense" },
        { "$ref": "#/$defs/SubLicense" }
      ]
    },
    "BundleLicense": {
      "allOf": [
        { "$ref": "#/$defs/LicenseCommon" },
        {
          "type": "object",
          "properties": {
            "order_id": { "type": "number" },
            "note": { "type": "string" },
            "is_bundle": { "const": true },
            "time_activated": { "type": "number" }
          },
          "required": [
            "order_id",
            "is_bundle"
          ],
          "additionalProperties": false
        },
        {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "license_key": { "type": "string" }
              },
              "required": [
                "license_key"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "users": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "email": { "type": "string" },
                      "first_name": { "type": "string" },
                      "last_name": { "type": "string" },
                      "phone_number": { "type": "string" },
                      "is_manager": { "type": "boolean" }
                    },
                    "required": [
                      "email",
                      "is_manager"
                    ],
                    "additionalProperties": false
                  }
                },
                "max_license_users": { "type": "number" }
              },
              "required": [
                "users",
                "max_license_users"
              ],
              "additionalProperties": false
            }
          ]
        }
      ]
    },
    "SubLicense": {
      "allOf": [
        { "$ref": "#/$defs/LicenseCommon" },
        {
          "type": "object",
          "properties": {
            "order_id": { "type": "number" },
            "note": { "type": "string" },
            "bundle_license_id": { "type": "number" },
            "LicenseCustomFields": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "product_custom_field_id": { "type": "number" },
                  "value": { "type": "string" }
                },
                "required": [
                  "product_custom_field_id"
                ],
                "additionalProperties": false
              }
            },
            "LicenseProductFeatures": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": { "type": "number" },
                  "allow_negative_consumptions": { "type": "boolean" },
                  "allow_overages": { "type": "boolean" },
                  "allow_unlimited_consumptions": { "type": "boolean" },
                  "consumption_period": { "type": "string", "enum": ["daily","weekly","monthly","annually"] },
                  "expiry_date": { "type": ["string", "null"] },
                  "floating_timeout": { "type": "number" },
                  "floating_users": { "type": "number" },
                  "is_floating_cloud": { "type": "boolean" },
                  "is_floating": { "type": "boolean" },
                  "max_consumption": { "type": "number" },
                  "max_overages": { "type": "number" },
                  "metadata": {
                    "type": "object",
                    "additionalProperties": true
                  },
                  "name": { "type": "string" },
                  "product_feature_id": { "type": "number" },
                  "reset_consumption": { "type": "boolean" }
                },
                "required": [
                  "id",
                  "allow_negative_consumptions",
                  "allow_overages",
                  "allow_unlimited_consumptions",
                  "floating_timeout",
                  "max_consumption",
                  "max_overages",
                  "metadata",
                  "product_feature_id",
                  "reset_consumption"
                ],
                "additionalProperties": false
              }
            }
          },
          "required": [
            "order_id",
            "bundle_license_id",
            "LicenseCustomFields",
            "LicenseProductFeatures"
          ],
          "additionalProperties": false
        }
      ]
    },
    "LicenseCommon": {
      "allOf": [
        {
          "type": "object",
          "properties": {
            "id": { "type": "number" },
            "active": { "type": "boolean" },
            "allow_unlimited_activations": { "type": "boolean" },
            "can_borrow": { "type": "boolean" },
            "created_at": { "type": "number" },
            "enabled": { "type": "boolean" },
            "floating_timeout": { "type": "number" },
            "floating_users": { "type": "number" },
            "is_air_gapped": { "type": "boolean" },
            "is_floating_cloud": { "type": "boolean" },
            "is_floating": { "type": "boolean" },
            "is_hardware_key_auth": { "type": "boolean" },
            "is_trial": { "type": "boolean" },
            "license_template_id": { "type": ["number", "null"] },
            "max_activations": { "type": "number" },
            "max_borrow_time": { "type": "number" },
            "max_transfers": { "type": "number" },
            "metadata": {
              "type": "object",
              "additionalProperties": true
            },
            "prevent_vm": { "type": "boolean" },
            "product_id": { "type": "number" },
            "start_date": { "type": ["string", "null"] },
            "subscription_id": { "type": "string" },
            "trial_days": { "type": "number" },
            "updated_at": { "type": "number" },
            "valid_duration": { "type": ["string", "null"] },
            "validity_period": { "type": "string" }
          },
          "required": [
            "id",
            "active",
            "allow_unlimited_activations",
            "can_borrow",
            "created_at",
            "enabled",
            "floating_timeout",
            "floating_users",
            "is_air_gapped",
            "is_floating_cloud",
            "is_floating",
            "is_hardware_key_auth",
            "is_trial",
            "max_activations",
            "max_borrow_time",
            "max_transfers",
            "metadata",
            "prevent_vm",
            "product_id",
            "start_date",
            "subscription_id",
            "trial_days",
            "updated_at",
            "valid_duration"
          ],
          "additionalProperties": false
        },
        {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "license_type": { "const": "perpetual" }
              },
              "required": ["license_type"],
              "additionalProperties": true
            },
            {
              "type": "object",
              "properties": {
                "license_type": { "const": "subscription" },
                "allow_grace_period": { "type": "boolean" },
                "grace_period": { "type": "number" },
                "time_activated": { "type": "number" }
              },
              "required": [
                "license_type",
                "allow_grace_period",
                "grace_period",
                "time_activated"
              ],
              "additionalProperties": true
            },
            {
              "type": "object",
              "properties": {
                "license_type": { "const": "consumption" },
                "allow_negative_consumptions": { "type": "boolean" },
                "allow_overages": { "type": "boolean" },
                "allow_unlimited_consumptions": { "type": "boolean" },
                "consumption_period": { "type": ["string", "null"], "enum": ["daily","weekly","monthly","annually",null] },
                "max_consumptions": { "type": "number" },
                "max_overages": { "type": "number" },
                "reset_consumption": { "type": "boolean" }
              },
              "required": [
                "license_type",
                "allow_negative_consumptions",
                "allow_overages",
                "allow_unlimited_consumptions",
                "consumption_period",
                "max_consumptions",
                "max_overages",
                "reset_consumption"
              ],
              "additionalProperties": true
            },
            {
              "type": "object",
              "properties": {
                "license_type": { "const": "time-limited" }
              },
              "required": ["license_type"],
              "additionalProperties": true
            }
          ]
        },
        {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "enable_maintenance_period": { "const": false }
              },
              "required": ["enable_maintenance_period"],
              "additionalProperties": true
            },
            {
              "type": "object",
              "properties": {
                "enable_maintenance_period": { "const": true },
                "maintenance_duration": { "type": "string" },
                "maintenance_period": { "type": ["string", "null"] }
              },
              "required": [
                "enable_maintenance_period",
                "maintenance_duration"
              ],
              "additionalProperties": true
            }
          ]
        }
      ]
    }
  }
}

Example response

{
    "order_id": "1742897553827009",
    "order_items": [
        {
            "id": "1742897554021019",
            "product_id": 4,
            "Licenses": [
                {
                    "id": "1742897554024029",
                    "product_id": 4,
                    "active": false,
                    "enabled": true,
                    "created_at": 1742897554029,
                    "updated_at": 1742897554029,
                    "license_type": "perpetual",
                    "max_activations": 1,
                    "allow_unlimited_activations": false,
                    "valid_duration": null,
                    "floating_timeout": 120,
                    "max_transfers": 0,
                    "can_borrow": false,
                    "max_borrow_time": 0,
                    "start_date": null,
                    "is_air_gapped": false,
                    "license_template_id": null,
                    "validity_period": null,
                    "subscription_id": "",
                    "enable_maintenance_period": false,
                    "is_floating_cloud": false,
                    "is_floating": false,
                    "floating_users": 1,
                    "is_trial": false,
                    "trial_days": 15,
                    "prevent_vm": false,
                    "metadata": {},
                    "is_hardware_key_auth": false,
                    "license_key": "B32M-AXCN-GPEY-CELK",
                    "order_id": "1742897553827009",
                    "is_bundle": true
                },
                {
                    "id": "1742897554109039",
                    "product_id": 1,
                    "active": false,
                    "enabled": true,
                    "created_at": 1742897554112,
                    "updated_at": 1742897554112,
                    "license_type": "perpetual",
                    "max_activations": 1,
                    "allow_unlimited_activations": false,
                    "valid_duration": null,
                    "floating_timeout": 120,
                    "max_transfers": 0,
                    "can_borrow": false,
                    "max_borrow_time": 0,
                    "start_date": null,
                    "is_air_gapped": false,
                    "license_template_id": null,
                    "validity_period": null,
                    "subscription_id": "",
                    "enable_maintenance_period": false,
                    "is_floating_cloud": false,
                    "is_floating": false,
                    "floating_users": 0,
                    "is_trial": false,
                    "trial_days": 1,
                    "prevent_vm": false,
                    "metadata": {},
                    "is_hardware_key_auth": false,
                    "bundle_license_id": "1742897554024029",
                    "order_id": "1742897553827009",
                    "LicenseProductFeatures": [
                        {
                            "id": "1742897554115049",
                            "product_feature_id": 5,
                            "max_consumption": 12,
                            "expiry_date": null,
                            "metadata": {},
                            "is_floating": false,
                            "is_floating_cloud": false,
                            "floating_timeout": 120,
                            "floating_users": 1
                        }
                    ],
                    "LicenseCustomFields": []
                },
                {
                    "id": "1742897554118059",
                    "product_id": 1,
                    "active": false,
                    "enabled": true,
                    "created_at": 1742897554120,
                    "updated_at": 1742897554120,
                    "license_type": "perpetual",
                    "max_activations": 1,
                    "allow_unlimited_activations": false,
                    "valid_duration": null,
                    "floating_timeout": 120,
                    "max_transfers": 0,
                    "can_borrow": false,
                    "max_borrow_time": 0,
                    "start_date": null,
                    "is_air_gapped": false,
                    "license_template_id": null,
                    "validity_period": null,
                    "subscription_id": "",
                    "enable_maintenance_period": false,
                    "is_floating_cloud": false,
                    "is_floating": false,
                    "floating_users": 0,
                    "is_trial": false,
                    "trial_days": 1,
                    "prevent_vm": false,
                    "metadata": {},
                    "is_hardware_key_auth": false,
                    "bundle_license_id": "1742897554024029",
                    "order_id": "1742897553827009",
                    "LicenseProductFeatures": [
                        {
                            "id": "1742897554207069",
                            "product_feature_id": 5,
                            "max_consumption": 12,
                            "expiry_date": null,
                            "metadata": {},
                            "is_floating": false,
                            "is_floating_cloud": false,
                            "floating_timeout": 120,
                            "floating_users": 1
                        }
                    ],
                    "LicenseCustomFields": []
                }
            ]
        }
    ],
    "new_passwords": [
        []
    ]
}

Licenses

Each entry in the items array specifies a product code and a list of licenses being associated to that product. The following examples show a minimal order request payload for key-based and user-based licenses.

Key-based license order

{
    "id": "id_1546606209296",
    "items": [
        {
            "product_code": "TT",
            "licenses": [
                {
                    "key": "123-123-123-123-123"
                }
            ]
        }
    ]
}

User-based license order

{
    "id": "id_1546606209296",
    "items": [
        {
            "product_code": "TT",
            "licenses": [
                {
                    "users": [{
                        "email": "[email protected]",
                        "is_manager": false
                    }]
                }
            ]
        }
    ]
}

License Policy

For each license you can specify a policy_code within the license object which will assign properties to a license based on the specified License Policy. (For more details on these properties, see the next section). If no policy code is specified, the default license policy defined for the Product will be used.

You can also explicitly specify license properties which will override the License Policy values. For example:

{
    "id": "id_1546606209296",
    "items": [
        {
            "product_code": "TT",
            "licenses": [
                {
                    "key": "123-123-123-123-123",
                    "policy_code": "policy_A",
                    "max_activations": 10
                }
            ]
        }
    ]
}

In the above example, all License properties for the created license will be taken from the License Policy "policy_A", with the exception of the max_activations property which was explicitly specified in the order request payload.

Authorization methods: Key-based vs. User-based licenses

Each product you create in the system allows for one of two possible license authorization methods:

Key-based: clients interacting with the license are required to provide a license key in their request
User-based: clients interacting with the license are required to provide user credentials in their request

When sending an order creation request, the authorization method of licenses in the request are determined by each license's product.

When creating key-based licenses in an order, you can provide a license key in the key property of the license. This is optional, and if omitted our system will generate a unique license key which will be returned to you in the order creation response object.
When creating user-based licenses in an order, you must specify the users (1 or more) attached to that license by specifying them in a list in the users property of the license.

Additional license properties

max_activations - maximum number of time this license can be activated. If not set, product max activations is being used if defined for the product, if not - default value of 1 activation is being used.
license_type - type of license
- value can be either time-limited, perpetual consumption or subscription. If it is a time limited license, valid_duration should also be set for the license. If it is perpetual license then valid duration does not apply and if consumption, max_consumptions is being used and should be set in order, if not, product max consumptions is being used.
- For subscription licenses, LicenseSpring requires an integration to an external source of truth (like a recurring billing system). LicenseSpring updates the status of the license according to the status of the subscription, which is handled by a 3rd party. Without this integration, subscription licenses remain valid until otherwise specified
max_consumptions - used in pair with consumption license_type - defines how many times product can be used within the license.
valid_duration - defines how long license should be valid - value examples: 1y (one year) or 2m (2 months) or 3d (3 days) or 4h (4 hours).
enable_maintenance_duration - whether license should consider maintenance duration, used in pair with maintenance_duration.
start_date - start date of license "2024-03-12"
maintenance_duration - duration of license maintenance period - value examples: 1y (one year) or 2m (2 months) or 3d (3 days).
validity_period - final end date and time license is valid.
product_features - array of additional product features
- shorter version with product feature code only: ["feature1", "feature2"]
- longer version as an object with the code property and any additional property as an overrided value, eg: [{ "code": "feature_code", "max_consumption": 33, "expiry_date": "2027-05-23" }]. For a full definition of this object see ProductFeature in the Request definition above
is_trial - boolean, defaults to False - whether this is a trial license or not.
prevent_vm - boolean, defaults to False - whether license should be allowed on virtual machines.
max_transfers - integer, defaults to 0 (Device transfer not allowed) - limit of license transfers between different devices.

For user-based licenses, instead of a license key, user is assigned as an object:

email - required, email of the license user
is_manager - optional (default false), if this user is license manager for all licenses in this order

Only for consumption licenses:

allow_overages - boolean, defaults to False - whether license should allow overage license usage regardless the consumption, value example: true or false
max_overages - number, maximum overage of consumption over the max_consumption.
reset_consumption - boolean, defaults to False, whether license consumption my be reset, value example: true or false
consumption_period - period over which licenses are reset - weekly, monthly or annually

Bundle Product Orders

LicenseSpring allows for products to be bundled, and the two types of products discussed in this article respective to bundling are:

Non-bundle products (default) - these are singular products where each license is attached to one product. Clients interacting with these licenses use the following endpoints on the License API:
Bundle products - these are products that contain multiple products within. The system creates a license for both the bundle itself and the products contained in the bundle. Activating/deactivating the top-level bundle license also activates/deactivates the licenses included within the bundle. Clients interacting with these licenses use the following endpoints on the License API:

A Bundle Order contains multiple products linked to a single Bundle Product. To create a Bundle Order, you have to set the is_bundle property, and the products within the bundle are explicitly specified within each License object, as in the following examples:

Bundle of key-based licenses

{
    "id": "2cdf5739334b4688b04c4bbfb3da89618",
    "is_bundle": true,
    "append": false,
    "customer": null,
    "items": [
        {
            "product_code": "drama", // bundle product code
            "key": "GP14Q-QA4Z-M6SK-CXBU",
            "users": [],
            "licenses": [
                {
                    "policy_code": "dftlp", // the deprecated name for this attribute is "license_template_code"
                    "product_code": "p"
                },
                {
                    "policy_code": "dftlp",
                    "product_code": "p34"
                }
            ]
        }
    ],
    "reference": ""
}

Bundle of user-based licenses

{
    "id": "2cdf57393364b4688b304c4bbfb9da89618",
    "is_bundle": true,
    "append": false,
    "customer": null,
    "items": [
        {
            "product_code": "d1", // bundle product code
            "users": [
                {
                    "email": "[email protected]",
                    "is_manager": false
                }
            ],
            "licenses": [
                {
                    "policy_code": "dftlp",
                    "product_code": "p2"
                },
                {
                    "policy_code": "dftlp",
                    "product_code": "12"
                }
            ]
        }
    ],
    "reference": ""
}

Notes

For Bundle Orders, the policy_code property is mandatory.

For Bundle Orders, the policy_code property has an alternate name: license_template_code. Both function identically, though the license_template_code name is considered deprecated on the API.

PreviousOrder NextRetrieve Order

Last updated 18 days ago

Was this helpful?

Good afternoon

hashtagParameters

hashtagNotes

hashtagRequest

hashtagNon-Bundle Order Request

hashtagTypescript

hashtagJSON Schema

hashtagExample: Key-based license

hashtagExample: User-based license

hashtagBundle Order Request

hashtagTypescript

hashtagJSON Schema

hashtagExample: Key-based bundle

hashtagExample: User-based bundle

hashtagNotes overview

hashtagResponse

hashtagNon-Bundle Order Response

hashtagTypeScript

hashtagJson Schema

hashtagExample response

hashtagBundle Order Response

hashtagTypeScript

hashtagJSON Schema

hashtagExample response

hashtagLicenses

hashtagKey-based license order

hashtagUser-based license order

hashtagLicense Policy

hashtagAuthorization methods: Key-based vs. User-based licenses

hashtagAdditional license properties

hashtagBundle Product Orders

hashtagBundle of key-based licenses

hashtagBundle of user-based licenses

hashtagNotes

Parameters

Notes

Request

Non-Bundle Order Request

Typescript

JSON Schema

Example: Key-based license

Example: User-based license

Bundle Order Request

Typescript

JSON Schema

Example: Key-based bundle

Example: User-based bundle

Notes overview

Response

Non-Bundle Order Response

TypeScript

Json Schema

Example response

Bundle Order Response

TypeScript

JSON Schema

Example response

Licenses

Key-based license order

User-based license order

License Policy

Authorization methods: Key-based vs. User-based licenses

Additional license properties

Bundle Product Orders

Bundle of key-based licenses

Bundle of user-based licenses

Notes