Skip to the content

Changelog

Dated versions of the HTS Pilot API and what changed in each.

Each entry is a dated record of the published contract: the OpenAPI document as it was on that day. The service always runs the latest version (Versioning and changes). The list under an entry is generated from the difference between its document and the one before.

2026-10-13

Japan as an import market, in its English and Japanese editions

Japan is now a fourth import market, JP, and a new field, tariff_language, chooses the language of the tariff text. Nothing that worked stops working: a call that does not send tariff_language behaves as before, and US, EU and VN are unchanged.

Japan (JP)

  • The schedule is Japan's Tariff Schedule as Japan Customs publishes it on customs.go.jp. The edition of 8 August 2026 is loaded (dataset_version 2026-08-08).
  • Japan Customs publishes it in an official English edition and an official Japanese edition, and each is a dataset of its own: GET /api/datasets lists two JP datasets of the same version, both active, named Japan (Tariff Schedule) - English and Japan (Tariff Schedule) - Japanese. A new field of the dataset, language (en or ja), says which edition it holds; it is en for every other dataset (Tariff data).
  • JP is accepted wherever market is: a classify request, a SKU, a batch and every tariff data operation (Tariff data).
  • A code has 9 digits and is written 6109.10.010: the six digits of the HS subheading and a 3-digit statistical code, 000 when the subheading is not split. national_digits of the dataset is 9.
  • GET /api/health has a new key, background.jp_tariff, with the values of vn_tariff (System).
  • The duty estimate for JP is in yen (currency is JPY), in whole yen. The answer of estimateDuty has no schema in the document, so the fields of a Japan estimate are described in Tariff data and are not in the generated difference below:
    • reference_only (always true) and source_notice: the schedule is published for reference only;
    • rate_columns: every rate the schedule prints for the line, and whether the origin can claim it;
    • preferences: the GSP, LDC and agreement rates of the line;
    • rate_basis: the rate the estimate took, one of general, temporary, wto, gsp, ldc or epa:<KEY>;
    • a range, when the line is printed as several rows or a rate holds only under a condition, is given in duty_min, duty_max, landed_cost_min and landed_cost_max;
    • consumption tax on imports is not included.

The tariff language, tariff_language

  • An optional field, en or ja, en when it is not sent. Only JP offers ja: Japan Customs publishes the schedule in an official English edition and an official Japanese edition, and ja shows the Japanese edition. It is not a translation, and it is chosen by this field, never by Accept-Language (Languages).
  • It is accepted in the body of POST /api/classify, POST /api/lookups/{lookup_id}/rerun, POST /api/batches/{batch_id}/start, POST /api/hts/duty-estimate and POST /api/skus/bulk, and as a query parameter of GET /api/hts/search, GET /api/hts/tree, GET /api/datasets/{dataset_id}/entries and POST /api/skus/{sku_id}/classify.
  • It is returned on a lookup (LookupSummary, LookupDetail), on a batch (BatchOut) and in the answers of the search, the tree and the duty estimate.
  • tariff_languages of a dataset lists what its market offers: ["en", "ja"] for JP, ["en"] for the other markets.
  • tariff_language picks the dataset a call reads. With ja, the dataset of an answer (the search, the tree, the duty estimate, result.dataset of a lookup) is the Japanese dataset, with its own id and name, and a lookup or a batch run in ja keeps that dataset. GET /api/datasets/{dataset_id}/entries reads the dataset's own edition when tariff_language is not sent, and the other edition of the same version when it names the other language.
  • When the edition asked for is not loaded for the version, the call is answered 404 with the code not_found; it is never answered from the other edition. A language the market does not offer is checked first and stays a 422 (Errors).
  • A value the market does not offer is refused with 422 and the code validation_error (Errors). A value other than en or ja is refused with the same status.
  • POST /api/skus/bulk differs from every other operation. A bulk call can mix markets, so its tariff_language applies to the items whose market offers it, and the other items are classified in en: it is not refused for a market. It matters only with classify_missing.

What to do

  • Nothing, for an integration that uses US, EU or VN.

  • Do not hard-code three markets: a list of markets can now hold JP.

  • Read tariff_languages from GET /api/datasets before you offer Japanese text for a market.

  • If you pick a dataset from GET /api/datasets by market and version, expect two for JP and choose by language.

  • Handle yen as whole numbers: JPY has no decimals.

  • Ignore the fields you do not know.

  • Added: GET /api/datasets/{dataset_id}/entries: query parameter tariff_language (string or null)

  • Added: GET /api/hts/search: query parameter tariff_language (string or null)

  • Added: GET /api/hts/tree: query parameter tariff_language (string or null)

  • Added: POST /api/skus/{sku_id}/classify: query parameter tariff_language (string or null)

  • Added: Schema BatchOut: field tariff_language (string)

  • Added: Schema BatchStartRequest: field tariff_language (string or null)

  • Added: Schema BulkRequest: field tariff_language (string or null)

  • Added: Schema ClassifyRequest: field tariff_language (string or null)

  • Added: Schema DatasetOut: field language (string)

  • Added: Schema DatasetOut: field tariff_languages (string[])

  • Added: Schema DutyRequest: field tariff_language (string or null)

  • Added: Schema LookupDetail: field tariff_language (string)

  • Added: Schema LookupSummary: field tariff_language (string)

  • Added: Schema RerunRequest: field tariff_language (string or null)

