# Stripe Integration {% hint style="info" %} LicenseSpring is available on the Stripe App Marketplace. You can find and install the app directly from {% endhint %} ## Connect LicenseSpring with Stripe {% stepper %} {% step %} Log in to [LicenseSpring](https://saas.licensespring.com/login) {% endstep %} {% step %} Go to **Settings → Integrations** and find the Stripe section {% endstep %} {% step %} Click on **Activate**

{% endstep %} {% step %} Provide the Account ID of the Stripe instance you wish to connect, choose a Management API key, and specify the Stripe instance type. Then, click **Confirm** ![](https://1783554078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgLzurdfXUuKr9IziZWLz%2Fuploads%2FmKakhZA9hnjDCztRk9xy%2Fimage.png?alt=media\&token=98699c63-4dba-4d36-8b08-7fde82b2106d) {% endstep %} {% step %} You will be redirected to Stripe, where you can review the necessary permissions and choose in which Stripe instance to install the app. Once reviewed, click **Continue** ![](https://1783554078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgLzurdfXUuKr9IziZWLz%2Fuploads%2FqUga47ZfKq2DZwBV0Dkd%2Fimage.png?alt=media\&token=f654bdb4-e89b-47fc-ac62-0c6a8fdd9ed3) {% endstep %} {% step %} If the process was successful, you'll be redirected to LicenseSpring, and your integration will be connected ![](https://1783554078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgLzurdfXUuKr9IziZWLz%2Fuploads%2FHvJfLO4TJzGFM48HcAYH%2FScreenshot%202026-03-02%20at%2009.32.45.png?alt=media\&token=1c711e04-786a-41b9-a34e-e37765f23a8e) {% endstep %} {% endstepper %} ## Create product in LicenseSpring platform Go to **Products → Add new Product** and create a new product

## Create product in Stripe dashboard {% stepper %} {% step %} Access your Stripe account linked with LicenseSpring from [step 1.](#connect-licensespring-with-stripe) {% endstep %} {% step %} Open the dashboard and navigate to **Product Catalogue → Create Product**. {% endstep %} {% step %} To create a product in Stripe, you need to set a **price**. For a **Recurring** billing type, the LicenseSpring app will generate a **subscription** (or **consumption**, if configured) license, using the **billing period** from the price settings for the license's **valid duration**. For a **One-off** billing type, the license type in LicenseSpring is defined by the product's default license type or the **`license_type`** [custom attribute](#custom-attributes). {% endstep %} {% step %} Click on **Add product**

{% endstep %} {% endstepper %} ## Add custom attributes to the product PRICE metadata {% hint style="info" %} Each product can have multiple prices. Each new price needs to have custom attributes defined as is show below. {% endhint %} To create licenses correctly, the LicenseSpring app utilizes the Stripe product's **price** metadata for custom attributes. To add attributes to the **price** metadata, navigate to the *Product catalogue* page, select a product, choose a **price**, and then edit the **price** metadata accordingly.

### License Policy In the LicenseSpring platform, you can assign one or more license policies to each product. These policies serve as a template for creating licenses. Add a license policy to a Stripe product **price** using the `license_policy` custom attribute, specifying a license policy code as the value. When an order is created through Stripe, our integration uses the fields, product features, and custom fields from the included license policy to generate the license. {% hint style="info" %} If you don't include the `license_policy` attribute, Stripe will use the product's default license policy. {% endhint %} For a Stripe subscription, the `license_type` will always be `subscription` (or `consumption` if the `license_type` custom attribute is used). The `valid_duration` is based on the product price's billing period. ### Custom Attributes Custom attributes are used to override fields from the license policy and to handle some specific use cases that license policies don't cover. Note that the `short_code` attribute is **always** required and is currently the only required field.

Custom Attribute	Type - Description
`short_code` (required)	`STRING` - The unique short code for the product in LicenseSpring.
`max_activations` (optional)	`NUMBER` - Sets the max activations of a license.
`floating_cloud` (optional)	`NUMBER` - 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.
`license_type` (optional)	`STRING` - Set as `perpetual`, `time-limited`, `subscription` or `consumption`. For recurring product prices, license type can be either `subscription` or `consumption`. In the case of consumption licenses, the total consumptions are reset at the start of each billing interval.
`valid_duration` (optional)	`STRING` - The format for this is `N[d/w/m/y]` where `N` is a number and `d`, `w`, `m`, or `y` represents days, weeks, months or years respectively (e.g., `20d` for 20 days). Not applicable for subscription licenses; these use the billing period from the price settings.
`enable_maintenance_duration` (optional)	`BOOLEAN` - Turns on maintenance capability. Set the value to `true` to enable. Any other value defaults to `false`. If the key is omitted, it defaults to the License Policy configuration.
`maintenance_duration` (optional)	`STRING` - Sets maintenance period. The format for this is `N[d/w/m/y]` where `N` is a number and `d`, `w`, `m`, or `y` represents days, weeks, months or years respectively (e.g., `20d` for 20 days).
`max_license_users` (optional)	`NUMBER` - Limits the number of users which can be added to the licenses. Can be added only for products with user authorization method.
`is_license_manager` (optional)	`BOOLEAN` - Set the value to `true` to enable. Any other value or omitting the key defaults to `false`. Sets the customer as a license manager. Useful on license-key based products where the customer is not set as a license manager per default.
`assign_customer_as_user` (optional)	`BOOLEAN` - Set the value to `true` to enable. Any other value or omitting the key defaults to `false`. Customer will be automatically assigned to the license as a license user. Can be added only for products with user authorization method.
`unpaid_active_license_period` (optional)	`STRING` - Used to define a period during which the licenses remain active even if they haven't been paid for yet. The format for this is `N[d/w/m/y]` where `N` is a number and `d`, `w`, `m`, or `y` represents days, weeks, months or years respectively (e.g., `20d` for 20 days).
`added_days` (optional)	`NUMBER` - Specifies the number of days to extend the current subscription interval. Applicable only to subscription licenses.
`ignore_product_in_licensespring` (optional)	`BOOLEAN` - Set the value to `true` to enable. Any other value or omitting the key defaults to `false`. Incoming webhooks for the specified product will be ignored, and a `200` status code will be returned to Stripe as a response.

### Custom Fields You can customize LicenseSpring license custom fields directly through Stripe using metadata attributes. If a product has an existing custom field, you can override its default value during the license creation process. This is done by adding a custom attribute to the Stripe Product **Price** Metadata using the following format: `custom_field_{CUSTOM_FIELD_NAME}` #### Example If you have a custom field named Serial (default value: `111`) and you want to assign a unique value: 1. Navigate to the specific Product **Price** metadata in Stripe. 2. Add a new metadata key named `custom_field_Serial`. 3. Enter your desired override value in the value field. > Note: To override multiple custom fields, you must add a separate metadata entry for each field using the `custom_field_` prefix. ### Single License In your store, users can select different quantities for a product. By default, if multiple quantities are selected, this results in multiple licenses, both user-based and license-key-based. If you prefer that selecting more than one quantity results in a single license that can be activated multiple times (for license-key based products) or a single license supporting multiple users (for user based products), you should add the custom attribute `is_single_license` with the value `true`.

### Max Simultaneous License Users from Quantity on a Single License In case of a single floating-cloud license, quantity can be used to determine max simultaneous license users. To enable this, please use the following combination of custom attributes on the product **price**: * `is_single_license` : `true` * `floating_cloud` : `1` * `floating_users_from_quantity` : `true` ## 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 Stripe is not supported. {% endhint %} How to set up product bundles in LicenseSpring? {% stepper %} {% step %} Go to the **Products** section in LicenseSpring platform {% endstep %} {% step %} Click the **Add new bundle** button ![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/MqSq06oKrmslMe28MahB/wTUy6_ZK7%20I06p4PDQYRS_image.png) {% endstep %} {% step %} Insert the desired **Bundle name** and **Bundle code**, choose which **Authorization method to use**, and select all the products that you want inside the bundle ![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/HHCvuAcatuQF0SO78BUL/XJbs1DPEaNQpUQupP0Bti_image.png) {% endstep %} {% step %} After the bundle is created, it should look something like the following picture. Take the **Bundle code** value and use it as the `short_code` in the Stripe configuration. (Look at the list below to see all the available Product attributes for bundle products) ![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/D6AafW4Z3OPXvTBlBkzN/H3BatFY8_bd8mVVZk6D49_image.png) {% endstep %} {% endstepper %} {% 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" %} Each license will include the features defined in the default license policy of the product for which the license was created. {% endhint %} ### Custom Attributes for bundles

Custom Attribute	Type - Description
`is_product_bundle` (required)	`BOOLEAN` - has to be set to `true`
`short_code` (required)	`STRING` - The unique short code for the product bundle in LicenseSpring.
`max_activations` (optional)	`NUMBER` - Sets the max activations of a license.
`floating_cloud` (optional)	`NUMBER` - 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.
`license_type` (optional)	`STRING` - Set as `perpetual`, `time-limited`, `subscription` or `consumption`. For recurring product prices, license type can be either `subscription` or `consumption`. In the case of consumption licenses, the total consumptions are reset at the start of each billing interval.
`valid_duration` (optional)	`STRING` - The format for this is `N[d/w/m/y]` where `N` is a number and `d`, `w`, `m`, or `y` represents days, weeks, months or years respectively (e.g., `20d` for 20 days). Not applicable for subscription licenses; these use the billing period from the price settings.
`enable_maintenance_duration` (optional)	`BOOLEAN` - Turns on maintenance capability. Set the value to `true` to enable. Any other value defaults to `false`. If the key is omitted, it defaults to the License Policy configuration.
`maintenance_duration` (optional)	`STRING` - Sets maintenance period. The format for this is `N[d/w/m/y]` where `N` is a number and `d`, `w`, `m`, or `y` represents days, weeks, months or years respectively (e.g., `20d` for 20 days).
`max_license_users` (optional)	`NUMBER` - Limits the number of users which can be added to the licenses. Can be added only for products with user authorization method.
`is_license_manager` (optional)	`BOOLEAN` - Set the value to `true` to enable. Any other value or omitting the key defaults to `false`. Sets the customer as a license manager. Useful on license-key based products where the customer is not set as a license manager per default.
`assign_customer_as_user` (optional)	`BOOLEAN` - Set the value to `true` to enable. Any other value or omitting the key defaults to `false`. Customer will be automatically assigned to the license as a license user. Can be added only for products with user authorization method.
`unpaid_active_license_period` (optional)	`STRING` - Used to define a period during which the licenses remain active even if they haven't been paid for yet. The format for this is `N[d/w/m/y]` where `N` is a number and `d`, `w`, `m`, or `y` represents days, weeks, months or years respectively (e.g., `20d` for 20 days).
`added_days` (optional)	`NUMBER` - Specifies the number of days to extend the current subscription interval. Applicable only to subscription licenses.

## Creating payment ### One-off #### With Invoices: ![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/dlU2BoKUWswyvXPattkI/beOA0z4mlHLBdS4YWqxX6_image.png) To generate an invoice, first select your customer and item (a one-time product). Then, set the payment collection method to 'Autocharge Customer.' Once you've reviewed everything, you can proceed to charge the customer. ![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/O9JCgxXce5xshg4HegyW/Nx7XYwO4vcZSU0LQ9biNH_image.png) #### With Payment Link: In the right upper corner click on the '+' sign and then on **Payment Link**. ![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/UkrryfJuM4oYVR53DM1U/Ie4qGwOGK_cd7Qcouz3jQ_screenshot%202024%2001%2017%20at%20142701.png) Once the page for payment link creation opens, select the **one-time** product price for which you want to create the link and click on **Create link**. ![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/m2tvClfaaU8S1jxBLX02/itb1WgkTz9LW7LGquhifW_screenshot%202024%2001%2017%20at%20142749.png) ### Recurring When dealing with subscription products, you should utilize a payment link. To do so, first choose 'Payment Link,' then select the product, and finally create the link. ![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/q5fVzoaXSiUNXNcDhadQ/MaTTd0I3SZ_8fx0%20_k2HZ_image.png) ![](https://content.gitbook.com/content/gLzurdfXUuKr9IziZWLz/blobs/kE6xsjGBaO6fSnttqJKh/86obH9xZqYk%20DvrOG9dAR_image.png) After creating the link, access it to complete the payment process. ## Webhook event reference Our integration supports five events from Stripe using API version `2026-01-28.clover`.

Event	Description
`checkout.session.completed`	Generates licenses if the checkout is not linked to either an invoice or a subscription.
`invoice.paid`	Generates any kind of license or extends the license's expiration date for a new subscription period.
`customer.subscription.updated`	When this event occurs, the current subscription is updated. Depending on the quantity, new licenses may be created, or existing ones may be disabled. Licenses are active when the Stripe subscription status is `active`, `trialing`, or `past_due`.
`customer.subscription.deleted`	All licenses associated with the subscription are deactivated.
`charge.refunded`	When a charge is refunded, all licenses linked to that payment intent are deactivated.

## Preview licenses in Stripe Licenses can be linked to either a subscription or a payment. * **Subscription-based License**: Open the associated subscription to view and manage licenses. * **Payment-based License**: Open the payment details where the license was originally created. {% hint style="warning" %} Licenses without an attached payment intent object can also be linked to a checkout or invoice. However, these licenses cannot currently be viewed in our Stripe LicenseSpring card. {% endhint %} In either view, you can enable, disable, and view details for each license displayed.

#### Managing Licenses **Enable a License** To enable a license, click the three dots on the desired license and select `Enable`. **Disable a License** To disable a license, click the three dots on the desired license and select `Disable`. **View License Details** To view detailed information about a license, click the three dots on the desired license and select `License Info`. A side panel will open with additional license details.

## Contact Support If you still have issues with the setup, need answers to certain questions or need additional functionalities added to the integration, please [**contact our LicenseSpring support team**](https://licensespring.zendesk.com/hc/en-us/requests/new).