Record inventory movement

Send a whole-unit quantity compatible with the movement type. Only adjustment accepts a negative quantity; the other types need a positive one (otherwise 400). The Variant must have inventoryAuthority: "marketapi".

In which warehouseCopy Anchor Link

warehouseId picks the warehouse. Without it, the movement goes to the seller's default warehouse. The warehouse must belong to the same seller as the Variant.

curl -X POST "$BACKEND_URL/v1/sellers/$SELLER_ID/inventory-movements" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"type":"adjustment","variantId":"'$VARIANT_ID'","warehouseId":"'$WAREHOUSE_ID'","quantity":10,"reason":"Initial count"}'

Transfer between warehousesCopy Anchor Link

With type: "transfer", warehouseId is the source and toWarehouseId is the destination. The quantity is positive and the two warehouses must differ.

curl -X POST "$BACKEND_URL/v1/sellers/$SELLER_ID/inventory-movements" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"type":"transfer","variantId":"'$VARIANT_ID'","warehouseId":"'$FROM_ID'","toWarehouseId":"'$TO_ID'","quantity":4,"reason":"Branch restock"}'

A transfer writes two rows in the ledger, with the same transferId: an outbound (-4) at the source and an inbound (+4) at the destination. Everything happens or nothing does. The Variant total does not change, so it does not publish quantity by itself, not even with the automatic policy. Whoever sends publishTargets still gets the job.

What comes backCopy Anchor Link

• movements: the list of movements written. It has 1 item, or 2 for a transfer (the outbound first, then the inbound).
• balance: the Variant balance after the command, with the totals and the warehouses list. No need to read the balance again.
• publicationJobId: the publication job, when there was an eligible target.

publishTargets is optional: select Listings, bindings, or Connections in this same call, without a mandatory second request.

The inventory.movement_created webhook is sent once per ledger row. Each event carries the movement (with warehouseId and transferId) and the same full balance. The two events of a transfer carry the same balance.

Common errorsCopy Anchor Link

• 400: a quantity with the wrong sign for the type; toWarehouseId missing on a transfer, or sent on another type; toWarehouseId equal to warehouseId.
• 404: the seller, the Variant or a warehouse does not exist. A warehouse of another seller or another account returns 404.
• 409 with details.reason = "warehouse_archived": the warehouse is archived and takes no movement. details.warehouseId says which one. Reactivate it first.
• 409 with details.reason = "inventory_underflow": the movement would leave the warehouse without enough stock. details.warehouseId is the warehouse that went short (for a transfer, the source). Nothing is written and no event is sent. A Variant with allowBackorder may go negative.
• 409 with details.reason = "inventory_authority": the Variant is not managed by MarketAPI.