What carries over
Every importer keeps the key string as it is, the buyer's email and name, the status, the device limit, the expiry date, the original issue date and, when the source has them, the devices already activated. Keys are matched without regard to capitals.
All importers are safe to run again. A key that is already in your account is never overwritten; it only gains devices it did not have yet. A key that belongs to a different Clavem account is reported as a conflict and left alone. The plan limit is checked before each batch is written, and keys that are expired or disabled do not count against it.
Devices and the status
A device appears on a license when your app calls activate. Keys imported from another system keep working without that step, but their old devices are only known to Clavem if the import included them. The dashboard then shows the license as Valid with, for example, 0 of 3 devices, which means no device has been activated through Clavem yet, not that the key was never used.
Include the devices when you can. Each one is stored under the instance id your app already saved, so a validate call with that instance_id succeeds straight away, and the seats the buyer used are counted against the limit. A license that had more devices than its limit is imported with all of them and the import says so; new activations are refused until a seat is free.
The License API's status follows the Lemon Squeezy shape: inactive with no active device, active with one or more. Both are valid.
Lemon Squeezy
In the dashboard open Import, choose Lemon Squeezy and paste an API key from Lemon Squeezy's Settings, API. Clavem reads your stores page by page and brings over keys, buyers, limits, expiry dates, instances and the original store, order, product and variant ids that the License API returns in meta. The key is used for that run only and never stored. See also moving from Lemon Squeezy.
Dodo Payments
Choose Dodo Payments on the Import screen, pick live or test mode and paste an API key with read access to license keys, customers and products. Map each Dodo product to a Clavem product, or let Clavem create one with the same name. Clavem imports keys, buyers, status, activation limits, expiry dates and license key instances page by page; a stopped run resumes where it ended.
Instances keep their Dodo id (lki_…), so an app that stored license_key_instance_id can send it as instance_id. A Dodo key with no activation limit is imported as unlimited. Your Dodo API key is used for the run only and never stored.
This importer was built from Dodo Payments' published API documentation and has not yet been run against a live Dodo store, so check the first page of results before importing everything.
CSV or JSON file
Choose CSV or JSON file on the Import screen. The file is read in your browser and sent in batches of 500. CSV needs a header row; columns are matched by name in any order, and separators can be commas, semicolons or tabs. JSON is an array of objects with the same names. Columns that are not listed below are ignored, and the import shows which ones.
| Column | Required | Meaning |
|---|---|---|
key | Yes | The license key, 12 to 256 characters, kept exactly as written. |
email | Yes | The buyer's email address. |
name | No | The buyer's name. |
activation_limit | No | Devices allowed, or -1 for unlimited. Empty uses the product's limit. |
status | No | inactive, active, expired or disabled. Empty means valid. |
expires_at | No | ISO 8601 date or time. Empty never expires. |
created_at | No | The original issue date, ISO 8601. Empty uses the import date. |
instance_id | No | A device already activated, under the id your app stored. Several: separate them with |, or repeat the key on another row with the next device. |
instance_name | No | Device names in the same order as instance_id. Empty becomes “Imported device”. |
instance_created_at | No | Activation dates in the same order as instance_id. |
devices | No | JSON only: an array of { "instance_id", "name", "created_at" } instead of the three columns above. |
key,email,name,activation_limit,expires_at,created_at,instance_id,instance_name
7QX2M-4KD9P-ZR8TB-W3NVH-61CJA,ada@example.com,Ada,3,,2024-03-04,mac-7f3a|mac-91bc,MacBook Pro|iMac
JX81Q-PL2MV-0T4RW-8KDNE-C5ZUA,bo@example.com,,2,2027-01-31,2025-06-01,,[
{
"key": "7QX2M-4KD9P-ZR8TB-W3NVH-61CJA",
"email": "ada@example.com",
"activation_limit": 3,
"created_at": "2024-03-04T10:00:00Z",
"devices": [
{ "instance_id": "mac-7f3a", "name": "MacBook Pro", "created_at": "2024-03-04T10:02:00Z" }
]
}
]Dates without a time zone are read as UTC. A row that cannot be read is listed with its number and the reason; the other rows are still imported.
From your own database (Postgres, Neon, Supabase, MySQL…)
If you issued keys yourself, select them with the column names above. This example assumes a licenses table and a devices table; rename the columns to match yours.
select l.license_key as key,
l.customer_email as email,
l.customer_name as name,
l.max_devices as activation_limit,
l.expires_at,
l.created_at,
coalesce(json_agg(json_build_object(
'instance_id', d.instance_id,
'name', d.device_name,
'created_at', d.activated_at))
filter (where d.instance_id is not null), '[]') as devices
from licenses l
left join devices d on d.license_id = l.id and d.removed_at is null
group by l.idThen either save the result as a file and use the file import, or send it to the Import API from a script.
- psql, as JSON: wrap the query in
json_aggand write it to a file. - psql, as CSV: use
\copy … with csv header, written on one line, and join devices withstring_agg(…, '|'). - Neon or Supabase SQL editor: run the query and download the result as CSV or JSON.
- MySQL: use
JSON_ARRAYAGG(JSON_OBJECT(…))for devices, orGROUP_CONCAT(… SEPARATOR '|')for a CSV.
psql "$DATABASE_URL" -At -c "select json_agg(t) from ( <the query above> ) t" > licenses.json\copy (select l.license_key as key, l.customer_email as email, string_agg(d.instance_id, '|' order by d.id) as instance_id, string_agg(coalesce(d.device_name, ''), '|' order by d.id) as instance_name from licenses l left join devices d on d.license_id = l.id group by l.id) to 'licenses.csv' with csv headerTo import straight from a script, create an API key in the dashboard under Developers, find the product id with GET /v1/admin/products, and run this with Node 18 or later. It reads the JSON file from above and sends it in batches of 500.
// node import-licenses.mjs licenses.json
import { readFile } from 'node:fs/promises';
const API = 'https://clavem.io/v1/admin/licenses/import';
const KEY = process.env.CLAVEM_API_KEY; // sk_clavem_…
const PRODUCT_ID = Number(process.env.CLAVEM_PRODUCT_ID);
const rows = JSON.parse(await readFile(process.argv[2], 'utf8'));
const licenses = rows.map((r) => ({ ...r, product_id: PRODUCT_ID }));
for (let i = 0; i < licenses.length; i += 500) {
const res = await fetch(API, {
method: 'POST',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ licenses: licenses.slice(i, i + 500) }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${body.error?.message}`);
console.log(`batch ${i / 500 + 1}`, body.summary);
for (const r of body.results) {
if (r.reason === 'invalid' || r.reason === 'key_in_other_account') console.warn(i + r.index, r.key, r.message);
}
}Running it twice is safe: the second run reports every key as skipped with the reason unchanged.
Import API
POST /v1/admin/licenses/import takes up to 500 licenses per call, authenticated with a management API key like the rest of the Management API. It uses the same rules as the file import.
POST /v1/admin/licenses/import
Authorization: Bearer sk_clavem_…
Content-Type: application/json
{
"licenses": [
{
"key": "7QX2M-4KD9P-ZR8TB-W3NVH-61CJA",
"product_id": 12,
"email": "ada@example.com",
"name": "Ada",
"status": "active",
"activation_limit": 3,
"expires_at": null,
"created_at": "2024-03-04T10:00:00Z",
"devices": [
{ "instance_id": "mac-7f3a", "name": "MacBook Pro", "created_at": "2024-03-04T10:02:00Z" }
]
}
]
}{
"summary": { "imported": 1, "updated": 0, "skipped": 0, "conflicts": 0, "invalid": 0, "devices_added": 1, "over_limit": 0 },
"results": [
{ "index": 0, "key": "7QX2M-4KD9P-ZR8TB-W3NVH-61CJA", "status": "imported", "license_id": 412,
"devices_added": 1, "devices": 1, "activation_limit": 3, "over_limit": false }
],
"ignored_fields": []
}| Result | Meaning |
|---|---|
imported | A new license, with its devices. |
updated | The key was already in your account and gained devices it did not have. Nothing else on it changes. |
skipped, unchanged | Already imported, nothing new. |
skipped, key_in_other_account | The key is registered to a different Clavem account. It is not touched; contact us to resolve it. |
skipped, duplicate_in_request | The same key appeared earlier in the call. Its devices were added to that item. |
skipped, invalid | The item could not be read. message says why; the rest of the call still imports. |
A product_id that is not one of your products refuses the whole call with 404, and a call that would go past your plan's license limit is refused with 402 plan_limit. In both cases nothing is written. Unknown fields are ignored and listed in ignored_fields.