Variant inventory

Inventory always belongs to a Variant, never a Product. Choose authority per Variant: marketapi owns the ledger and balance; managed_externally leaves the ERP authoritative; derived calculates kits from the BOM; disabled manages no quantity.

Within the Variant, the balance is per warehouse: each Variant has one balance line per warehouse of the seller, and the Variant balance is their sum.

How the balance is computed and reaches the marketplace, with diagrams: Catalog and inventory.

A marketapi movement writes the ledger and can create a publication Job for selected targets in the same intent. With automatic inventory opt-in, only eligible bindings receive quantity; title, price, and media are never republished.

Warehouses and transferCopy Anchor Link

Every seller starts with a default warehouse. Create others in Create warehouse if it keeps stock in more than one place.

• A movement changes one warehouse. warehouseId picks which. Without it, it is the default one.
• Transfer (type: "transfer"): takes from the source warehouse (warehouseId) and puts into the destination (toWarehouseId), with a positive quantity. It writes two ledger rows with the same transferId. The Variant total does not change, so a transfer does not publish quantity by itself.
• Warehouse of another seller: 404. Archived warehouse: 409 with details.reason = "warehouse_archived".
• Not enough stock in the warehouse: 409 with details.reason = "inventory_underflow", and nothing is written.

How balances are computedCopy Anchor Link

For a managed Variant, available = onHand - reserved, in each warehouse. A reservation lowers available without taking the physical unit out of stock; a confirmed sale lowers both. Reservation, release and sale are per warehouse too: take stock out of the same warehouse where you reserved it.

The API does not accept a negative balance: the movement returns 409 (inventory_underflow) with the warehouseId of the warehouse that went short. Only a Variant that allows backorder may go negative.

A derived kit has no movement of its own. The kit is calculated per warehouse: in each one, it is the smallest whole quotient of the components that are there, and the warehouses are summed. A kit is not assembled from parts that sit in two places.

If a kit uses two cables and one charger, with 10 cables and 3 chargers in the same warehouse, the kit balance is 3. If the 3 chargers are in another warehouse, with no cables, the kit is worth 0 in both. Check the BOM to explain that number; recording a movement on the components recalculates it on the next read.

Current supportCopy Anchor Link

Use the complete marketplace matrix to compare product support. The Connection capability still decides whether publication can be queued for that account.

Publish inventory

• MockDevelopment only
• Mercado LivreNot supported
• MagaluPlanned
• AmazonPlanned
• TikTok ShopPlanned
• ShopeePlanned