Journal an additional cost on the order by hand

POST /orders/{orderId}/costs

Journal an additional cost on the order by hand: an amount, a reason and the chart account it is charged to (accountCode), for the order or one line (lineId; 404 OrderLineNotFound).

409 AccountNotPostable for an account not in the chart, archived or kept by the ledger; 409 CostCurrencyRefused for a currency other than the order's or the home one; 409 OrderNotOpen on a quote or a cancelled order. Posts the account against 2160 accrued costs. Appends fulfillment.cost-recorded. costId (a caller-minted cost_…) is required and is the idempotency key: a retry with the same id is acknowledged and appends nothing.

Access

Requires financials:write.

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

Retries

costId (a caller-minted cost_…) is required and is the idempotency key: a retry with the same id is acknowledged and appends nothing.

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.cost-recorded

What a fact is: Facts and the journal.

AI agent tool

Agents call this as fulfillment_record_order_cost (Fulfillment: Record order cost), in the costs toolset.

Connecting an agent: AI agents.

Example

From Journal an additional cost on an order, step 8: Journal the redelivery.

curl

curl -X POST 'https://fulfillment.getmanifold.io/orders/ord_01a15ad0-c1a0-7b2c-8d3e-4f5a6b7c8d9e/costs' \
  -H "Authorization: Bearer $MANIFOLD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "costId": "cost_01a15ad0-e9c0-7551-91df-0a1b2c3d4e5f",
  "amountCents": 4500,
  "reason": "Courier to redeliver after a failed first attempt",
  "accountCode": "6300"
}'

JavaScript (fetch)

const response = await fetch("https://fulfillment.getmanifold.io/orders/ord_01a15ad0-c1a0-7b2c-8d3e-4f5a6b7c8d9e/costs", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.MANIFOLD_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "costId": "cost_01a15ad0-e9c0-7551-91df-0a1b2c3d4e5f",
    "amountCents": 4500,
    "reason": "Courier to redeliver after a failed first attempt",
    "accountCode": "6300"
  }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const answer = await response.json();

Request body · application/json

{
  "costId": "cost_01a15ad0-e9c0-7551-91df-0a1b2c3d4e5f",
  "amountCents": 4500,
  "reason": "Courier to redeliver after a failed first attempt",
  "accountCode": "6300"
}

Response · 201 · application/json

