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.
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_version2026-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/datasetslists twoJPdatasets of the same version, both active, namedJapan (Tariff Schedule) - EnglishandJapan (Tariff Schedule) - Japanese. A new field of the dataset,language(enorja), says which edition it holds; it isenfor every other dataset (Tariff data). JPis accepted wherevermarketis: 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,000when the subheading is not split.national_digitsof the dataset is 9. GET /api/healthhas a new key,background.jp_tariff, with the values ofvn_tariff(System).- The duty estimate for
JPis in yen (currencyisJPY), in whole yen. The answer ofestimateDutyhas 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(alwaystrue) andsource_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 ofgeneral,temporary,wto,gsp,ldcorepa:<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_minandlanded_cost_max; - consumption tax on imports is not included.
The tariff language, tariff_language
- An optional field,
enorja,enwhen it is not sent. OnlyJPoffersja: Japan Customs publishes the schedule in an official English edition and an official Japanese edition, andjashows the Japanese edition. It is not a translation, and it is chosen by this field, never byAccept-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-estimateandPOST /api/skus/bulk, and as a query parameter ofGET /api/hts/search,GET /api/hts/tree,GET /api/datasets/{dataset_id}/entriesandPOST /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_languagesof a dataset lists what its market offers:["en", "ja"]forJP,["en"]for the other markets.tariff_languagepicks the dataset a call reads. Withja, thedatasetof an answer (the search, the tree, the duty estimate,result.datasetof a lookup) is the Japanese dataset, with its ownidand name, and a lookup or a batch run injakeeps that dataset.GET /api/datasets/{dataset_id}/entriesreads the dataset's own edition whentariff_languageis 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
404with the codenot_found; it is never answered from the other edition. A language the market does not offer is checked first and stays a422(Errors). - A value the market does not offer is refused with
422and the codevalidation_error(Errors). A value other thanenorjais refused with the same status. POST /api/skus/bulkdiffers from every other operation. A bulk call can mix markets, so itstariff_languageapplies to the items whose market offers it, and the other items are classified inen: it is not refused for a market. It matters only withclassify_missing.
What to do
Nothing, for an integration that uses
US,EUorVN.Do not hard-code three markets: a list of markets can now hold
JP.Read
tariff_languagesfromGET /api/datasetsbefore you offer Japanese text for a market.If you pick a dataset from
GET /api/datasetsby market and version, expect two forJPand choose bylanguage.Handle yen as whole numbers:
JPYhas no decimals.Ignore the fields you do not know.
Added:
GET /api/datasets/{dataset_id}/entries: query parametertariff_language(string or null)Added:
GET /api/hts/search: query parametertariff_language(string or null)Added:
GET /api/hts/tree: query parametertariff_language(string or null)Added:
POST /api/skus/{sku_id}/classify: query parametertariff_language(string or null)Added: Schema
BatchOut: fieldtariff_language(string)Added: Schema
BatchStartRequest: fieldtariff_language(string or null)Added: Schema
BulkRequest: fieldtariff_language(string or null)Added: Schema
ClassifyRequest: fieldtariff_language(string or null)Added: Schema
DatasetOut: fieldlanguage(string)Added: Schema
DatasetOut: fieldtariff_languages(string[])Added: Schema
DutyRequest: fieldtariff_language(string or null)Added: Schema
LookupDetail: fieldtariff_language(string)Added: Schema
LookupSummary: fieldtariff_language(string)Added: Schema
RerunRequest: fieldtariff_language(string or null)
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_alertscounts 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/eventsis open to every key, whatever its role. It needed theadminrole.- 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, elsenull. It is in the rows ofGET /api/usage/ledgerand intransactionsofGET /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 (
entryacts as a member), capped at the role its creator holds in that workspace now, and never aboveadmin. The role of the creator's account on the service plays no part (Authentication). - Keys and webhooks are managed by the
adminandownerof the workspace, and a key with theadminrole sees and changes the webhooks of its own workspace only. A webhook of another workspace answers404. - Creating a webhook and changing its
urlneed a person signed in to the application. A key is answered403with the codesession_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.
creditsofGET /api/usage/meandGET /api/auth/meis that balance, andnullwhen the caller's lookups in that workspace are free. GET /api/plans/meis 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 answered402withtrial_ended.GET /api/usage/ledgerlists the rows of the workspace for itsadminandowner, and one's own rows for anyone else. Auser_idthat does not name a member of the workspace answers404. A ledger row hasorganisation_id, the workspace whose balance it changed.GET /api/auth/mehas two more fields:workspace(id,nameandrole) andworkspace_role, the role the request acts with there.roleis 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) andworkspace_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
creditsas a number ornull, 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,workspaceandworkspace_roleare added to existing answers.
No difference in the specification.
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 hasdetails.trial_ended_at(when the trial ended, with its offset from UTC),details.trial_days(its length) anddetails.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 hasdetails.read_onlyand 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/menow has a schema,MyPlanOut; the answer had none. It holdsplan,restricted,trial,read_onlyandentitlements.trialisnull, or an object withdays,started_at,ends_atandended;read_onlyistrueonce the trial has ended. The example answer of2026-10-04shows neithertrialnorread_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/ledgerandGET /api/usage/ledger/exporttakekind=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 itsamountis negative, or zero when nothing was left (Usage).- The schemas
MyPlanOut,PlanNameOut,TrialOut,TrialEndedandOwnerTrialEndedare 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 parameterkind: valuetrial_lapse - Added:
GET /api/usage/ledger: query parameterkind: valuetrial_lapse - Added: 16 operations: status
402 - Added: Schema
MyPlanOut - Added: Schema
OwnerTrialEnded - Added: Schema
PlanNameOut - Added: Schema
TrialEnded - Added: Schema
TrialOut
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):
413with the codepayload_too_large, when the body of the request is larger thanmax_upload_mbplus 64 KiB. Such a file was answered422before. A file over the limit by less than that is still answered422, so treat both413and422as "the file is too large". Do not retry a413: the same file is refused again. Readmax_upload_mbbefore you send, and split a larger file.429with the coderate_limited, the headerRetry-After: 10anddetails.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 inRetry-Afterand 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 answered429at once, with the same body andRetry-After. Send the uploads of one key one after the other.415with the codeunsupported_media_type, when theContent-Typeof the body is notmultipart/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 fieldfile, and do not retry (Batches).408with the coderequest_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 hasConnection: 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 a408automatically, 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).401with the codeunauthenticated, before the body is read, when the request names no credential at all (noX-API-Key, noAuthorization: Bearer ...). A key that is sent and not accepted is still answered401, after the body has arrived and before any wait in line. A declared length over the limit is still answered413first (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 is422with thedetailFile exceeds the 25 MB limit(the number in force). So an.xlsxfile (compressed), a.csvfile 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 is422with thedetail"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 ofGET /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 LFand a loneCRbecome a line feed, and the cell is trimmed.preview, therawof 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: status408 - Added:
POST /api/batches: status413 - Added:
POST /api/batches: status415 - Added:
POST /api/batches: status429 - Added: Operation
GET /api/limits(getLimits): Request limits of this instance - Added: Schema
LimitsOut
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.