Importing licenses from a CSV file
When you move to LicenseManager from another license manager, or from Lemon Squeezy, your customers already have license keys. Importing them with their current keys means nobody gets a new key, and the next version of your app accepts the keys your customers already pasted.
You can import:
- From the dashboard, with a CSV file: open Licenses and click Import. Any number of rows, sent in batches of 500.
- With the API, with
importLicenses: up to 500 licenses per request.
No email is sent: your customers already have their keys. For the whole move, from preparing the product to switching your app, follow Migrating from another license manager, or Migrating from Lemon Squeezy.
Import in a test product first, check the result, then import the same file in the live product. Test keys start with TEST-, which is added to every imported key in a test product.
The CSV file
One row per license, with a header row. Only key and email are required:
key,email,name,policy,expires_at,max_machines,price,currency,subscription_id,legacy_id
ACME-7F3K-Q9MZ-2XLP,jane@example.com,Jane Doe,Personal,2027-03-01,2,49,USD,,lic_8812
ACME-H4TR-CWN6-EYB3,john@example.com,John Smith,Business,,5,149,USD,,lic_8813
ACME-JDF7-KQ2M-X9ZP,max@example.com,,Monthly,,,,,sub_1MowQVLkdIwHu7ix,lic_8814| Column | Also recognized as | Value | When empty or missing |
|---|---|---|---|
key | license_key, license, serial | The license key, kept as is. Case sensitive, up to 255 characters, unique in the product. | The row isn’t imported. |
email | user_email, customer_email | The customer’s email. Licenses with the same email belong to the same customer. | The row isn’t imported. |
name | user_name, customer_name | The customer’s name, given to a customer who has none yet. | No name. |
policy | policy_id, plan, variant_name | The name or the id of a policy of the product, compared regardless of case. | The product’s default policy. |
expires_at | expires, expiration | A date, like 2027-03-01 or 2027-03-01T00:00:00Z. | Never expires, when the column exists. Without the column, the policy’s duration from today. |
max_machines | activation_limit, seats | A number of machines, or unlimited. | The policy’s. |
price, currency | amount | What was paid, like 49 and USD, for your revenue stats. | No price. USD when only the price is given. |
status | disabled | disabled or true leaves the row out. expired without a date expires the license now. | Imported. |
subscription_id | stripe_subscription_id, paddle_subscription_id | The Stripe or Paddle subscription paying for the license, see subscriptions. | Not a subscription license. |
Every other column is kept in the license’s meta, under imported: like { "imported": { "legacy_id": "lic_8812" } }. Use it for the ids of your old tool, so you can find a license again.
Column names are compared regardless of case, spaces, dashes and underscores: Expires At works like expires_at. Commas and semicolons both work as separators, and the file can come from Excel.
Import from the dashboard
Open the licenses
Open the product’s Licenses page, and click Import. You need a role that can create licenses.
Choose the file
The file is read in your browser, and checked before anything is sent. The dialog shows which column fills which field, the first rows, and the rows with errors: a missing key, an invalid email, a policy that doesn’t exist, a key twice in the file. Rows with errors are left out of the import: fix them in the file and choose it again.
Import
Click Import. The licenses are sent in batches of 500, and the dialog tells how many were imported, skipped and failed, with the line of each failure.
Importing again is safe. A key already used by a license of the product is skipped, and the license left as is. If the import is interrupted, or some rows failed, fix the file and import all of it again.
Subscriptions
A license paid by a subscription that moved to Stripe or Paddle, like the ones Lemon Squeezy’s migration moves to Stripe, must stay linked to it. Otherwise, the subscription’s next renewal creates a new license with a new key, emailed to the customer, and the imported one expires.
Put the subscription’s id in subscription_id, sub_…. The import then links the license to the subscription:
- Its renewals extend the imported license, and never create another one. When the subscription ends, the license expires, like the licenses its payments create.
- The license follows the policy of the subscription’s price, which must be mapped to a policy of the product: the
policycolumn is ignored. Its expiration comes from the subscription, it gets every update, and has no money back guarantee. - Its machines are the policy’s times the subscription’s quantity, unless the row gives
max_machines.
Connect Stripe or Paddle, and map the subscription’s prices, before importing. The subscription is read from the provider of the product’s mode: test products need a Stripe test mode or Paddle sandbox connection. A column named paddle_subscription_id, or a subscription_provider column set to paddle, reads it from Paddle.
A subscription keeps one license: a row whose subscription already has a license fails with subscription_taken.
With the API
POST /v1/products/{productId}/licenses/import (API reference ) creates up to 500 licenses per request, with an API key. Each license takes the fields of a license creation, but sendKey, with a required key, and optionally the customer’s name and a subscription:
curl -X POST https://api.licensemanager.dev/v1/products/x7Kp2QaZ/licenses/import \
-H "x-api-key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"licenses": [
{
"key": "ACME-7F3K-Q9MZ-2XLP",
"email": "jane@example.com",
"name": "Jane Doe",
"policyId": "p4Rt8LmQ",
"expiresAt": "2027-03-01T00:00:00Z",
"maxMachines": 2,
"price": { "amount": 49, "currency": "USD" },
"meta": { "legacyId": "lic_8812" }
},
{
"key": "ACME-JDF7-KQ2M-X9ZP",
"email": "max@example.com",
"subscription": { "provider": "stripe", "externalId": "sub_1MowQVLkdIwHu7ix" }
}
]
}'The licenses are imported one by one: one that fails doesn’t stop the others. The response tells the result of each, in the order sent:
{
"created": 1,
"skipped": 1,
"failed": 0,
"results": [
{ "index": 0, "key": "ACME-7F3K-Q9MZ-2XLP", "status": "skipped", "licenseId": "l3Nv8KwB", "error": { "code": "key_taken", "message": "Another license of the product already uses this key" } },
{ "index": 1, "key": "ACME-JDF7-KQ2M-X9ZP", "status": "created", "licenseId": "l9Qx2RtM", "error": null }
]
}error.code | Status | Meaning |
|---|---|---|
key_taken | skipped | A license of the product already uses the key, like one imported before. licenseId is its id. |
policy_not_found | failed | The product has no policy with this policyId. |
validation_error | failed | The minor version would lock before the major version. |
integration_not_connected | failed | The subscription’s provider isn’t connected in the product’s mode. |
integration_error | failed | The provider’s API key can’t read subscriptions. |
subscription_not_found | failed | The provider has no subscription with this id. |
subscription_not_mapped | failed | The subscription’s price isn’t mapped to a policy of the product. |
subscription_taken | failed | The subscription already keeps another license valid. |
A request whose body is invalid, like a license without a key or an invalid email, fails as a whole with 422, before anything is imported.
A request imports up to 500 licenses and counts as one toward your plan’s API requests: 3,000 licenses take 6 requests.
What isn’t imported
- Machines. Each license starts with no machine. Each computer is registered the first time the new version of your app validates its key, and takes a place then.
- History and creation dates. Each license starts with a
license.createdevent dated from the import. Keep the original date in a column, which goes into the meta. - Last activation. Imported licenses show as Inactive until their key is validated, and don’t count toward your plan’s active licenses until then.
Moving a large catalog, or from Lemon Squeezy? We help you import it for free: email sales@licensemanager.dev with where your licenses are today.