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. Setup product attributes
2. Setup license generation
3. Setup webhook integration

1. 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 Account Settings > Settings > 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 (OLD LINK)
• 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 based products where customer is not set as a license manager per 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.

Custom Fields

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







2. Set-up License Generation

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:
   • URL: https://api.licensespring.com/api/fast_license
   • Method : HTTP POST
   • POST Encoding: UTF-8
   • Output format : Single line license (Quantity based)

3. 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 "webhook expansion"
3. In the new webhook section, add a new webhook by pressing "ADD WEBHOOK URL" and fill it out with:

url: https://api.licensespring.com/api/fs_contextual 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.

For subscriptions, please also send the following webhooks:

• 'subscription.activated'
• 'subscription.deactivated'
• 'subscription.canceled'
• 'subscription.uncanceled`
• 'subscription.updated'
• 'subscription.payment.reminder'
• 'subscription.payment.overdue'
• 'subscription.charge.completed'
• 'subscription.charge.failed'

Webhook Events

This section describes what the expected behavior is for the web hooks.

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

Is triggered when subscription is activated.

• In LicenseSpring: LS: If this subscription was previously deactivated, it is now activated and Expiration date is set to next

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.

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

At the time of this writing, Subscriptions have been simplified on FastSpring. Subscriptions are now configured like a normal product. This means that you can issue Licenses of any type (Subscription, Perpetual etc.).

For example:

• In LicenseSpring configure a product with the code "basicproduct" and set default license type to perpetual
• In FastSpring create create product called "Lifetime basic" and set uuid and product_short_code=basicproduct in custom attributes and set a price.
• In FastSpring, you can then create a subscription, call it "Basic subscription" with product_short_code=basicproduct (same as the product). The LicenseSpring Webhook will recognize that this is a subscription and it will create a license that is a subscription even though default license type of product configuration in LicenseSpring is perpetual.

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 "Output format" to "Single license only"
2. On product additional parameters add an additional parameter single_licenseand set its value to true
3. Additionally add single_license custom attribute to the product and set it's value to true to ensure subscription updates will work as expected.

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, products fulfillment needs to set as described in the single license sections 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)



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