2026-10-09

Workspaces: keys, webhooks, credits and plans

API keys, webhooks, credits and plans now belong to a workspace: the account of one person (its personal workspace) or a team that several accounts share, each member with a role there (owner, admin, reviewer or member). The generated difference below is empty: the operations, parameters and schemas are the same, and the changes are in answers that the document declares without a schema, in who may make a call, and in five new error codes. Most of it applies only while the service has workspaces switched on, which it does not yet. A few changes apply now; they are listed first.

Changed now

  • A webhook receives the events of its own workspace only: the lookups, batches and catalog alerts made there. It no longer receives the events of every account of the service. In tariff.changed, sku_alerts counts the alerts of that workspace only (Webhooks).
  • The webhook object has a new field, organisation_id: the id of the workspace whose events it receives (Webhook endpoints).
  • GET /api/webhooks/events is open to every key, whatever its role. It needed the admin role.
  • A ledger row has a new field, api_key_id: the id of the API key a lookup was made with, on the row of its fee, else null. It is in the rows of GET /api/usage/ledger and in transactions of GET /api/usage/me. The CSV download is unchanged (Usage).
  • The test call of a webhook is also limited to 20 calls per minute for one workspace, beside 5 per webhook.

While workspaces are switched on

  • A key acts in the workspace it was made in, never anywhere else. Its role is the role it was given (entry acts as a member), capped at the role its creator holds in that workspace now, and never above admin. The role of the creator's account on the service plays no part (Authentication).
  • Keys and webhooks are managed by the admin and owner of the workspace, and a key with the admin role sees and changes the webhooks of its own workspace only. A webhook of another workspace answers 404.
  • Creating a webhook and changing its url need a person signed in to the application. A key is answered 403 with the code session_required. A key can still list webhooks, pause one, change its events, test it, read its deliveries and delete it. Keys are created in the application, as before.
  • Credits are those of the workspace. In a personal workspace the balance is the account's, as before; in a team workspace the lookups of every member are charged to one balance that the team shares. credits of GET /api/usage/me and GET /api/auth/me is that balance, and null when the caller's lookups in that workspace are free.
  • GET /api/plans/me is the plan and the free trial of the workspace. When the trial of a workspace has ended, every member and every key of it is answered 402 with trial_ended.
  • GET /api/usage/ledger lists the rows of the workspace for its admin and owner, and one's own rows for anyone else. A user_id that does not name a member of the workspace answers 404. A ledger row has organisation_id, the workspace whose balance it changed.
  • GET /api/auth/me has two more fields: workspace (id, name and role) and workspace_role, the role the request acts with there. role is unchanged and keeps its three values.
  • Five codes are new, all with the status they name: session_required (403), workspace_required (403), workspace_mismatch (403), member_suspended (403) and workspace_not_found (404) (Errors).

The examples of this version also show two fields added by an earlier release: user_deleted on the events of a lookup and deleted on the users of the productivity report, both true for an account that was erased.

What to do

  • If your system registers its webhooks itself, or changes their address, move that step to a person signed in to the application before workspaces are switched on. Pausing a webhook and changing its events still work with a key.
  • If a webhook should see the events of a team, create it in that team's workspace. A webhook made in a personal workspace receives that workspace's events only.
  • Treat credits as a number or null, and the five new codes as a stop: retrying the same call gives the same answer. A code you do not know is still handled by its status.
  • Ignore fields you do not know: organisation_id, api_key_id, workspace and workspace_role are added to existing answers.

No difference in the specification.

Read the reference as of 2026-10-09

2026-10-05

The free trial and a read-only account

An account that is on a free trial becomes read-only when the trial ends, and the operations that create a lookup or change something answer 402 for it. This version publishes that refusal: 16 operations now declare a 402 answer, with two codes and the body of each. Nothing that worked stops working. The one change at run time is on the credit ledger: kind=trial_lapse is now a value of the filter, and it was answered 422 before.

A read-only account

