Move a line's held stock to another site

POST /orders/{orderId}/lines/{lineId}/allocation

Move a line's held stock to another site: the hold is released where it was, taken at toLocationId, and the pending parcel moves with it (joining the parcel already open at that site, or opening one).

Allocation is decided once and stands until someone moves it, and this is that move — the way a merchant overrules routing, or ships from the warehouse that actually has the room. fromLocationId defaults to the site holding most of the line and quantity to everything it holds. 409 AllocationNotMovable when no parcel on the shelf holds the line, when the named site holds less than asked, or when the parcel is already picked — units off the shelf move physically, not by decision. Appends fulfillment.allocation-moved. Idempotent on reference: the release and the reserve carry it, so a retry moves nothing twice and is acknowledged.

Access

Requires orders:write.

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

Retries

Idempotent on reference: the release and the reserve carry it, so a retry moves nothing twice and is acknowledged.

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

Why every write carries a key: Idempotency and retries.

Facts appended

fulfillment.allocation-moved

What a fact is: Facts and the journal.

AI agent tool

Agents call this as fulfillment_move_allocation (Fulfillment: Move allocation), in the parcels toolset.

Connecting an agent: AI agents.

Example

curl

curl -X POST 'https://fulfillment.getmanifold.io/orders/ord_01a156d4-8704-7a21-8b32-4c5d6e7f8091/lines/lin_01a156d4-8704-7a21-8b32-7f8091021324/allocation' \
  -H "Authorization: Bearer $MANIFOLD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "toLocationId": "loc_01a0f6b0-1100-7e51-8f62-8b9cadbecfd5",
  "reference": "PO-7781-bowls-shopfront",
  "reason": "The shopfront has the bowls boxed"
}'

JavaScript (fetch)

const response = await fetch("https://fulfillment.getmanifold.io/orders/ord_01a156d4-8704-7a21-8b32-4c5d6e7f8091/lines/lin_01a156d4-8704-7a21-8b32-7f8091021324/allocation", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.MANIFOLD_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "toLocationId": "loc_01a0f6b0-1100-7e51-8f62-8b9cadbecfd5",
    "reference": "PO-7781-bowls-shopfront",
    "reason": "The shopfront has the bowls boxed"
  }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const answer = await response.json();

Request body · application/json

{
  "toLocationId": "loc_01a0f6b0-1100-7e51-8f62-8b9cadbecfd5",
  "reference": "PO-7781-bowls-shopfront",
  "reason": "The shopfront has the bowls boxed"
}

Response · 200 · application/json

