What a row needs
Each row is one license. It needs a key of 12 to 256 characters and an email. Everything else is optional, and an empty cell means “use the default”: the product’s device limit, no expiry, today’s date as the issue date. The file is read in your browser, so it never leaves the machine except as validated rows.
Name the headers the importer knows
Headers are matched by name, in any order, after a clean-up that ignores case, spaces, hyphens and camelCase, so Activation Limit, activation-limit and activationLimit are the same. These names are recognised:
| Field | Accepted header names |
|---|---|
| key | key, license_key, licence_key |
email, e_mail, email_address, customer_email |
|
| name | name, customer_name |
| activation limit | activation_limit, activations_limit, device_limit |
| expiry | expires_at |
| status | status |
| issue date | created_at, issued_at |
| device id | instance_id, instance_ids, device_id, device_ids |
| device name | instance_name, instance_names, device_name, device_names |
| device date | instance_created_at, device_created_at, activated_at |
The expiry column has one accepted name. In a test file with the headers License Key, E-mail, Expiry Date, Seats, activation-limit, Issued At and a second Email, the first, second, fifth and sixth columns were read correctly. Expiry Date and Seats were ignored, and the second Email lost to the first. The row, which was meant to expire on 2025-01-31, came out with no expiry. The dashboard shows each header with the field it maps to or “Ignored”, and lists ignored columns in a notice, so read that list before you press import.
Prepare the sheet
- Put the header in row 1, with no title rows above it. A file without a header has its first data row read as headers, and the import stops with a missing
keyandemail. - Format the key column as text before you paste. Spreadsheets convert text that looks like a number or a date.
- Format date columns as
yyyy-mm-ddbefore exporting, with no time or with a time and a zone. Dates without a zone are read as UTC. A spreadsheet’s internal date number such as45000is refused, and so is31/01/2027. - Leave
expires_atempty for a license that never expires. A far-future date like9999-12-31is refused, because dates run from 1990 to 2200. - Put
-1in the limit column for unlimited.0is refused, and an empty cell uses the product’s limit. - Use one of
inactive,active,expiredordisabledinstatus, or leave it empty for valid. Case does not matter, butrevokedandrefundedare refused. - Export as CSV with UTF-8 encoding: “CSV UTF-8” in Excel, “Comma-separated values” in Google Sheets, or the CSV export in Numbers.
Several devices on one key
If you know which devices were activated, give them under the id your app stored, so a validate call with that instance_id succeeds. There are two ways. Put several ids in one cell separated by |, with names and dates in the same order in their own cells, or repeat the key on a second row with the next device:
key,email,name,activation_limit,instance_id,instance_name,instance_created_at
7QX2M-4KD9P-ZR8TB-W3NVH-61CJA,ada@example.com,Ada,3,mac-7f3a,MacBook Pro,2024-03-04T10:02:00Z
7QX2M-4KD9P-ZR8TB-W3NVH-61CJA,ada@example.com,Ada,3,mac-91bc,iMac,2024-04-10T08:00:00Z
JX81Q-PL2MV-0T4RW-8KDNE-C5ZUA,bo@example.com,,2,,,
A device with no name becomes “Imported device”. If a license has more devices than its limit, all of them are imported and the result says so, and new activations are refused until a seat is free. Without any device columns the dashboard notes that no device will show until your app activates.
What the check says before anything is sent
A test file with seven rows produced four accepted rows and three refused ones, each reported by position among the data rows with the first problem it found:
| Row | Problem | Message |
|---|---|---|
| 2 | key SHORT-KEY |
key is shorter than 12 characters |
| 4 | limit 0 |
activationLimit must be a positive number, or -1 for unlimited |
| 5 | limit unlimited |
activationLimit must be a number |
The same test file held the key 7QX2M-4KD9P-ZR8TB-W3NVH-61CJA twice, once in lower case. Keys are matched without regard to capitals, so those rows are one license: in a single request the second is merged into the first, and in a later one it is skipped as unchanged. A semicolon-separated file with a byte order mark and a header License Key was read without any change.
Plan limits and batches
The dashboard sends 500 rows at a time. Before each batch, Clavem counts the active and inactive, unexpired licenses it would add. Expired and disabled rows do not count. If the batch would pass your plan’s limit, it is refused whole with plan_limit and nothing from it is written. A made-up example: a sheet of 1,200 rows where 1,000 are live and 200 are expired needs room for 1,000 licenses. The Free plan covers 50, Indie covers 1,000, and Studio covers 10,000, so the sheet fits Indie only if you have no other active licenses. Import the expired rows first, since they cost nothing against the limit. The plans are on the pricing page.
Importing it
Open Import, choose CSV or JSON file, pick the Clavem product and the file. Check the column list, read the five preview rows, and run it. A bad row is listed and the rest still import. Running the same file again is safe: a key already in your account is skipped, and only devices it lacked are added. A file belongs to one product, so split sheets that cover several. If the sheet has thousands of rows, use POST /v1/admin/licenses/import as described in Import existing licenses.
Check one key afterwards:
curl https://clavem.io/v1/licenses/validate -d license_key=7QX2M-4KD9P-ZR8TB-W3NVH-61CJA
After the import
Your app needs to call Clavem’s License API, as in the API reference: activate once per device, validate at launch. If the sheet was how you tracked sales, connect Stripe next, as in Connecting Stripe, so new purchases issue keys without you typing them in. Imported keys have no Stripe subscription, so renewals do not touch them. Give subscription keys an expires_at and extend them with PATCH when people renew.
Rollback
Keep the spreadsheet as it was. The import does not change it, and it has no undo button, so try ten rows on a test product first. Anything you do not want can be disabled from the license’s page or with PATCH /v1/admin/licenses/:id. The Licenses screen exports every key, buyer and status as CSV when you want a fresh copy.
Questions
Which columns are required?
Only key and email. Name, activation limit, status, expiry, creation date and devices are optional.
Can I use semicolons or tabs instead of commas?
Yes. The reader detects a comma, semicolon or tab from the first line, which covers the semicolon files that European spreadsheet settings produce. A leading byte order mark is dropped.
Is there an undo for an import?
No. A key you did not want can be disabled in the dashboard or with PATCH /v1/admin/licenses/:id. Import a small sample first.