Create Order

8min
If the product uses key-based licensing, before storing an order you need to generate a license key using /api/v1/orders/generate_license/.
POST
Request Params
Body Parameters
id
required
String
Order ID. This is a unique identifier for an order within a company
is_bundle
optional
Boolean
If true, defines the order as a bundle order. Defaults to false. For more details on bundle orders, see the Bundle section below
append
optional
Boolean
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
optional
Boolean
Whether or not this is a test order
created
optional
String
Date and time order is created
order_type
optional
String
Current possible value is: normal
language
optional
String
Order language, value should be language short code
campaign_params
optional
String
e.g. Google campaign params for the order
download_id
optional
String
Custom order download ID
prevent_vm
optional
String
If set to true, license activation won't be possible on a Virtual Machine
metadata
optional
String
Custom metadata, in the format of a serialized JSON object
items
required
Object
Product licenses in this order
customer
optional
Object
Customer data for the order
JSON
{
    "id": "id_1546606209296",
    "append": true,
    "is_test": false,
    "created": "2017-03-15 22:13:01",
    "order_type": "normal",
    "language": "en",
    "campaign_params": "cpg=web,src=google.com",
    "download_id": "someID33",
    "customer": {
        "email": "[email protected]",
        "first_name": "John",
        "last_name": "Smith",
        "company_name": "Acme Inc.",
        "phone": "+1656123123123",
        "reference": "ref_usr_321"
    },
    "items": [{
        "product_code": "TT",
        "licenses": [{
            "key": "123-123-123-123-123",
            "user": {
            	"email": "[email protected]"
            },
            "max_activations": 3,
            "license_type": "consumption",
            "max_consumptions": 10000,
            "valid_duration": "1y",
            "enable_maintenance_period": true,
            "maintenance_duration": "3d",
            "validity_period": "2019-10-15 00:00:00",
            "product_features": ["my_code", {"code": "my_feature", "max_consumption":33}],
            "is_trial": false
        }]
    }],
    "prevent_vm": false
}
{
    "id": "id_1546606209296",
    "append": true,
    "is_test": false,
    "created": "2017-03-15 22:13:01",
    "order_type": "normal",
    "language": "en",
    "campaign_params": "cpg=web,src=google.com",
    "download_id": "someID33",
    "customer": {
        "email": "test@customer.com",
        "first_name": "John",
        "last_name": "Smith",
        "company_name": "Acme Inc.",
        "phone": "+1656123123123",
        "reference": "ref_usr_321"
    },
    "items": [{
        "product_code": "TT",
        "licenses": [{
            "key": "123-123-123-123-123",
            "user": {
            	"email": "end-user@gmail.com"
            },
            "max_activations": 3,
            "license_type": "consumption",
            "max_consumptions": 10000,
            "valid_duration": "1y",
            "enable_maintenance_period": true,
            "maintenance_duration": "3d",
            "validity_period": "2019-10-15 00:00:00",
            "product_features": ["my_code", {"code": "my_feature", "max_consumption":33}],
            "is_trial": false
        }]
    }],
    "prevent_vm": false
}
Responses
200
{
    "id": 1608537775387429,
    "order_items": [
        {
            "id": 1608537775387449,
            "product_id": 1584723961091238,
            "licenses": [
                {
                    "id": 1608537775387439,
                    "customer": {
                        "id": 620,
                        "total_orders": 42,
                        "total_licenses": 97,
                        "labels": [
                            {
                                "id": 3,
                                "label_id": 8,
                                "label": "Customer",
                                "color": "#ff9f43"
                            },
                            {
                                "id": 53,
                                "label_id": 34,
                                "label": "Loyal",
                                "color": "#3a0cd4"
                            }
                        ],
                        "email": "[email protected]",
                        "first_name": "",
                        "last_name": "",
                        "company_name": "",
                        "phone": "",
                        "reference": "",
                        "address": "",
                        "postcode": "",
                        "city": "",
                        "country": "",
                        "state": "",
                        "clabels_all": "customerloyal",
                        "cognito_user_pool_id": "",
                        "metadata": {},
                        "company": 277,
                        "license_user": null,
                        "clabels": [
                            8,
                            34
                        ]
                    },
                    "product_features": [],
                    "product_custom_fields": [],
                    "license_user": null,
                    "license_users": [],
                    "order_store_id": "179ebecf61de4bdc9ffc418dsadsd",
                    "active_up_to_date_devices": 0,
                    "product": {
                        "id": 1584723961091238,
                        "product_name": "wbhk"
                    },
                    "created_at": "2020-12-21T08:02:55Z",
                    "updated_at": "2020-12-21T08:02:55Z",
                    "license_key": "GB7L-5CWN-LVSK-QUWB",
                    "active": false,
                    "enabled": true,
                    "time_activated": null,
                    "time_disabled": null,
                    "max_activations": 1,
                    "times_activated": 0,
                    "valid_duration": null,
                    "validity_period": null,
                    "license_type": "perpetual",
                    "enable_maintenance_period": false,
                    "maintenance_duration": "1",
                    "maintenance_period": null,
                    "is_trial": false,
                    "max_consumptions": null,
                    "total_consumptions": 0,
                    "subscription_id": null,
                    "last_check": null,
                    "prevent_vm": false,
                    "allow_overages": false,
                    "max_overages": 0,
                    "reset_consumption": false,
                    "consumption_period": null,
                    "trial_days": 1,
                    "is_floating": false,
                    "is_floating_cloud": false,
                    "floating_users": 1,
                    "note": null,
                    "max_license_users": 1,
                    "order": 1608537775387429,
                    "order_item": 1608537775387449,
                    "disabled_user": null
                }
            ],
            "created_at": null,
            "updated_at": null,
            "order": 1608537775387429,
            "product": 1584723961091238
        }
    ],
    "customer": {
        "id": 620,
        "total_orders": 42,
        "total_licenses": 97,
        "labels": [
            {
                "id": 3,
                "label_id": 8,
                "label": "Customer",
                "color": "#ff9f43"
            },
            {
                "id": 53,
                "label_id": 34,
                "label": "Loyal",
                "color": "#3a0cd4"
            }
        ],
        "email": "[email protected]",
        "first_name": "",
        "last_name": "",
        "company_name": "",
        "phone": "",
        "reference": "",
        "address": "",
        "postcode": "",
        "city": "",
        "country": "",
        "state": "",
        "clabels_all": "customerloyal",
            "cognito_user_pool_id": "",
            "metadata": {},
        "company": 277,
        "license_user": null,
        "clabels": [
            8,
            34
        ]
    },
    "has_active_licenses": false,
    "created_at": "2020-12-21T08:02:55Z",
    "updated_at": "2020-12-21T08:02:55Z",
    "store_id": "179ebecf61de4bdc9ffc418dsadsd",
    "type": "normal",
    "customer_email": null,
    "is_test": false,
    "customer_reference": null,
    "is_trial": false,
    "download_id": null,
    "language": null,
    "campaign_params": null,
    "customer_first_name": null,
    "customer_last_name": null,
    "customer_company": null,
    "customer_phone": null,
    "metadata": {},
    "company": 277,
    "license_users": []
}
{
    "id": 1608537775387429,
    "order_items": [
        {
            "id": 1608537775387449,
            "product_id": 1584723961091238,
            "licenses": [
                {
                    "id": 1608537775387439,
                    "customer": {
                        "id": 620,
                        "total_orders": 42,
                        "total_licenses": 97,
                        "labels": [
                            {
                                "id": 3,
                                "label_id": 8,
                                "label": "Customer",
                                "color": "#ff9f43"
                            },
                            {
                                "id": 53,
                                "label_id": 34,
                                "label": "Loyal",
                                "color": "#3a0cd4"
                            }
                        ],
                        "email": "tc@tc.com",
                        "first_name": "",
                        "last_name": "",
                        "company_name": "",
                        "phone": "",
                        "reference": "",
                        "address": "",
                        "postcode": "",
                        "city": "",
                        "country": "",
                        "state": "",
                        "clabels_all": "customerloyal",
                        "cognito_user_pool_id": "",
                        "metadata": {},
                        "company": 277,
                        "license_user": null,
                        "clabels": [
                            8,
                            34
                        ]
                    },
                    "product_features": [],
                    "product_custom_fields": [],
                    "license_user": null,
                    "license_users": [],
                    "order_store_id": "179ebecf61de4bdc9ffc418dsadsd",
                    "active_up_to_date_devices": 0,
                    "product": {
                        "id": 1584723961091238,
                        "product_name": "wbhk"
                    },
                    "created_at": "2020-12-21T08:02:55Z",
                    "updated_at": "2020-12-21T08:02:55Z",
                    "license_key": "GB7L-5CWN-LVSK-QUWB",
                    "active": false,
                    "enabled": true,
                    "time_activated": null,
                    "time_disabled": null,
                    "max_activations": 1,
                    "times_activated": 0,
                    "valid_duration": null,
                    "validity_period": null,
                    "license_type": "perpetual",
                    "enable_maintenance_period": false,
                    "maintenance_duration": "1",
                    "maintenance_period": null,
                    "is_trial": false,
                    "max_consumptions": null,
                    "total_consumptions": 0,
                    "subscription_id": null,
                    "last_check": null,
                    "prevent_vm": false,
                    "allow_overages": false,
                    "max_overages": 0,
                    "reset_consumption": false,
                    "consumption_period": null,
                    "trial_days": 1,
                    "is_floating": false,
                    "is_floating_cloud": false,
                    "floating_users": 1,
                    "note": null,
                    "max_license_users": 1,
                    "order": 1608537775387429,
                    "order_item": 1608537775387449,
                    "disabled_user": null
                }
            ],
            "created_at": null,
            "updated_at": null,
            "order": 1608537775387429,
            "product": 1584723961091238
        }
    ],
    "customer": {
        "id": 620,
        "total_orders": 42,
        "total_licenses": 97,
        "labels": [
            {
                "id": 3,
                "label_id": 8,
                "label": "Customer",
                "color": "#ff9f43"
            },
            {
                "id": 53,
                "label_id": 34,
                "label": "Loyal",
                "color": "#3a0cd4"
            }
        ],
        "email": "tc@tc.com",
        "first_name": "",
        "last_name": "",
        "company_name": "",
        "phone": "",
        "reference": "",
        "address": "",
        "postcode": "",
        "city": "",
        "country": "",
        "state": "",
        "clabels_all": "customerloyal",
            "cognito_user_pool_id": "",
            "metadata": {},
        "company": 277,
        "license_user": null,
        "clabels": [
            8,
            34
        ]
    },
    "has_active_licenses": false,
    "created_at": "2020-12-21T08:02:55Z",
    "updated_at": "2020-12-21T08:02:55Z",
    "store_id": "179ebecf61de4bdc9ffc418dsadsd",
    "type": "normal",
    "customer_email": null,
    "is_test": false,
    "customer_reference": null,
    "is_trial": false,
    "download_id": null,
    "language": null,
    "campaign_params": null,
    "customer_first_name": null,
    "customer_last_name": null,
    "customer_company": null,
    "customer_phone": null,
    "metadata": {},
    "company": 277,
    "license_users": []
}
﻿
Metadata should be in literal string format: "metadata":"{ \"flower\": \"license\" }"
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
User-based license order
{
    "id": "id_1546606209296",
    "items": [
        {
            "product_code": "TT",
            "licenses": [
                {
                    "key": "123-123-123-123-123"
                }
            ]
        }
    ]
}
{
    "id": "id_1546606209296",
    "items": [
        {
            "product_code": "TT",
            "licenses": [
                {
                    "key": "123-123-123-123-123"
                }
            ]
        }
    ]
}
﻿
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:
JSON
{
    "id": "id_1546606209296",
    "items": [
        {
            "product_code": "TT",
            "licenses": [
                {
                    "key": "123-123-123-123-123",
                    "policy_code": "policy_A",
                    "max_activations": 10
                }
            ]
        }
    ]
}
{
    "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.
License properties
key - the license key.
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) or 5min (5 minutes).
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, suitable for consumption features: [{code: "feature_code", max_consumption:33}].
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 - week, month or year
Bundle Orders
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
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": ""
}
{
    "id": "2cdf57393364b4688b304c4bbfb9da89618",
    "is_bundle": true,
    "append": false,
    "customer": null,
    "items": [
        {
            "product_code": "d1", // bundle product code
            "users": [
                {
                    "email": "myuser@test.com",
                    "is_manager": false
                }
            ],
            "licenses": [
                {
                    "policy_code": "dftlp",
                    "product_code": "p2"
                },
                {
                    "policy_code": "dftlp",
                    "product_code": "12"
                }
            ]
        }
    ],
    "reference": ""
}
﻿
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
﻿
Updated 24 Jun 2024
Did this page help you?
Change Customer on Order
List License Policies
Docs powered by Archbee
TABLE OF CONTENTS