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
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)
- Go to FastSpring "Products" section
- Open your product.
- In the Options > "Custom attributes" dialog of your product
- 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 here
- 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.
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 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.
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:
- Method : HTTP POST
- POST Encoding: UTF-8
- Output format : Single line license (Quantity based)
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 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.
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
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.
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.
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 )
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 additional parameters add an additional parameter single_licenseand 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 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.
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.
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.
On the main product, add the feature as a "Related offer". Select Add Product options inside the Add new selector.
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 here
- 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.