{
  "id": "ord_01a156d4-8704-7a21-8b32-4c5d6e7f8091",
  "reference": "PO-7781",
  "source": {
    "kind": "api"
  },
  "customer": {
    "companyId": "cmp_01a1588a-1f02-7a3b-8c4d-5e6f7a8b9c0d",
    "shippingAddressId": "cloc_01a1588a-1f02-7a3b-8c4d-6f7a8b9c0d1e",
    "billingAddressId": "cloc_01a1588a-1f02-7a3b-8c4d-6f7a8b9c0d1e"
  },
  "party": {
    "companyId": "cmp_01a1588a-1f02-7a3b-8c4d-5e6f7a8b9c0d",
    "name": "Harbour Ceramics Pty Ltd",
    "paymentTermsDays": 30,
    "shipTo": {
      "id": "cloc_01a1588a-1f02-7a3b-8c4d-6f7a8b9c0d1e",
      "label": "Fremantle warehouse",
      "address": {
        "firstName": "Receiving",
        "lastName": "Dock",
        "company": "Harbour Ceramics",
        "address1": "14 Kiln Street",
        "city": "Fremantle",
        "province": "Western Australia",
        "provinceCode": "WA",
        "country": "Australia",
        "countryCode": "AU",
        "zip": "6160"
      }
    },
    "billTo": {
      "id": "cloc_01a1588a-1f02-7a3b-8c4d-6f7a8b9c0d1e",
      "label": "Fremantle warehouse",
      "address": {
        "company": "Harbour Ceramics Pty Ltd",
        "address1": "PO Box 412",
        "city": "Fremantle",
        "provinceCode": "WA",
        "countryCode": "AU",
        "zip": "6959"
      }
    }
  },
  "catalogIds": [
    "cat_01a15880-2a10-7b2c-8d3e-4f5a6b7c8d9e"
  ],
  "currency": "AUD",
  "fx": {
    "currency": "AUD",
    "home": "AUD",
    "rate": 1,
    "rateDate": "2026-10-20",
    "source": "same"
  },
  "convention": "exclusive",
  "shippingTaxBasis": {
    "_tag": "calculated",
    "treatment": "domestic",
    "country": "AU",
    "class": "follows-goods",
    "rateBps": 1000
  },
  "shippingMethod": {
    "title": "Standard",
    "code": "STD"
  },
  "number": "SO-01042",
  "serial": 1042,
  "status": "partially-shipped",
  "lines": [
    {
      "id": "lin_01a156d4-8704-7a21-8b32-5d6e7f809102",
      "sku": "MUG-SPECKLE",
      "name": "Speckled stoneware mug",
      "ordered": 4,
      "removed": false,
      "catalogId": "cat_01a15880-2a10-7b2c-8d3e-4f5a6b7c8d9e",
      "discountCents": 0,
      "allocated": 4,
      "picked": 4,
      "packed": 4,
      "dispatched": 4,
      "invoiced": 0,
      "returned": 0,
      "unitPriceCents": 2400,
      "listPriceCents": 2400,
      "inclusive": false,
      "taxBasis": {
        "_tag": "calculated",
        "treatment": "domestic",
        "country": "AU",
        "parts": [
          {
            "class": "standard",
            "rateBps": 1000,
            "weight": 1
          }
        ]
      },
      "orderDiscountCents": 0,
      "tax": {
        "inclusive": false,
        "amountCents": 9600,
        "entries": [
          {
            "class": "standard",
            "treatment": "domestic",
            "country": "AU",
            "rateBps": 1000,
            "netCents": 9600,
            "taxCents": 960,
            "source": "manifold"
          }
        ],
        "netCents": 9600,
        "taxCents": 960,
        "grossCents": 10560
      }
    },
    {
      "id": "lin_01a156d4-8704-7a21-8b32-7f8091021324",
      "sku": "BOWL-SALT-L",
      "name": "Salt-glaze serving bowl, large",
      "ordered": 2,
      "removed": false,
      "catalogId": "cat_01a15880-2a10-7b2c-8d3e-4f5a6b7c8d9e",
      "discountCents": 0,
      "allocated": 2,
      "picked": 0,
      "packed": 0,
      "dispatched": 0,
      "invoiced": 0,
      "returned": 0,
      "unitPriceCents": 3800,
      "listPriceCents": 3800,
      "inclusive": false,
      "taxBasis": {
        "_tag": "calculated",
        "treatment": "domestic",
        "country": "AU",
        "parts": [
          {
            "class": "standard",
            "rateBps": 1000,
            "weight": 1
          }
        ]
      },
      "orderDiscountCents": 0,
      "tax": {
        "inclusive": false,
        "amountCents": 7600,
        "entries": [
          {
            "class": "standard",
            "treatment": "domestic",
            "country": "AU",
            "rateBps": 1000,
            "netCents": 7600,
            "taxCents": 760,
            "source": "manifold"
          }
        ],
        "netCents": 7600,
        "taxCents": 760,
        "grossCents": 8360
      }
    }
  ],
  "workflow": {
    "paymentTerms": "on-account",
    "pick": "manual",
    "pack": "manual",
    "ship": "manual",
    "invoice": "manual",
    "shortfall": "wait",
    "allocation": "single-site-preferred",
    "routing": {
      "order": "rank",
      "decider": "manifold",
      "priority": []
    },
    "routingByCatalog": {}
  },
  "paymentTermsBy": "customer",
  "createdSequence": 4096,
  "shipments": [
    {
      "id": "shp_01a156d4-8704-7a21-8b32-8091021324a5",
      "number": "SH-01057",
      "reference": "auto:ord_01a156d4-8704-7a21-8b32-4c5d6e7f8091:1",
      "status": "shipped",
      "locationId": "loc_01a0f6b0-1100-7e51-8f62-7a8b9cadbec4",
      "lines": [
        {
          "lineId": "lin_01a156d4-8704-7a21-8b32-5d6e7f809102",
          "sku": "MUG-SPECKLE",
          "quantity": 4,
          "dispatchId": "dsp_01a1588b-1a20-7b31-9c42-6e7f80910213"
        }
      ],
      "cartons": [
        {
          "packaging": "carton",
          "weightGrams": 2150,
          "size": {
            "lengthMm": 300,
            "widthMm": 250,
            "heightMm": 150
          }
        }
      ],
      "carrier": "Australia Post",
      "service": "Parcel Post",
      "trackingNumber": "33XYZ0012345",
      "trackingUrl": "https://auspost.com.au/mypost/track/details/33XYZ0012345",
      "createdAt": "2026-10-20T01:02:11.204Z",
      "updatedAt": "2026-10-20T03:12:40.000Z"
    },
    {
      "id": "shp_01a1588b-2b30-7c41-8d52-91021324a5b6",
      "number": "SH-01058",
      "reference": "PO-7781-bowls",
      "status": "cancelled",
      "locationId": "loc_01a0f6b0-1100-7e51-8f62-7a8b9cadbec4",
      "lines": [],
      "cartons": [],
      "createdAt": "2026-10-20T03:31:09.402Z",
      "updatedAt": "2026-10-20T03:33:51.660Z"
    },
    {
      "id": "shp_01a1588b-2b30-7c41-8d52-021324a5b6c7",
      "number": "SH-01059",
      "reference": "moved:PO-7781-bowls-shopfront",
      "status": "pending",
      "locationId": "loc_01a0f6b0-1100-7e51-8f62-8b9cadbecfd5",
      "lines": [
        {
          "lineId": "lin_01a156d4-8704-7a21-8b32-7f8091021324",
          "sku": "BOWL-SALT-L",
          "quantity": 2
        }
      ],
      "cartons": [],
      "createdAt": "2026-10-20T03:33:51.660Z",
      "updatedAt": "2026-10-20T03:33:51.660Z"
    }
  ],
  "invoices": [],
  "refunds": [],
  "payments": [],
  "notes": [],
  "edits": [],
  "consignments": [],
  "money": {
    "subtotalCents": 17200,
    "charges": {
      "shippingCents": 0,
      "shippingDiscountCents": 0,
      "discountCents": 0
    },
    "discountCents": 0,
    "tax": {
      "netCents": 17200,
      "taxCents": 1720,
      "grossCents": 18920,
      "breakdown": [
        {
          "class": "standard",
          "treatment": "domestic",
          "country": "AU",
          "rateBps": 1000,
          "exempt": false,
          "taxableCents": 17200,
          "taxCents": 1720
        }
      ]
    },
    "totalCents": 18920,
    "paidCents": 0,
    "refundedCents": 0,
    "balanceCents": 18920,
    "refundOwedCents": 0,
    "status": "unpaid"
  },
  "discounts": [],
  "shortfalls": [],
  "createdAt": "2026-10-20T01:02:11.204Z",
  "updatedAt": "2026-10-20T03:33:51.660Z"
}

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: fulfillment-manager.openapi.json. Base URL https://fulfillment.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
`FulfillmentOrderNotFound` orderId	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
`UnknownOrderLine` orderId, lineId	A line named is not on the order or the parcel.	Use the `lin_` ids from the order.
`AllocationNotMovable` orderId, lineId, reason	The held stock cannot move as asked. `reason` says why.	Move a line still on the shelf, to a site that holds enough.
`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.

`502`

Refusal	What it means	What to do
`InventoryUnavailable` reason	The inventory service did not answer, so nothing changed.	Send the same request again, with the same key.

`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 15: Move the hold to the other site