Clavem

Turn a spreadsheet of license keys into working licenses with the CSV import

A spreadsheet is enough if every row has a key and a buyer's email. Name your headers the way the importer expects, because a column it does not recognise is ignored without stopping the import, and an ignored expiry column turns every key into one that never expires.

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

  1. 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 key and email.
  2. Format the key column as text before you paste. Spreadsheets convert text that looks like a number or a date.
  3. Format date columns as yyyy-mm-dd before 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 as 45000 is refused, and so is 31/01/2027.
  4. Leave expires_at empty for a license that never expires. A far-future date like 9999-12-31 is refused, because dates run from 1990 to 2200.
  5. Put -1 in the limit column for unlimited. 0 is refused, and an empty cell uses the product’s limit.
  6. Use one of inactive, active, expired or disabled in status, or leave it empty for valid. Case does not matter, but revoked and refunded are refused.
  7. 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.