The free trial applies only to an account created on or after 6 October 2026 (UTC), and only while the service has it switched on; trial in GET /api/plans/me is null for an account that has none. Reading still works for a read-only account: lookups, batches, the catalog, exports of existing results and the settings of the account (Errors). Two codes are new, both with the status 402:

  • trial_ended: the trial of the account has ended. The body has details.trial_ended_at (when the trial ended, with its offset from UTC), details.trial_days (its length) and details.read_only (true). Do not retry it: the same call is refused again.
  • owner_trial_ended: the call would start work on a batch that belongs to another account, and the trial of that account has ended. The body has details.read_only and nothing about when, because the dates of a trial are told to its own account only. Do not retry it either.

The 16 operations that declare the 402 answer, by the codes they can carry:

Codes Operations
trial_ended decideLookup, resolveLookup, uploadBatch, validateBatch, createSku, syncSkus, updateSku, deleteSku, checkSkuCodes, acknowledgeAlert
trial_ended, out_of_credits classifyProduct, rerunLookup, classifySku
trial_ended, owner_trial_ended retryBatch, editBatchRow
trial_ended, owner_trial_ended, out_of_credits startBatch

The refusal is answered once the key and its role are accepted, and before the fields of the request are checked and before a record is looked up: a call with an unknown id or an invalid field on a read-only account is answered 402 too, not 404 or 422. The webhook operations declare no 402: they take the admin role, and an administrator account is not on a trial.

A key acts as the account that created it, so the trial that counts is that account's. Only an administrator can create a key and an administrator account is not on a trial, so a key does not normally receive trial_ended; it can once the account that created it is no longer an administrator. A key with the reviewer or admin role can receive owner_trial_ended when it starts, retries or edits a row of a batch that belongs to another account. A row of a running batch that was not processed because its owner's trial ended stores a message without the date: the owner reads its own date, other readers do not (Batches).

Other changes of the contract

  • GET /api/plans/me now has a schema, MyPlanOut; the answer had none. It holds plan, restricted, trial, read_only and entitlements. trial is null, or an object with days, started_at, ends_at and ended; read_only is true once the trial has ended. The example answer of 2026-10-04 shows neither trial nor read_only, so for a client built against that example they are two new fields, which a client that ignores fields it does not know is not affected by (Usage).
  • GET /api/usage/ledger and GET /api/usage/ledger/export take kind=trial_lapse. A ledger row of that kind takes off what was left of the sign-up credits after the trial ended, or earlier when the account was put on a plan other than the trial. An account has at most one, and its amount is negative, or zero when nothing was left (Usage).
  • The schemas MyPlanOut, PlanNameOut, TrialOut, TrialEnded and OwnerTrialEnded are new.

What to do

Every call that worked keeps working. If your client treats 402 as "out of credits", treat trial_ended and owner_trial_ended as a stop: send no more lookups and no more changes for that account, and do not retry or poll for it to change (Errors). Read GET /api/plans/me before you send work if you want to know in advance: read_only is true once the trial has ended. The paragraph at the end of the 2026-10-04 entry, which says that 402 is not declared per operation, no longer holds for 402: the 16 operations above declare it. 404 and 409 are still described on the pages and are not declared per operation.

  • Added: GET /api/plans/me: the answer now has a schema, MyPlanOut (it had none)
  • Added: GET /api/usage/ledger/export: query parameter kind: value trial_lapse
  • Added: GET /api/usage/ledger: query parameter kind: value trial_lapse
  • Added: 16 operations: status 402
  • Added: Schema MyPlanOut
  • Added: Schema OwnerTrialEnded
  • Added: Schema PlanNameOut
  • Added: Schema TrialEnded
  • Added: Schema TrialOut

Read the reference as of 2026-10-05

2026-10-04

Request limits

One operation is new: GET /api/limits (System) returns what a request may hold on the service you call: the largest upload file in megabytes (max_upload_mb), the largest size of an .xlsx file once unpacked (max_upload_unpacked_mb), the file extensions an upload may have (upload_extensions), the most columns and the longest cell of an upload file (max_upload_columns, max_upload_cell_chars), the most rows of a batch file (max_batch_rows), the longest product description (max_description_chars) and the most items of one POST /api/skus/bulk call (max_sku_bulk_items). Any role may call it, with an API key.

The default upload limit of the service is now 25 MB; it was 10 MB. The limit can be configured otherwise, so an integration reads it from GET /api/limits before it sends a file instead of assuming a number.

New answers of an upload

