# FastSpring Contextual Store Old

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

{% stepper %}
{% 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 the following attributes:

* `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 [**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 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/integrations/fastspring/broken-reference) can also be 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 %}

![Opening "Custom attributes" in FastSpring](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/GlxT2WPhQj0O2zyI84A3/WpS83cQUh6_k3XBJWXSbO_image.png)

![Setting up product parameters in "Custom attributes"](https://api.archbee.com/api/optimize/IJdHyjBlO9LOXOrDnWJTx/6fgVXkdvF4KHA1zpGX9Mm_image.png)

![You can find your uuid in your LinceseSpring Account](https://api.archbee.com/api/optimize/IJdHyjBlO9LOXOrDnWJTx/bi6wyIPeBZHYbEmoPbJYI_image.png)
{% endstep %}

{% step %}

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

{% code title="Remote Server Request configuration" %}

```
URL: https://api.licensespring.com/api/fast_license
Method: HTTP POST
POST Encoding: UTF-8
Output format: Single line license (Quantity based)
```

{% endcode %}

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/UTtUAp67hJgAdctiCZTx/remote_server_request.png)

![](https://api.archbee.com/api/optimize/IJdHyjBlO9LOXOrDnWJTx/3RK60_bACtMMKbh3hBdnX_screenshot-2024-02-12-at-095845.png)
{% 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 "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`

{% hint style="info" %}
Information on FastSpring's webhooks can be found on [FastSpring's Webhook Page](https://fastspring.com/docs/webhooks/).
{% endhint %}

{% hint style="info" %}
Only the `order.completed` is needed if you are not using subscriptions.
{% endhint %}

![Adding a new webhook](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/3bcdhOeTfu7PcOwlHw6t/add_webhook.png)

![Add a title to your new webhook and be sure to enable webhook expansion](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/WGANqtYNSaadQFaCKSl8/add_webhook_2_CGlHsXb.png)

![Add Webhook URL Endpoint](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/hSYjusUd6UGhLifKfKtZ/add_webhook_3.png)

![Add your LicenseSpring's URL and your Shared Key to the Endpoint](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/1yklnb2EpYjQezlV8oIU/add_webhook_4.png)

![Select the appropriate events to send back to LicenseSpring](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/JCnXPjjrQ4htiuToKj35/add_webhook_5.png)

![You can find your Shared Key in your LicenseSpring Account](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/eTIVRJSdIpC0HYCpFew5/find_shared_key.png)

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

![FastSpring Webhook events will be found under a license's "Usage report" on LicenseSpring](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/lnDrEljZSgY9kEXwC5v5/License_usage_report.png)
{% endstep %}
{% endstepper %}

### Webhook Events

This section describes the expected behavior for the webhooks.

#### order.completed

This is the main webhook, and is triggered after clearing payment and all fulfillment 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

Triggered when subscription is activated.

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

#### subscription.deactivated

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

Triggered when the subscription is cancelled and 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

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

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

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 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 free trial days when editing subscription price. When order is created using a subscription with trial days, LicenseSpring integration will recognize this and create a trial license using the 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.

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/BLVqOfyTV6lluw0IMco9/Screen_Shot_2021%2003%2024_at_12.45.51_PM.png)

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

Example workflow:

* In LicenseSpring configure a product with the code `basicproduct` and set default license type to perpetual.
* In FastSpring 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

Default behaviour: when a user selects different quantities for a product, multiple quantities will result in multiple licenses (both user and license-key based).

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), do the following:

1. For license-key based, in license fulfillment settings change "Output format" to "Single license only".
2. On product additional parameters add an additional parameter `single_license` and set its value to `true`.
3. Additionally add `single_license` custom attribute to the product and set its value to `true` to ensure subscription updates will work as expected.

![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/nS0Q0mteAQJxbxI62uFF/single_license.png)

#### Max Simultaneous License Users from Quantity on a Single License

For a 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, use the 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, product fulfillment needs to be set as described in the single license section 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, add the following custom attribute on the product:

`license_type = time-limited`

You can use the same Product configured in LicenseSpring for many different products in FastSpring by adjusting custom attributes.

#### Features

You can add features to both products and subscriptions. Features need to be first set up as a normal product in FastSpring. The product name does not matter. The custom attribute is used to recognize which feature to add to a license. Set a custom attribute:

`feature_code = my_feature` (where `my_feature` is the code of the feature on a LicenseSpring product).

No additional configuration is required (such as fulfillment).

{% hint style="info" %}
The product path and feature code need to be the same so the 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](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/1lKppygEXIKmqw2cHVK1/feature_1.png)

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](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/PMZo7IgjSfHMrYN6UREA/features_2_LxS5E1J.png)

![Add features to the main product in the main popup](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/RwYLev6Sv7PWJbDiuBDa/feature_4.png)