Merchant Trades

The trades object holds three lists. They are asked separately and they stack: an offer survives only if none of the three gates it.

"trades": {
  "offers": [
    {
      "merchant": "minecraft:librarian",
      "level": 2,
      "gives": "minecraft:bookshelf",
      "takes": ["minecraft:emerald"]
    }
  ],
  "professions": [
    "minecraft:weaponsmith",
    { "id": "minecraft:librarian", "levels": [4, 5] }
  ],
  "levels": [5]
}

In the editor

The Trades tab. Its picker lists real offers rather than every item in the game — pick a profession and you see what that merchant actually trades, at which level, for what price. Most of this block is written by clicking.

Professions sit on the same tab. The pack-wide level gate is a right-click on a profession entry and then Merchant Levels.

offers — one named trade

Field	Meaning
merchant	The profession id, or the entity id for a merchant with no profession (minecraft:wandering_trader, or a merchant from another mod).
level	The merchant level the offer belongs to. Defaults to 1.
gives	What the player receives.
takes	One or both price items.
nbt	Optional criterion, narrowing it the same way it does on an item entry.

Amounts are deliberately not part of an offer

A merchant rolls its own price and stack size, so an entry naming them would gate the same trade on one villager and miss it on the next.

The editor's trade picker lists real offers rather than every item in the game, so most of the time this block is written by clicking rather than by hand.

professions — a whole merchant

A bare id gates that profession at every level:

"professions": ["minecraft:weaponsmith"]

The object form gates only the levels listed — {"id": "minecraft:librarian", "levels": [4, 5]} leaves novice, apprentice and journeyman librarians trading normally.

levels here lists the gated ones, not the free ones

That is the opposite of unlock_actions, and it is deliberate. The levels list at the top of trades already means "these levels are gated", and one word meaning two opposite things inside one block is a trap for whoever edits the file by hand.

levels — one rank, every profession

A merchant level gated for every profession at once. This is the rule behind "until the Bronze Age there are only novices", which would be tedious to repeat profession by profession.

"levels": [4, 5]

Written as numbers; strings are accepted on the way in.

A wandering trader always counts as level 1, so gating level 1 hides every wandering trader as well.

Gating an item everywhere it is traded

That is a different question and is not written here. Use the trade action on an ordinary items entry — it gates buying or selling that item at any merchant, wherever it turns up.

The three tools, side by side:

Goal	Where it goes
One specific trade	trades → offers
A merchant, or a rank of merchant	trades → professions / levels
This item is not traded by anybody	the trade action on an items entry

What the player sees

A merchant whose offers are all gated opens with a notice in the trade window rather than an empty list — without it, an emptied merchant is indistinguishable from one that happens to have no stock, which reads as a bug.

Whether that notice names the stages holding the offers back is showStagesInWindow under [trade_lock], off by default. That is the opposite default from the dimension and mob messages, on purpose: those answer "why can I not go there", where naming the stage is the whole help. A merchant with nothing to offer is a puzzle some packs would rather keep as one.

The message itself is tradeLocked under [lock_messages].

Global or individual

All three lists work in both scopes — a trade window always has a player standing in front of it.

See also

• Entities & Spawns — interactionlock with the trade action stops a player interacting with the villager at all, which is a blunter instrument than gating its offers.
• Complete Examples