Integrations
FastSpring

FastSpring Contextual Store

36min

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:

  1. Activate FastSpring integration in LicenseSpring
  2. Setup Product Attributes
  3. Setup License Generation
  4. Setup webhook integration

1. Activate FastSpring integration in LicenseSpring

Go to Settings > Integrations > FastSpring and click Activate

Document image


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)

Document image


2. Setup Product Attributes

  1. Go to FastSpring "Products" section
  2. Open your product.
  3. 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 here
  • license_type - optional, STRING. If this field is not included, the default license type from the product configuration in LicenseSpring is used (perpetualtime-limitedsubscription, 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.

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

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.

Opening "Custom attributes" in FastSpring
Opening "Custom attributes" in FastSpring

Document image


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.

Retrieving uuid and mgmt key
Retrieving uuid and mgmt key


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.

  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
  5. Set the following settings in the dialog:
License generation fulfillment
License generation fulfillment




Document image


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:

urlhttps://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

Add a title to your new webhook and be sure to enable webhook expansion
Add a title to your new webhook and be sure to enable webhook expansion

Add Webhook URL Endpoint
Add Webhook URL Endpoint

Document image

Select the appropriate events to send back to LicenseSpring
Select the appropriate events to send back to LicenseSpring

You can find your Shared Key in your LicenseSpring Account
You can find your Shared Key in your LicenseSpring Account


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.

FastSpring Webhook events will be found under a license's "Usage report" on LicenseSpring
FastSpring Webhook events will be found under a license's "Usage report" on LicenseSpring


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

Edit subscription pricing
Edit subscription pricing


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:

  1. On product additional parameters add an additional parameter single_licenseand set its value to true
  2. Additionally add single_license custom attribute to the product and set it's value to true to ensure subscription updates will work as expected.
Setting single-license behaviours
Setting single-license behaviours


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
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 Related Offers to the main product

Add features to the main product in the main popup
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?

  1. Go to the Products section in LicenseSpring platform
  2. Click the Add new bundle button

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

    Document image
    
  4. 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)

    Document image
    



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

  1. Go to FastSpring "Products" section
  2. Open your product
  3. 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 (perpetualtime-limitedsubscription, 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.