# FastSpring Contextual Store

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

{% hint style="info" %}
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
{% endhint %}

{% hint style="info" %}
For subscriptions, it's the same integration as for products below, with a few small precisions added at the bottom of this guide.
{% endhint %}

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

{% stepper %}
{% step %}

### Activate FastSpring integration in LicenseSpring

Go to Settings > Integrations > FastSpring and click **Activate**

![](/files/75316abada6486ff1fb47c46b6b86754e5dd1172)

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)

![](/files/83edec1b4f39c3776707f786cd9f26839c7c9af4)
{% endstep %}

{% step %}

### 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**](#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

{% hint style="warning" %}
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.
{% endhint %}

#### Custom fields

[**Custom fields**](broken://spaces/gLzurdfXUuKr9IziZWLz/pages/ac469c60c7cb5e80f8da43579eff3e0e71d6c740) 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}`.

{% hint style="info" %}
Please note that you need to do this for every product you plan to process through LicenseSpring.
{% endhint %}

![](/files/63c88c51b5d5388bbe222a92cf2e75096845d7cf)

![](/files/680c32ca82faa005ef37ba4792bd37cdeef0a49c)

{% hint style="info" %}
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.
{% endhint %}

![](/files/8df31cbeac9ec77e44d8c3cc7a4642fb7004fc99)
{% endstep %}

{% step %}

### Set-up License Generation

{% hint style="info" %}
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.
{% endhint %}

Follow these steps to add the fulfillment:

{% stepper %}
{% step %}

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
   {% endstep %}

{% step %}
5\. 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)`

![](/files/49ad09759b414dbfd369641ee4705f37f6b14360)
{% endstep %}
{% endstepper %}

![](/files/6bd9e0546e2cd83fe3d79b7eaaacae369dd65ebb)

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

![](/files/e454ea252bca0b568c1ec9903da32a258ce3d7bc)

![](/files/9305912b7802187abfe58a4f11ef67bca47f5c47)
{% endstep %}

{% step %}

### 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`

{% hint style="info" %}
Information on Fastspring's webooks can be found [**here.**](https://fastspring.com/docs/webhooks/)

Only the **order.completed** event is needed if you are not using subscriptions
{% endhint %}

![](/files/7c32af0f8065d7bc8c4ea2a7217754a77ed6a63c)

![](/files/03c6377385af9ddd3f8762acaa7409d09b3ee099)

![](/files/fbc4055a0c29d5b49b480c310e8885d26e1139a9)

![](/files/13295754a68d89135b312051a6134df5a75e0721)

![](/files/bca9600279f58f3a930dfcb3556548a0057447fe)

{% hint style="info" %}
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.
{% endhint %}

![](/files/16151036a499b7e57efdf491469237c541a2689e)
{% endstep %}
{% endstepper %}

### 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**](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.

![](/files/92ffcb4d1549b02dc196559ba4238afe50a79b92)

#### 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:

{% stepper %}
{% step %}
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`
   {% endstep %}

{% step %}
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

![](/files/e5629dd0ad4dbf34050f699f0f572bb186c05caa)
{% endstep %}
{% endstepper %}

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

{% hint style="warning" %}
Also, the products fulfillment **needs** to be set as described in the single license section shown above.
{% endhint %}

#### 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)

{% hint style="info" %}
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.
{% endhint %}

![Add the feature code from LicenseSpring as a custom attribute in FastSpring](/files/4b917914fd030adde2b0e82a3d223f0cd47a6891)

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](/files/7639f1d5bc8246cba04cddfe8d1ea783ff4e188a)

![Add features to the main product in the main popup](/files/c4157fc9a2d6684da4a47e5d0c75d76a38ef5626)

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

{% hint style="warning" %}
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.
{% endhint %}

How to set up product bundles in LicenseSpring?

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

![](/files/8acb7606162b08a4328d11f3d265658c927695d3)

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

![](/files/72dd777e6044c40af6aaa5dc02ab33075787978f)

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**)

![](/files/5219c583105eb28169d6c56c3839802ae2cbf04e)

{% hint style="info" %}
All other setup steps are the same as they are for basic Products. The only difference is in the supported **Product attributes**.
{% endhint %}

{% hint style="info" %}
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**.
{% endhint %}

{% hint style="warning" %}
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.
{% endhint %}

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**](#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`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.licensespring.com/integrations/fastspring/fastspring-contextual-store.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.