Open a transfer between two of the organization's own locations

POST /transfers

What this does depends on the organization's transfer policy (see GET /settings). Under two-step it opens the document and moves nothing until despatch, appending inventory.transfer-created. Under instant the entire move happens here in one commit with no in-transit state — appending inventory.transfer-completed, a single fact, because an instant transfer never was in transit and recording a despatch followed by a receipt would describe a moment that did not happen. Under unrestricted the caller picks with mode; asking for a shape the policy forbids is 409 TransferModeNotAllowed rather than being quietly corrected, and 409 TransfersDisabled when the policy is off. An instant transfer checks free stock at the source up front (409 InsufficientStock), because it is moving it now. A transfer into a non-fulfillable site is entirely normal: that is how stock reaches a quarantine bay. reference is required and is the idempotency key: a retry with the same reference is acknowledged with the transfer it already opened — under instant, the units move once.

Access

Requires stock:write.

How scopes come from roles: Scopes and roles. Getting a token: Authentication and app tokens.

Retries

reference is required and is the idempotency key: a retry with the same reference is acknowledged with the transfer it already opened — under instant, the units move once.

A retry with the same key answers 201, with what the first call recorded.

Why every write carries a key: Idempotency and retries.

Facts appended

inventory.transfer-created
inventory.transfer-completed

What a fact is: Facts and the journal.

AI agent tool

Agents call this as inventory_create_transfer (Inventory: Create transfer), in the stock toolset.

Connecting an agent: AI agents.

Example

Open a two-step transfer of six blue widgets from Main to the shopfront.

curl

curl -X POST 'https://inventory.getmanifold.io/transfers' \
  -H "Authorization: Bearer $MANIFOLD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "fromLocationId": "loc_019cadd3-8330-7e12-aa44-2cd5f05da74a",
  "toLocationId": "loc_019cd06e-3b38-7e92-b496-c92f8184a3aa",
  "mode": "two-step",
  "reference": "restock-shopfront-2026-10-21",
  "lines": [
    {
      "sku": "WIDGET-BLUE",
      "quantity": 6
    }
  ]
}'

JavaScript (fetch)

const response = await fetch("https://inventory.getmanifold.io/transfers", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.MANIFOLD_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "fromLocationId": "loc_019cadd3-8330-7e12-aa44-2cd5f05da74a",
    "toLocationId": "loc_019cd06e-3b38-7e92-b496-c92f8184a3aa",
    "mode": "two-step",
    "reference": "restock-shopfront-2026-10-21",
    "lines": [
      {
        "sku": "WIDGET-BLUE",
        "quantity": 6
      }
    ]
  }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const answer = await response.json();

Request body · application/json

{
  "fromLocationId": "loc_019cadd3-8330-7e12-aa44-2cd5f05da74a",
  "toLocationId": "loc_019cd06e-3b38-7e92-b496-c92f8184a3aa",
  "mode": "two-step",
  "reference": "restock-shopfront-2026-10-21",
  "lines": [
    {
      "sku": "WIDGET-BLUE",
      "quantity": 6
    }
  ]
}

Response · 201 · application/json

{
  "id": "trf_01a15bd0-1918-7e9f-bf21-92e337bede18",
  "number": "TR-00042",
  "fromLocationId": "loc_019cadd3-8330-7e12-aa44-2cd5f05da74a",
  "toLocationId": "loc_019cd06e-3b38-7e92-b496-c92f8184a3aa",
  "status": "draft",
  "mode": "two-step",
  "lines": [
    {
      "sku": "WIDGET-BLUE",
      "quantity": 6,
      "despatched": 0,
      "received": 0
    }
  ],
  "reference": "restock-shopfront-2026-10-21",
  "createdAt": "2026-10-21T00:15:27.000Z",
  "updatedAt": "2026-10-21T00:15:27.000Z"
}

The panel writes this call in other languages. It does not send it: Manifold's APIs do not take calls from a web page on another site, so run the call from your own code or terminal. The whole API as OpenAPI: inventory-manager.openapi.json. Base URL https://inventory.getmanifold.io.

Errors

Every refusal is a status and a JSON body whose _tag names it. A refused call changes nothing.

`401`

Refusal	What it means	What to do
`Unauthorized` reason	The token is missing, expired or not one Manifold issued.	Get a fresh token and send the call again.
`TokenAlreadyUsed` tokenId	A single-use app token was already spent.	Mint a new token for this call.

`402`

Refusal	What it means	What to do
`SubscriptionRequired` status	The organization's subscription has lapsed, so writes are refused.	An owner settles billing. Reads still work meanwhile.

`403`

Refusal	What it means	What to do
`TenantRequired` userId	The token names no organization.	Choose the organization, then get a new token.
`ScopeRequired` required	The token's roles do not grant the scope this call needs.	Ask an owner or admin for a role that grants it.

`404`

Refusal	What it means	What to do
`LocationNotFound` locationId	No such record in this organization.	Check the id in the path or the body.
`ItemNotFound` sku	No such record in this organization.	Check the id in the path or the body.

`409`

Refusal	What it means	What to do
`LocationArchived` locationId	The location is archived, and an archived location takes no changes or stock.	Use an active location.
`TransfersDisabled`	Transfers are turned off for this organization.	An owner or admin turns them on in Settings.
`TransferModeNotAllowed` mode, policy	The organization's transfer policy does not allow this kind of transfer.	Use the mode `policy` allows.
`InsufficientStock` sku, available, requested, locationId	Fewer units are free than the call needs. `available` and `requested` say how many.	Receive or move stock in first, or ask for fewer.
`MirroredFromSource` source	This area is fed by your source system until the organization goes live.	Make the change in the source system, or go live first.

`503`

Refusal	What it means	What to do
`RequestLogUnavailable` tokenId, reason	The service could not record the request, so it did nothing.	Send the same request again, with the same key.

How refusals work everywhere: Errors.

Used in

Running more than one location, step 4: Move ten units into it
Running more than one location, step 12: Move stock with no van involved