Fulfillment Manager API · writeOffs

Write off stock — damaged, expired or lost units leaving the platform

POST /write-offs

locationId is the site the units leave from (the organization's default location when absent): one inventory does not know is 404 LocationNotFound, an archived one 409 LocationArchived, and nothing is written off. For tracked SKUs writing off on-hand stock the units must be named exactly as a pick names them: serials free on the shelf at that site, or a lot with enough free units there (409 PickTrackingMismatch / UnitsNotOnShelf otherwise; expired units are claimable — leaving as a write-off is what expiry is for). disposition decides what happens physically: dispose (default) removes the units from inventory entirely; keep-damaged moves them to the damaged bucket (broken but kept). Either way the units leave the free shelf and registry, and accounting consumes their cost layers per the SKU's costing method and posts a write-down ledger entry — the loss is recognised when the damage is, so a later disposal of kept-damaged stock posts nothing. bucket: "damaged" is that later disposal: it empties units already in inventory's damaged bucket (damaged refund returns, earlier keep-damaged write-offs), skips shelf validation (those units are not on the free shelf), and posts no ledger entry. Inventory is commanded before the append (inventory.stock-disposed or inventory.stock-damaged, reference = the write-off id; 409 InsufficientStock when the bucket is short). Appends fulfillment.stock-written-off. writeOffId (a caller-minted wo_…) is required and is the idempotency key — a retried write-off is acknowledged with the original document, never applied twice.

Access

Requires stock:write.

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

Retries

writeOffId (a caller-minted wo_…) is required and is the idempotency key — a retried write-off is acknowledged with the original document, never applied twice.

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

• fulfillment.stock-written-off

What a fact is: Facts and the journal.

AI agent tool

Agents call this as fulfillment_write_off_stock (Fulfillment: Write off stock), in the parcels toolset. It is marked destructive, so the agent asks before running it.

Connecting an agent: AI agents.

Example

curl -X POST 'https://fulfillment.getmanifold.io/write-offs' \
  -H "Authorization: Bearer $MANIFOLD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "writeOffId": "wo_01a15ac0-d8b0-7441-80ce-f90a1b2c3d4e",
  "sku": "MUG-SPECKLE",
  "locationId": "loc_01a0f6b0-1100-7e51-8f62-7a8b9cadbec4",
  "quantity": 2,
  "reason": "damaged",
  "disposition": "dispose",
  "note": "Dropped during a stock count"
}'

const response = await fetch("https://fulfillment.getmanifold.io/write-offs", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.MANIFOLD_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "writeOffId": "wo_01a15ac0-d8b0-7441-80ce-f90a1b2c3d4e",
    "sku": "MUG-SPECKLE",
    "locationId": "loc_01a0f6b0-1100-7e51-8f62-7a8b9cadbec4",
    "quantity": 2,
    "reason": "damaged",
    "disposition": "dispose",
    "note": "Dropped during a stock count"
  }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const answer = await response.json();

{
  "writeOffId": "wo_01a15ac0-d8b0-7441-80ce-f90a1b2c3d4e",
  "sku": "MUG-SPECKLE",
  "locationId": "loc_01a0f6b0-1100-7e51-8f62-7a8b9cadbec4",
  "quantity": 2,
  "reason": "damaged",
  "disposition": "dispose",
  "note": "Dropped during a stock count"
}

{
  "id": "wo_01a15ac0-d8b0-7441-80ce-f90a1b2c3d4e",
  "sku": "MUG-SPECKLE",
  "locationId": "loc_01a0f6b0-1100-7e51-8f62-7a8b9cadbec4",
  "quantity": 2,
  "reason": "damaged",
  "disposition": "dispose",
  "bucket": "onHand",
  "note": "Dropped during a stock count",
  "occurredAt": "2026-10-20T08:20:41.556Z"
}

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

402

403

404

409

502

503

How refusals work everywhere: Errors.