FastSpring Contextual Store

this guide will go over some of the most common scenarios for which fastspring will integrate with licensespring this guide will work both for products and subscriptions that are configured at key based or user based on licensespring there are additional sections at the bottom of this guide for specific use cases for subscriptions, it's the same integration as for products below, with a few small precisions added at the bottom of this guide follow these steps to configure licensing for products that you sell in fastspring activate fastspring integration in licensespring setup product attributes setup license generation setup webhook integration 1\ activate fastspring integration in licensespring go to settings > integrations > fastspring and click activate select the management api key and license api key (also known as uuid , this is the key that will later be used in webhook integration setup) 2 setup product attributes go to fastspring "products" section open your product in the options > "custom attributes" dialog of your product uuid required , can be found in your licensespring account under settings > keys > license api keys product short code required , with the code you configured licensespring product with max activations optional, int if this field is not included, the default from the product configuration in licensespring will be used floating cloud optional, int if this value is set licenses from this product will be created as floating cloud this value also sets the total number of machines / users that can concurrently use a floating cloud license ( max simultaneous license users value in licensespring configuration ) needs to be less than or equal to max activations attribute value floating users from quantity optional, bool quantity is used to determine max simultaneous license users instead of max activations on single floating cloud licenses see docid\ oa87a qpwfbvl73ntklxf license type optional, string if this field is not included, the default license type from the product configuration in licensespring is used ( perpetual , time limited , subscription , consumption ) for subscription products license type is always subscription valid duration optional, string if this field is not included, the default valid duration from the product configuration in licensespring is used the format for this is n\[d/w/m/y] where n is number and option between d,w,m,y is possible (day, week, month, year) not applicable for subscription licenses please see the section about subscriptions for instructions on configuring a subscription maintenance duration optional, string behaves same as the valid duration field max consumptions optional, int, will be applied on non subscriptions only, when license type attribute is set to consumption enable maintenance duration optional, turns on maintenance capability if not defined, default from ls is used is license manager optional, sets customer as a license manager useful on license key or user based products where the customer is not set as a license manager by default assign customer as user optional, bool, customer will be automatically assigned to the license as a license user can be added only for products with user authorization method grace period optional, int, sets grace period ( in hours ) for the subscription license user max activations optional, int to change the max activations for a customer assigned to a license as a license user , use this attribute along with the assign customer as user attribute if this field is not included, the default is 1 can be added only for products that use the user authorization method ignore product in licensespring optional, bool when set to true , incoming webhooks for the specified product will be ignored, and a 200 status code will be returned to fastspring as a response disable licenses only on full refund optional, bool when set to true , only licenses that are fully refunded will be disabled licenses will remain enabled in the case of partial refunds is trial optional, bool when set to true , licenses are created as trial licenses applicable only for non subscription licenses to customize the trial days duration, override the trial days value on the corresponding license policy dynamic max activations optional, bool when set to true , the max activations value is calculated dynamically as the product quantity multiplied by the user max activations defined in the selected license policy (the default license policy is used if none is specified) this attribute can only be used with user based products, requires the assign customer as user attribute, and applies only when the license type is set to single license license policy for every product in the licensespring platform you can define one or many license policies which act as a template when creating licenses license policy can be added to the fastspring products as a custom attribute key license policy with value of some license policy code when order is being created via fastspring, our integration will take all the fields, product features and custom fields from included license policy and create the license based on those license policy if license policy is defined, then instead of using separate features, fastspring looks at the license policy code, and sets features on a license based on the features that are added to the license policy in licensespring the license policy attribute and the features, as described here, can't both be used inside the same product configuration for example, if you decide to use the license policy attribute then you can't be using features, and vice versa, if you decide to use features then you need to remove the license policy attribute custom fields https //docs licensespring com/docs/custom fields can be also customized using fastspring after custom fields have been created on the licensespring product with some default value we can customize them using custom attributes if we have for example some custom field named serial with default value 111 and we want to create a custom value for this field on some license we would add this custom attribute key to the fastspring product in format custom field {valuename} ex key custom field serial and add some value to it note that for every custom field which we would want to customize we need to add separate custom attribute in the above mentioned format custom field {valuename} please note that you need to do this for every product you plan to process through licensespring if the number of fields isn't enough, save all the attributes that you can and after that reopen the window, then more fields should appear 3\ set up license generation if your product is key based, you need to add a license generation fulfillment to the fastspring product this will generate a license key during order create process this is not needed for the user based products in the "products section, open your product in the "fulfillment" section, click "add fulfillment" select "generate a license" as action and "remote server request" as generator press next to come to configuration set the following settings in the dialog url https //integrations licensespring com/api/generate license https //integrations licensespring com/api/generate license method http post post encoding utf 8 output format single line license (quantity based) customizing the license character set to customize the set of characters used when generating licenses, follow these steps navigate to the product where your license fulfillment is configured under the fulfillments section, locate the fulfillment configuration you previously set up and click edit on the remote license configuration page, click on the parameters tab add a new parameter with the following details name alphabet value the set of characters you want to use for license generation (e g , abcdefg1234567) once this parameter is added, the license generator will use your specified character set for all licenses issued through this fulfillment examples are provided in the two images below 4 set up webhook integration these are events we identified as important and currently support in your fastspring store, go to "integrations" and then "webhooks" first, add a new webhook section with the "add webhook" button in upper right the title can be anything you like, but we recommend something relating to licensespring you must enable "enable webhook expansion" in the new webhook section, add a new webhook by pressing "add webhook url" and fill it out with url https //integrations licensespring com/api/fastspring hmac sha256 secret enter the "shared key" from your licensespring account you can find this under "account settings > settings > keys" `in the list of events below, the following events order completed required for all license types return created licenses will be disabled if the order is refunded for subscriptions, please also send the following webhooks subscription deactivated subscription canceled subscription uncanceled subscription updated subscription payment reminder subscription payment overdue subscription charge completed subscription charge failed subscription paused subscription resumed information on fastspring's webooks can be found https //fastspring com/docs/webhooks/ only the order completed event is needed if you are not using subscriptions all webhook events from fastspring are stored as "license history" and available in the platform as a "history log" for each license this history log can be found under the "usage report" for a license webhook events this section describes what the expected behavior is for the webhooks order completed this is the main webhook, and is triggered after clearing payment and all fulfilment actions in licensespring creates an order and licenses subscriptions a subscription type license is automatically put into active state and the validity period will match the billing period set on fastspring the other events pertain to subscription handling subscription deactivated is triggered after cancellation at the end of the remaining period, or when "deactivate now" option is used in fastspring in licensespring this event will deactivate all associated licenses and devices immediately subscription canceled is triggered when the subscription is cancelled will be deactivated on next payment period in licensespring the event is logged to the license history, but has no effect on the status of the license it is expected that subscription deactivated will trigger properly subscription uncanceled is triggered when cancelling a subscription is reverted in licensespring the event is logged to the license history, but has no effect on the status of the license subscription updated is triggered after a manual/api update of subscription in licensespring updates the license based on active and next parameters others ignored for single licenses updates change in quantity (max activations) and ads end date to a license note subscription payment reminder notification in licensespring the event is logged to the license history, but has no effect on the status of the license subscription payment overdue notification in licensespring the event is logged to the license history, but has no effect on the status of the license subscription charge completed is triggered when subscription is renewed (it is not triggered for a new subscription) in licensespring updates "expiration date" (validity period) to match next value of webhook payload subscription charge failed notification in licensespring the event is logged to the license history, but has no effect on the status of the license subscription paused is triggered after the subscription is paused at the end of the remaining period in licensespring this event will disable all associated licenses immediately subscription resumed is triggered when a subscription is resumed (the subscription had to be paused beforehand) in licensespring this event will enable again all associated licenses return created is triggered when an order is refunded in licensespring this event will disable all associated licenses more information on specific scenarios user based licenses the customer email address is assigned as a "license manager" role and he is supposed to assign licenses in the https //users licensespring com/ , or email(s) of end users should be provided in the webhook request subscription trials subscriptions can be set with some free trial days when editing subscription price when order is created using subscription with trial days, licensespring integration will recognize this and create trial license using sent trial days expiration date will be set using fastspring event data on first subscription charge completed event this license will be changed from trial to full license subscriptions configuration notes instead of going to the products tab, you go to the subscriptions tab, and after that, the setup is the same as it is for products ( choose a price and set the necessary custom attributes ) single license for multiple quantities or multiple users in your store, user can select different quantities for a product default behaviour is that multiple quantities will result in multiple licenses (both user and license key based!) if instead, when user selects >1 quantity you want to make a single license that can be activated multiple times (for license key based) or a single license that supports multiple users (for user based licenses), you need to for license key based, in license fulfilment settings change on product fulfilment add an additional parameter single license and set its value to true , here are the steps in "catalog" select the desired product on the product page scroll down to the fulfilment section click on the "edit" button on the desired fulfilment on the edit page click on the "parameters" tab add the single license parameter and set its value to true additionally add single license custom attribute to the product and set it's value to true to ensure subscription updates will work as expected in "catalog" select the desired product in the upper right corner in the dropdown select the "custom attributes" a dd single license custom attribute and set it's value to true (image below) click the "save" button on the custom attribute pop up window max simultaneous license users from quantity on a single license in case of single floating cloud license, quantity can be used to determine max simultaneous license users instead of max activations for license key based or number of users for user based products to enable this, please use this following combination of custom attributes on the product floating users from quantity true floating cloud 1 max activations optional, int if this field is not included, the default from the product configuration in licensespring will be used also, the products fulfillment needs to be set as described in the single license section shown above issue different license types for the same product in licensespring, a product can issue perpetual, time limited, consumption, and subscription licenses fastspring only allows their products to be configured as either perpetual or subscriptions to create a time limited license, for instance, you need to add following custom attribute on product license type = time limited just like in subscriptions example, you can use the same product configured in licensespring for many different products in fastspring features you can add features to both products and to subscriptions features need to be first set up as a normal product in fastspring the name does not matter however, the custom attribute is what is used to recognize which feature to add to a license you therefore need to set a custom attribute with the following feature code = my feature (where my feature is for example code of the feature on a product) no additional configuration is required (such as fulfilment) the product path and feature code need to be the same so our licensespring <> fastspring integration can properly update the features when subscription is updated add the feature code from licensespring as a custom attribute in fastspring on the main product, add the feature as a "related offer" select add product options inside the add new selector add related offers to the main product add features to the main product in the main popup product bundles product bundle is a unique type of product in licensespring that requires specific configuration this section outlines all the currently available product attributes for product bundles and instructions on how to use them only one product bundle can be processed per order multiple quantities of the same product bundle are supported ; however, including two or more different product bundles in the same order on fastspring is not supported how to set up product bundles in licensespring? go to the products section in licensespring platform click the add new bundle button insert the desired bundle name and bundle code , choose which authorization method to use , and finally, select all the products that you want inside the bundle after the bundle is created, it should look something like the following picture take the bundle code value and use it as the product short code in the fastspring configuration (look at the list below to see all the available product attributes for bundle products ) all other setup steps are the same as they are for basic products the only difference is in the supported product attributes if a product bundle contains, for example, three products, then four licenses will be created in licensespring one license will be for the bundle itself, which can be used for all products within the bundle the remaining three licenses will be created for each individual product in the bundle the value of these individual licenses is determined by the default license policy of each product features (in fastspring) are not supported each license will include the features defined in the default license policy of the product for which the license was created product attributes go to fastspring "products" section open your product in the options > "custom attributes" dialog of your product uuid required , can be found in your licensespring account under settings > keys > license api keys is product bundle required , boolean, has to be set to true product short code required , with the code you configured licensespring product bundle with max activations optional, int if this field is not included, the value from the default license policy on the product in licensespring will be used floating cloud optional, int if this value is set licenses from this product bundle will be created as floating cloud this value also sets the total number of machines / users that can concurrently use a floating cloud license ( max simultaneous license users value in licensespring configuration ) needs to be less than or equal to max activations attribute value floating users from quantity optional, bool quantity is used to determine max simultaneous license users instead of max activations on single floating cloud licenses see docid\ oa87a qpwfbvl73ntklxf license type optional, string if this field is not included, the default license type of each product inside the bundle configuration in licensespring is used ( perpetual , time limited , subscription , consumption ) for subscription products license type is always subscription valid duration optional, string if this field is not included, the default valid duration of each product inside the bundle configuration in licensespring is used the format for this is n\[d/w/m/y] where n is number and option between d,w,m,y is possible (day, week, month, year) applicable for time limited licenses only maintenance duration optional, string behaves same as the valid duration field max consumptions optional, int, will be applied on non subscriptions only, when license type attribute is set to consumption enable maintenance duration optional, turns on maintenance capability if not defined, default from ls is used is license manager optional, sets customer as a license manager useful on license key or user based products where the customer is not set as a license manager by default assign customer as user optional, bool, customer will be automatically assigned to the license as a license user can be added only for products with user authorization method grace period optional, int, sets grace period ( in hours ) for the subscription licenses user max activations optional, int to change the max activations for a customer assigned to a license as a license user , use this attribute along with the assign customer as user attribute if this field is not included, the default is 1 can be added only for products that use the user authorization method ignore product in licensespring optional, bool when set to true , incoming webhooks for the specified product will be ignored, and a 200 status code will be returned to fastspring as a response disable licenses only on full refund optional, bool when set to true , only licenses that are fully refunded will be disabled licenses will remain enabled in the case of partial refunds product bundle license policies you can define a specific license policy for each individual product within a bundle go to fastspring "products" section open your product in the options > "custom attributes" dialog of your product to override the default license policy for a product in the bundle use the product short code as the attribute key use the license policy short code as the attribute value example if you have a bundle containing 3 products and want to override the license policy for the second product assume the second product’s short code is short code prod 2 assume the license policy you want to apply is license policy 2 then, in the custom attributes key short code prod 2 value license policy 2 fastspring requires that the key attribute in custom attributes is at least 3 characters long if your product short code is shorter than that, you can add a prefix to meet this requirement use the following format product in bundle {product short code} example for a product short code of ab , the required custom attribute key is product in bundle ab if the license policy short code is lp2 , the resulting key–value pair is key product in bundle ab value lp2