> ## Documentation Index > Fetch the complete documentation index at: https://docs.arcuserp.com/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve a purchase order's landed costs > Every landed allocation that reached this purchase order's receipts, with its inventory and COGS share, and per line the goods cost, landed cost and landed unit cost. It reveals inventory cost and cost of goods sold, so it requires the margin permission; no API scope grants it today, so an API key is refused 403 margin_permission_required (the same answer as a user without the permission). ## OpenAPI ````yaml /openapi.yaml get /purchase-orders/{id}/landed-costs openapi: 3.1.0 info: title: Arcus ERP Public API version: 1.0.0 description: > Arcus ERP public REST API. Designed for external integrations and data migration. **Authentication.** Bearer token (API key) via the `Authorization` header. Format: `Authorization: Bearer ark_live_ent__` (or `ark_test_*` for sandbox). API keys are issued per-entity in **Settings > Developers > API Keys**. **Entity scoping.** The entity is encoded in the API key prefix; routes are flat (e.g. `/v1/accounts`, `/v1/orders`, `/v1/products`). A small set of platform endpoints (migration, reconciliation, events, webhook endpoints, API keys) use the `/v1/entities/{entity_id}/...` form -- those are noted in their tags. **Key capabilities.** - Related-resource hydration via `?expand[]=` (see `x-arcus-expand` on each resource). - Cursor-based pagination (`starting_after` / `ending_before` / `limit`). - Idempotency via the `Idempotency-Key` header. - Webhook events for asynchronous notification. - Conditional requests / ETag for cache validation. **Changelog.** Entries are dated and name every published contract whose MEANING moved, not only the ones whose field names changed. The narrative version of the same entries, written for integrators, is published at https://arcuserp.mintlify.app/changelog. **October 2026: the order status values are the ones the API sends.** The `Order` schema's `order_status`, `payment_status`, `fulfillment_status` and `document_type` now list the values the order endpoints actually return (`order_status`: draft, open, processing, fulfilled, cancelled, archived, expired, awaiting_ach_clearance; `payment_status`: unpaid, partial, processing, paid, refunded, terms, overdue, overpaid, partially_refunded; `fulfillment_status`: unfulfilled, partial, fulfilled, backordered, awaiting_pickup; `document_type` adds late_fee_invoice). The values themselves did not change; the schema had listed names the API never sends (`confirmed`, `partially_paid`, `partially_fulfilled`, `voided`, `on_hold`), so a client generated from it could reject a real order. On `POST /v1/orders`, `order_status` is limited to `draft` only for a `sales_order` or `invoice`. The refusals of the order, refund, settings and deposit endpoints are now listed with their `code` values on each response. **October 2026: a pair of bank lines in transit at a month end is an open item there.** `GET /v1/entities/{entity_id}/reconciliation/account-audit`, `answers.books_against_bank`, each `month_ends` row: when the two bank lines of a pair matched together to one bill payment (a wire and its return) fall on either side of that date, `bank_unbooked_amount` and `bank_unbooked_count` now include the line already in the bank, and `gl_uncleared_amount` and `gl_uncleared_count` include the payment's bank leg; `explained_by_open_items` therefore explains that date instead of leaving the part in transit unexplained. No field is renamed and no other date moves; once both lines are in the bank the pair counts nowhere, as every other match. **2026-09-22 (planned 2026-09-21), REORDER-BUYER-TRUTH: demand changed what it MEANS on three published contracts, with no field renamed.** An integrator that pins field names sees no breakage and different numbers, which is why this entry exists. - **Demand now counts build consumption.** `demand_avg_per_day` on the public product, kit and inventory-balance objects, and `daily_demand` / `demand_basis` / `net_suggested_qty` on `GET /v1/purchasing/reorder-report`, are composed from fulfilled sales lines PLUS posted `build_consume` inventory draws: each physical decrement of a product counts exactly once. The previous rule adopted an internal-consumption basis only when the sales blend was exactly zero, so a product both sold AND consumed into work orders planned as if the build draws did not exist. Products drawn into work orders move; on one production-shaped dataset five did, the largest from 0.05/day to 14.95/day. - **`demand_basis` now carries four values, not two:** `sales`, `sales_and_builds`, `builds` and `consumption`. A consumer with a two-branch reader (anything that is not `consumption` is `sales`) silently hides the two new ones. - **`current_demand_units` on `GET /v1/inventory/balances/:id` moved, by a second rule.** It counts committed-but-unshipped CUSTOMER demand, and it now counts a kit component's own line rather than its parent kit line, and excludes non-sales documents. On one production dataset 269 of 1,043 balance rows changed, 227 of them downward; the largest single move was 1,941 to 25, on a product whose open PURCHASE order line had been reported as customer demand. Re-baseline anything that alerts or reorders off this field. - `run_rate_30/90/180/365` and `blended_daily` on the same balance object move for the first reason above. - **Added, not changed:** `GET /v1/purchasing/reorder-report` accepts `demand_window` and returns the unit, cover-through and reorder-point-provenance fields documented on that operation; `order_multiple` is accepted and returned on the product-vendor doors. - **Volume note.** The `inventory.low_stock`, `inventory.out_of_stock` and `inventory.back_in_stock` webhook events are population-gated on `on_hand <= reorder_point`, and reorder points move with the demand above, so subscribers should expect a one-time step change in event volume around the release. servers: - url: https://api.arcuserp.com/v1 description: Arcus ERP API (accepts both live `ark_live_*` and test `ark_test_*` keys) - url: https://dev-api.arcuserp.com/v1 description: >- Dev sandbox API (test-only data, accepts `ark_test_*` keys against dev RDS) security: [] paths: /purchase-orders/{id}/landed-costs: parameters: - name: id in: path required: true schema: type: string format: uuid get: tags: - Purchasing summary: Retrieve a purchase order's landed costs description: >- Every landed allocation that reached this purchase order's receipts, with its inventory and COGS share, and per line the goods cost, landed cost and landed unit cost. It reveals inventory cost and cost of goods sold, so it requires the margin permission; no API scope grants it today, so an API key is refused 403 margin_permission_required (the same answer as a user without the permission). operationId: getPurchaseOrderLandedCostsV1 responses: '200': description: The purchase order's landed costs. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/PurchaseOrderLandedCosts' '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' security: - ApiKeyAuth: [] components: schemas: PurchaseOrderLandedCosts: type: object description: >- A purchase order's landed costs (DESIGN D13): every landed allocation that reached its receipts (Case A, a landed-only bill naming the PO, a receipt-set bill on its receipts), each with its inventory share (what the layer and the layers its bump was followed into still hold now) and its COGS share (the rest), from the same plan a void runs; per PO line the units, goods cost at receipt, landed cost and landed unit cost; the landed bills; and the totals by category. Margin-grade throughout. properties: po_id: type: string format: uuid po_number: type: string allocations: type: array items: type: object properties: allocation_id: type: string format: uuid bill_id: type: string format: uuid bill_number: type: string bill_status: type: string vendor_id: type: string format: uuid vendor_name: type: string nullable: true category: type: string nullable: true basis: type: string nullable: true product_id: type: string format: uuid product_title: type: string nullable: true sku: type: string nullable: true location_id: type: string format: uuid nullable: true location_name: type: string nullable: true order_item_id: type: string format: uuid nullable: true receiving_transaction_id: type: string format: uuid nullable: true purchase_receipt_item_id: type: string format: uuid nullable: true receipt_reference: type: string nullable: true target: type: string enum: - layer - drop_ship description: >- layer, or drop_ship (a drop-ship receipt line: fifo_layer_id null, purchase_receipt_item_id set, inventory share 0). fifo_layer_id: type: string format: uuid nullable: true date: type: string format: date amount: type: number inventory_share: type: number cogs_share: type: number reversal_refusal: type: string nullable: true description: The code a void of this bill would answer now, if any. lines: type: array items: type: object properties: order_item_id: type: string format: uuid product_id: type: string format: uuid nullable: true product_title: type: string nullable: true sku: type: string nullable: true quantity_ordered: type: number quantity_received: type: number po_unit_cost: type: number nullable: true goods_cost: type: number description: >- The goods cost at receipt (the receipt items' quantity times unit cost). goods_revaluation: type: number description: >- The layers' per-unit goods change times the units received: layer_revaluation_per_unit (unrounded) times quantity_received, the change to the goods cost since receipt that the line's stock layers carry (a goods-bill revaluation, or any other later writer of a layer's cost); landed cost excluded. See goods_revaluation_posted for what the ledger posted, which spreads over the open units: where units left the layers before a goods bill, the two differ by the per-unit change on those units. Where the layers received every receipt item of the line (layer_received_qty equals quantity_received), goods_cost + goods_revaluation is the layers' goods value on the units received (their goods unit cost times quantity_received). On a line with stock layers the change is measured from the receipts that made those layers (see receipt_unit_cost), so units received with no layer at another price (a migrated or drop-ship receipt) are never a revaluation. 0 on a line with no stock layer. One exact quotient, rounded once to cents, half away from zero. goods_revaluation_posted: type: number nullable: true description: >- What the ledger posted to inventory for this line's goods-bill revaluations, live bills only: the revaluation snapshot on the line's own layers (inventory.bill_revaluation_allocations, applied_total_value_cents). A partial goods bill spreads its capitalizable variance over the units still open, so where units had left the layers before the bill this is smaller in size (nearer zero) than goods_revaluation (100 received, 40 written off, then 50 billed at 10.50 against 10.00: 25.00 posted, goods_revaluation 41.67); it also differs from goods_revaluation by any change another writer made to a layer's cost. A bill revalued before the snapshot existed (2026-07-29) reads the inventory line of its live revaluation entry, given to its one goods line with a price difference; on the lines of such a bill with two or more it is null when its entry put an amount on inventory (the entry kept no per-line split) and 0 when it put none. A bill's entry can differ from the sum of its lines by the cents the stock balance's revaluation carried beyond the layers. receipt_unit_cost: type: number nullable: true description: >- The receipt items' own unit cost, four decimals: their value over their units, unrounded (on a one-receipt line, purchase_receipt_items.unit_cost). On a line with stock layers, the receipt items of the receipts that made those layers (the receipt each layer's receiving transaction names), so a receipt item that made no layer, a migrated or drop-ship receipt, is not in it (30 at 326.97 layered beside 30 at 330.00 with no layer: 326.97, never their 328.4850 average); where a layer names no receipt, or those receipts hold no receipt item, every receipt item of the line. goods_unit_cost is goods_cost in cents over the units, so the two differ on a sub-cent price (7 at 0.0525: 0.0525 here, 0.0529 there). Null when nothing was received. Rounded once, half away from zero, from the exact quotient (an amount in ten-thousandths over an integer count of units), the same rule the landed-cost postings use. layer_revaluation_per_unit: type: number nullable: true description: >- The per-unit goods change the line's own layers carry: their goods unit cost (their goods value over the units they received, unrounded; layer_unit_cost less layer_landed_per_unit, within a ten-thousandth) less the receipt basis of receipt_unit_cost (unrounded), four decimals: 0 on a line received at two prices whose layers took one of them and no goods bill or other writer changed a layer's cost. receipt_unit_cost + layer_revaluation_per_unit is the layers' goods unit cost. 0 on a line with no stock layer; null when nothing was received. Rounded once, half away from zero, from the exact quotient (an amount in ten-thousandths over an integer count of units), the same rule the landed-cost postings use. layer_received_qty: type: number description: >- The units the line's own layers received (those whose receipt names this line). It differs from quantity_received where a receipt item made no layer (a migrated receipt: 60 received against a 30-unit layer) or units were given back after receipt; layer_received_qty x layer_unit_cost is what the layers hold at their unit cost. 0 on a line with no stock layer. landed_cost_other_layers: type: number description: >- The part of landed_cost that the line's own layers do not carry: a landed charge the line is attributed by product on another receipt's layer of the same product (a receipt that names no purchase-order line), or a drop-ship share on a line that has stock layers. It is in landed_cost and its three parts and not in layer_landed_per_unit, so the layers' landed cost is landed_cost - rounding - landed_cost_other_layers, exact to the other-layer share's own sub-cent rounding, which rounding also holds, and the layers' units (on a line with no stock layer, its units received) x layer_unit_cost = those units x (receipt_unit_cost + layer_revaluation_per_unit) + that, within the four-decimal rounding. landed_cost_drop_ship names the drop-ship part of it, so landed_cost_other_layers - landed_cost_drop_ship is the charge on another receipt's layers. landed_cost_drop_ship: type: number description: >- Of landed_cost_other_layers, the drop-ship shares: landed cost allocated to units of this line received drop-ship (a receipt item that made no stock layer: the allocation's target is drop_ship) on a line that also has stock layers. It carries its whole amount onto the units sold at the receipt (in sold_share, never rounding). 0 on a line with no stock layer, where a drop-ship share is the line's whole per-unit basis (in layer_landed_per_unit) and is never elsewhere. landed_cost_other_layers keeps every kind, so its identity is unchanged. layers: type: array description: >- The line's own stock layers, one per layer (those whose receiving transaction names this line: the same set layer_received_qty, layer_unit_cost and layer_landed_per_unit stand on), in the order received. On a line received in several receipts the line's per-unit figures are their average and cannot multiply out to the cent; each layer does: received_qty x unit_cost = value, to the cent. Where layer_received_qty equals quantity_received and landed_cost_other_layers is 0, the values sum to goods_cost + goods_revaluation + landed_cost - rounding, each figure rounded to the cent on its own. Empty on a line with no stock layer. items: type: object properties: fifo_layer_id: type: string format: uuid receipt_reference: type: string nullable: true description: >- The receipt the layer came from: its receiving transaction's reference number, else the receipt's own number (the allocations' receipt_reference rule). received_date: type: string format: date nullable: true received_qty: type: number description: >- The units the layer received (inventory.fifo_layers.received_qty). goods_unit_cost: type: number nullable: true description: >- The layer's unit cost less every landed stamp on it (the canonical receipt cost of a layer, a goods-bill revaluation kept in), four decimals. landed_per_unit: type: number nullable: true description: >- The landed stamps on the layer, per unit (each bill's four-decimal delta, summed), four decimals. goods_unit_cost + landed_per_unit = unit_cost wherever the goods cost is not floored at 0. unit_cost: type: number nullable: true description: >- The layer's own stored unit cost (inventory.fifo_layers.unit_cost), four decimals. value: type: number description: >- received_qty x unit_cost in dollars, the exact product rounded once to the cent, half away from zero (the extended-cost law the landed postings use). landed_cost: type: number goods_unit_cost: type: number nullable: true description: >- goods_cost per received unit, four decimals. Rounded once, half away from zero, from the exact quotient (an amount in ten-thousandths over an integer count of units), the same rule the landed-cost postings use. landed_cost_per_unit: type: number nullable: true description: >- landed_cost per received unit, four decimals. Rounded once, half away from zero, from the exact quotient (an amount in ten-thousandths over an integer count of units), the same rule the landed-cost postings use. 314.15 over 200 units is 1.5708. landed_unit_cost: type: number nullable: true description: >- Goods plus every landed cent per received unit, the rounding included; not the stock layer's unit cost (layer_unit_cost). Rounded once, half away from zero, from the exact quotient (an amount in ten-thousandths over an integer count of units), the same rule the landed-cost postings use. layer_landed_per_unit: type: number nullable: true description: >- The four-decimal unit-cost deltas the landed bills stamped on this line's own layers (those whose receipt names this line), per unit the layers received (per received unit on a line with no stock layer). A landed charge attributed to the line by product on a layer whose receipt names no purchase-order line is in landed_cost and its three parts, not here. Rounded once, half away from zero, from the exact quotient (an amount in ten-thousandths over an integer count of units), the same rule the landed-cost postings use. layer_unit_cost: type: number nullable: true description: >- The layers' own goods unit cost (receipt cost plus goods_revaluation per unit) plus layer_landed_per_unit: on a one-receipt line, the layer's own unit cost (inventory.fifo_layers.unit_cost). Rounded once, half away from zero, from the exact quotient (an amount in ten-thousandths over an integer count of units), the same rule the landed-cost postings use. inventory_share: type: number description: >- The line's landed cost still on hand (its allocations' inventory shares, summed). Each stock layer's share is the landed cost the bill stamped on it, in cents: the layer's integer quantity times the bill's stored four-decimal per-unit delta, exact, rounded once half away from zero; the cents the allocation entry posted and a void reverses. sold_share: type: number description: The line's landed cost carried on units since sold or used. rounding: type: number description: >- The cents a four-decimal unit cost cannot hold, posted to cost of goods sold by the allocation entries. inventory_share + sold_share + rounding = landed_cost. landed_bills: type: array items: $ref: '#/components/schemas/PurchaseOrderLandedBill' totals: type: object properties: goods_cost: type: number landed_cost: type: number inventory_share: type: number cogs_share: type: number unattributed_landed_cost: type: number by_category: type: array items: type: object properties: category: type: string amount: type: number PurchaseOrderLandedBill: type: object description: >- A landed bill that reaches a purchase order. Identity only on the purchase order itself; allocated_on_this_po only inside PurchaseOrderLandedCosts. properties: bill_id: type: string format: uuid bill_number: type: string vendor_id: type: string format: uuid vendor_name: type: string nullable: true bill_date: type: string format: date status: type: string mode: type: string enum: - case_a - po_landed - receipt_set description: >- case_a (goods and landed lines on a bill naming the PO), po_landed (a landed-only bill naming the PO) or receipt_set (a Case-B bill on this PO's receipts). categories: type: array items: type: string allocated_on_this_po: type: number description: Inside PurchaseOrderLandedCosts only. ErrorEnvelope: type: object description: | Canonical error response envelope. All API errors use this shape. required: - error - code properties: error: type: string description: Machine-readable error key example: not_found code: type: string description: Machine-readable error code (often same as error) example: not_found type: type: string enum: - validation_error - permission_error - not_found - conflict - rate_limit - internal - expand_error - not_implemented example: not_found hint: type: string description: Human-readable one-sentence explanation (English) example: >- The requested order does not exist or does not belong to this entity. param: type: string description: The parameter that caused the error, if applicable example: expand[0] required: type: string description: The scope required (only on insufficient_scope errors) example: accounts:read request_id: type: string description: >- Unique request ID for support tracing (maps to CloudWatch log stream) example: req_abc123 responses: Error: description: Error response (400/401/403/404/409/422/429/500) content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: ApiKeyAuth: type: http scheme: bearer description: | API key issued per entity via Settings > Developers > API Keys. Each key carries scopes (e.g. orders:read, products:write). Bearer token format: Authorization: Bearer ark_live_ent__ Test keys use ark_test_ent__. Both are issued per entity via Settings > Developers > API Keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.