An upload (POST /api/batches) can now be refused in more ways (Batches):

  • 413 with the code payload_too_large, when the body of the request is larger than max_upload_mb plus 64 KiB. Such a file was answered 422 before. A file over the limit by less than that is still answered 422, so treat both 413 and 422 as "the file is too large". Do not retry a 413: the same file is refused again. Read max_upload_mb before you send, and split a larger file.
  • 429 with the code rate_limited, the header Retry-After: 10 and details.retry_after_seconds: 10, when the service is reading other files and your upload waited for room in vain, or the line of waiting uploads was full. The file was not read and no batch was created: wait the seconds in Retry-After and send the same upload again. An upload is held for up to 30 seconds before this answer, and for up to 90 seconds when the service is configured so: give it a request timeout above 90 seconds plus the time your connection needs to send the file. The places are also shared between callers, and a caller is an API key: one key holds one place at a time and may have two more uploads waiting, and one upload more from the same key is answered 429 at once, with the same body and Retry-After. Send the uploads of one key one after the other.
  • 415 with the code unsupported_media_type, when the Content-Type of the body is not multipart/form-data. It is answered before the body is read. It is a defect of the client: fix how the request is built, a form with the field file, and do not retry (Batches).
  • 408 with the code request_timeout, when the file takes too long to arrive: more than about 200 seconds in all at the default limit (the time the largest allowed body takes at 128 KiB per second, never under 60 seconds), or more than 30 seconds between two pieces of it. The answer has Connection: close, so a client that is still writing may see the connection closed instead. Nothing was read and no batch was created. Do not retry a 408 automatically, because the same file over the same connection is likely to be too slow again: a person or the calling program decides (a faster connection, a smaller file). Sending again is safe (Batches).
  • 401 with the code unauthenticated, before the body is read, when the request names no credential at all (no X-API-Key, no Authorization: Bearer ...). A key that is sent and not accepted is still answered 401, after the body has arrived and before any wait in line. A declared length over the limit is still answered 413 first (Batches).

An upload whose caller goes away while it waits in line is not read and not stored, so it creates no batch. The advice after a timeout or a connection error is unchanged: read GET /api/batches before you send the file again. The answer of an upload must be read within 60 seconds of its first byte; after that the service sends no more and closes the connection.

What the service reads of a file

These are changes of behaviour for a file that was accepted before or refused differently:

  • The text of all the cells of a file together is held to max_upload_mb, counted in the bytes it takes in UTF-8, with a quote, a backslash, a tab and a line break each counted twice. Over that, the answer is 422 with the detail File exceeds the 25 MB limit (the number in force). So an .xlsx file (compressed), a .csv file in a legacy encoding with accented text, or a file full of quotes and line breaks can be refused for its text while the file itself is under the limit. If that happens, split the file (Batches).
  • The column names of row 1 count once for every row after the header: their bytes together, multiplied by the number of rows, may not exceed max_upload_mb. Over that, the answer is 422 with the detail "The column names in row 1 are too long for a file of 2000 rows. Shorten them and send the file again." (English, with the number of rows of the file). At the defaults, 25 MB and 2000 rows, the names may take a little over 13,000 bytes in all. The limit is not a field of GET /api/limits. Shorten the names, or send fewer rows in each file (Batches).
  • The text of a cell is cleaned: every control character other than a tab and a line feed becomes a space, CR LF and a lone CR become a line feed, and the cell is trimmed. preview, the raw of a row and the exported file can differ from the bytes of the file in exactly that way (Batches).

What to do

Every operation, parameter and field that existed is unchanged, and every call that worked keeps working, except that a file whose text or column names are over the limits above is now refused, and that the text of a cell is cleaned as described. What you may have to do: if your client handled only 422 as a refusal of a file that is too large, handle 413 the same way; if it treated every 429 as a limit per minute, handle the 429 of an upload as described above, and send the uploads of one key one after the other; handle 408 and 415 of an upload as described above and in Errors. If your code refuses a file above 10 MB before uploading it, read max_upload_mb instead.

The OpenAPI document

The document declares, for uploadBatch, besides 200, 401, 403, 422 and 500, the answers 408, 413, 415 and 429, each with the Error body. Its error-code table lists request_timeout (408) and unsupported_media_type (415), and the description of max_upload_mb states how the text is counted. No other operation that existed changed. 402, 404 and 409 are still described on the pages and are not declared per operation (Errors).

  • Added: POST /api/batches: status 408
  • Added: POST /api/batches: status 413
  • Added: POST /api/batches: status 415
  • Added: POST /api/batches: status 429
  • Added: Operation GET /api/limits (getLimits): Request limits of this instance
  • Added: Schema LimitsOut

Read the reference as of 2026-10-04

2026-10-03

The history starts here

The first recorded version of the API, with three import markets (US, EU, VN): 55 operations for lookups, review, batches, the SKU catalog, tariff data, usage, webhooks, reports and system status. Every answer carries X-Request-ID and every error a code (Request identifiers, Errors). The history starts here; earlier changes were not recorded. One of them is described in Languages: the questions, the missing information and the legal findings of a lookup follow the language of the lookup, set with language on a classify request.

The history starts here: there is no earlier version to compare with.

Read the reference as of 2026-10-03