{
  "id": "ord_01a15ad0-c1a0-7b2c-8d3e-4f5a6b7c8d9e",
  "reference": "WEB-20417",
  "source": {
    "kind": "api"
  },
  "salesRepId": "usr_01a15ad0-a1b2-7c3d-8e4f-5a6b7c8d9e01",
  "commission": {
    "earnedOn": "invoiced",
    "earner": "order-rep",
    "earnedBy": {
      "userId": "usr_01a15ad0-a1b2-7c3d-8e4f-5a6b7c8d9e01",
      "groupId": "cgr_00000000-0000-0000-0000-000000000000",
      "groupName": "default",
      "baseRateBps": 0
    }
  },
  "customer": {
    "personId": "psn_01a15ad0-c0f9-7a1b-8c2d-3e4f5a6b7c8d"
  },
  "party": {
    "personId": "psn_01a15ad0-c0f9-7a1b-8c2d-3e4f5a6b7c8d"
  },
  "catalogIds": [
    "cat_01a15ad0-a2c3-7d4e-8f5a-6b7c8d9e0f12"
  ],
  "currency": "AUD",
  "fx": {
    "currency": "AUD",
    "home": "AUD",
    "rate": 1,
    "rateDate": "2026-10-21",
    "source": "same"
  },
  "convention": "inclusive",
  "shippingTaxBasis": {
    "_tag": "calculated",
    "treatment": "domestic",
    "country": "AU",
    "class": "follows-goods",
    "rateBps": 0
  },
  "number": "SO-00001",
  "serial": 1,
  "status": "open",
  "lines": [
    {
      "id": "lin_01a15ad0-a3d4-7e5f-9a6b-7c8d9e0f1a23",
      "sku": "MUG-SPECKLED",
      "name": "Speckled stoneware mug",
      "ordered": 4,
      "removed": false,
      "kind": "stock",
      "outsideCatalogs": true,
      "discountCents": 0,
      "discountKind": "amount",
      "allocated": 4,
      "picked": 0,
      "packed": 0,
      "dispatched": 0,
      "invoiced": 0,
      "returned": 0,
      "unitPriceCents": 2400,
      "priceOverride": {
        "by": {
          "_tag": "user",
          "id": "usr_01a15ad0-a1b2-7c3d-8e4f-5a6b7c8d9e01"
        },
        "at": "2026-10-21T01:10:33.484Z"
      },
      "inclusive": true,
      "taxBasis": {
        "_tag": "calculated",
        "treatment": "domestic",
        "country": "AU",
        "parts": [
          {
            "class": "standard",
            "rateBps": 0,
            "weight": 1
          }
        ]
      },
      "orderDiscountCents": 0,
      "tax": {
        "inclusive": true,
        "amountCents": 9600,
        "entries": [
          {
            "class": "standard",
            "treatment": "domestic",
            "country": "AU",
            "rateBps": 0,
            "netCents": 9600,
            "taxCents": 0,
            "source": "manifold"
          }
        ],
        "netCents": 9600,
        "taxCents": 0,
        "grossCents": 9600
      },
      "commission": {}
    }
  ],
  "workflow": {
    "paymentTerms": "on-account",
    "pick": "manual",
    "pack": "auto",
    "ship": "manual",
    "invoice": "off",
    "shortfall": "wait",
    "allocation": "single-site-preferred",
    "routing": {
      "order": "rank",
      "decider": "manifold",
      "priority": []
    },
    "routingByCatalog": {},
    "quoteMode": "quotes",
    "requireCustomer": true,
    "marginPolicies": {}
  },
  "paymentTermsBy": "tenant",
  "createdSequence": 0,
  "shipments": [
    {
      "id": "shp_01a15ad0-a4e5-7f6a-8b7c-8d9e0f1a2b34",
      "number": "SH-00001",
      "reference": "auto:ord_01a15ad0-c1a0-7b2c-8d3e-4f5a6b7c8d9e:1",
      "status": "pending",
      "locationId": "loc_01a15ad0-a5f6-7a7b-9c8d-9e0f1a2b3c45",
      "lines": [
        {
          "lineId": "lin_01a15ad0-a3d4-7e5f-9a6b-7c8d9e0f1a23",
          "sku": "MUG-SPECKLED",
          "quantity": 4
        }
      ],
      "cartons": [],
      "createdAt": "2026-10-21T01:10:33.484Z",
      "updatedAt": "2026-10-21T01:10:33.484Z"
    }
  ],
  "invoices": [],
  "refunds": [],
  "payments": [],
  "notes": [],
  "edits": [],
  "consignments": [],
  "links": [],
  "costs": [
    {
      "costId": "cost_01a15ad0-e9c0-7551-91df-0a1b2c3d4e5f",
      "amountCents": 4500,
      "currency": "AUD",
      "fx": {
        "currency": "AUD",
        "home": "AUD",
        "rate": 1,
        "rateDate": "2026-10-21",
        "source": "same"
      },
      "reason": "Courier to redeliver after a failed first attempt",
      "accountCode": "6300",
      "date": "2026-10-21",
      "recordedBy": {
        "_tag": "user",
        "id": "usr_01a15ad0-a1b2-7c3d-8e4f-5a6b7c8d9e01"
      },
      "recordedAt": "2026-10-21T01:10:35.822Z"
    }
  ],
  "marginApprovals": [],
  "money": {
    "subtotalCents": 9600,
    "charges": {
      "shippingCents": 0,
      "shippingDiscountCents": 0,
      "discountCents": 0
    },
    "discountCents": 0,
    "tax": {
      "netCents": 9600,
      "taxCents": 0,
      "grossCents": 9600,
      "breakdown": [
        {
          "class": "standard",
          "treatment": "domestic",
          "country": "AU",
          "rateBps": 0,
          "exempt": false,
          "taxableCents": 9600,
          "taxCents": 0
        }
      ]
    },
    "totalCents": 9600,
    "paidCents": 0,
    "refundedCents": 0,
    "balanceCents": 9600,
    "refundOwedCents": 0,
    "status": "unpaid"
  },
  "discounts": [],
  "shortfalls": [],
  "routing": [
    {
      "lineId": "lin_01a15ad0-a3d4-7e5f-9a6b-7c8d9e0f1a23",
      "locationId": "loc_01a15ad0-a5f6-7a7b-9c8d-9e0f1a2b3c45",
      "routedBy": "rank"
    }
  ],
  "createdAt": "2026-10-21T01:10:33.484Z",
  "updatedAt": "2026-10-21T01:10:35.822Z"
}

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.
`OrderLineNotFound` orderId, lineId	No such record in this organization.	Check the id in the path or the body.

`409`

Refusal	What it means	What to do
`OrderNotOpen` orderId, status	The order is cancelled, closed or still a quote, so it takes no more of this. `status` says which.	Read the order before doing anything else.
`AccountNotPostable` accountCode, reason	The request was refused. `reason` says why.	Nothing changed. Read the record, then decide.
`CostCurrencyRefused` currency, allowed	The request was refused, and nothing changed.	Nothing changed. Read the record, then decide.
`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

Journal an additional cost on an order, step 7: Try to charge it to accrued costs
Journal an additional cost on an order, step 8: Journal the redelivery
Journal an additional cost on an order, step 9: Send it again