FastSpring Contextual Store

This guide will go over some of the most common scenarios for which FastSpring will integrate with LicenseSpring.

Follow these steps to configure licensing for products that you sell in FastSpring:

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

1. Go to FastSpring "Products" section

2. Open your product.

3. In the Options > "Custom attributes" dialog of your product, add attributes as needed:

• 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 Max simultaneous license users from quantity on a single license.

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

Custom fields

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.

Follow these steps to add the fulfillment:

1

1. In the "Products" section, open your product

2. In the "Fulfillment" section, click "ADD FULFILLMENT"

3. Select "Generate a License" as action and "Remote Server Request" as Generator.

4. Press NEXT to come to configuration

2

1. Set the following settings in the dialog:

   • URL: 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:

1. Navigate to the Product where your license fulfillment is configured.

2. Under the Fulfillments section, locate the fulfillment configuration you previously set up and click Edit.

3. On the Remote License Configuration page, click on the Parameters tab.

4. 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:

1. In your FastSpring store, go to "Integrations" and then "Webhooks"

2. 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"

3. 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 here.

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 adds 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 User Portal, 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:

1

For license-key based, in license fulfilment settings change:

• On product fulfilment add an additional parameter single_license and set its value to true.

Steps:

1. In "Catalog" select the desired product

2. On the product page scroll down to the fulfilment section

3. Click on the "Edit" button on the desired fulfilment

4. On the edit page click on the "Parameters" tab

5. Add the single_license parameter and set its value to true

2

Additionally add single_license custom attribute to the product and set its value to true to ensure subscription updates will work as expected.

Steps:

1. In "Catalog" select the desired product

2. In the upper right corner in the dropdown select the "Custom Attributes"

3. Add single_license custom attribute and set its value to true

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

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)

On the main product, add the feature as a "Related offer". Select Add Product options inside the Add new selector.

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.

How to set up product bundles in LicenseSpring?

1. Go to the Products section in LicenseSpring platform

2. Click the Add new bundle button

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

1. 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)

Product Bundle - Product Attributes

1. Go to FastSpring "Products" section

2. Open your product

3. In the Options > "Custom attributes" dialog of your product, add attributes:

• 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 Max simultaneous license users from quantity on a single license.

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

1. Go to FastSpring "Products" section

2. Open your product

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